Refactor template.md: Add TOC, consolidate duplications, reduce by 31%

[Copilot]

The template lacked navigability and contained significant duplication across Best Practices, testing guidance, and code examples. This refactoring reorganizes content for both human comprehension and Copilot efficiency.

Changes

• Added comprehensive Table of Contents with anchor links to all major sections
• Restructured sections in logical progression: Context → Quality → Testing → Development → Admin UI → Documentation → CI/CD
• Removed duplications:
  • Consolidated 4+ scattered "Best Practices" sections into unified Development Best Practices
  • Merged duplicate testing guidance from Testing and CI/CD sections
  • Eliminated redundant code examples (retained one canonical example per pattern)
  • Fixed duplicate "WORK IN PROGRESS" sections in changelog examples
• Streamlined content: Reduced from 1,064 → 730 lines (31%) by:
  • Converting verbose paragraphs to bullet points
  • Trimming redundant explanations
  • Using cross-references instead of content repetition
• Enhanced readability: Added visual separators, emoji callouts (✅ ❌ 📝), and consistent heading hierarchy

Example: Before vs After Structure

Before (v0.5.2):

Testing → README → Dependency Updates → JSON-Config → Translation → 
Best Practices (Dependencies) → Error Handling → Code Style → 
Best Practices (ESLint) → CI/CD → Best Practices (Testing)

After (v0.5.3):

## 📑 Table of Contents

1. [Project Context](#project-context)
2. [Code Quality & Standards](#code-quality--standards)
3. [Testing](#testing) — consolidated unit/integration/API
4. [Development Best Practices](#development-best-practices) — unified
5. [Admin UI Configuration](#admin-ui-configuration)
6. [Documentation](#documentation)
7. [CI/CD & GitHub Actions](#cicd--github-actions)

All technical content preserved. Version bumped to 0.5.3 with CHANGELOG updated.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>refactor copilot instruction</issue_title>
<issue_description>refactor complete template, add an index to show and easily navigate truth the different section, remove duplications and make it easy human readable but efficient and effective for copilot.</issue_description>

<agent_instructions>use best possible model for human readable language but ensure file stays efficient and effective for copilot</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes refactor copilot instruction #84

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR refactors the template.md file to improve organization, readability, and efficiency. The refactoring consolidates duplicate content, adds comprehensive navigation through a Table of Contents, and streamlines verbose explanations while maintaining technical accuracy. The changes align with issue #84's request to make the template more human-readable while remaining effective for Copilot.

Changes:

• Added comprehensive Table of Contents with anchor links and emoji icons for improved navigation
• Restructured content into logical sections: Context → Quality → Testing → Development → Admin UI → Documentation → CI/CD
• Removed duplicate Best Practices sections, redundant testing guidance, and duplicate WORK IN PROGRESS changelog examples
• Reduced file size by 31% (1064→730 lines) through streamlining while preserving all critical technical content
• Enhanced readability with consistent visual hierarchy, separators, and checkmark/cross icons for guidelines

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
template.md	Major refactoring with TOC addition, section reorganization, duplicate removal, and streamlined examples (31% size reduction)
package.json	Version bump from 0.5.2 to 0.5.3
config/metadata.json	Version bump for both main version and template version to 0.5.3
README.md	Updated version reference to 0.5.3
CHANGELOG.md	Added detailed changelog entries for version 0.5.3 documenting all refactoring changes
.github/copilot-instructions.md	Version bump to 0.5.3

[Copilot]

The await harness.stopAdapter() call on line 287 is unreachable code. It's placed after the if/else block that either calls resolve() or reject(), which will exit the promise. This line should be moved inside the if block before resolve(true), or better yet, use a finally block or ensure cleanup happens regardless of test outcome. Otherwise, the adapter may remain running if the test passes.

[Copilot]

The CHANGELOG entries for version 0.5.3 don't include a reference to issue #84, even though the PR description mentions "Fixes #84". According to the repository's Pull Request Guidelines, changelog entries should reference related issues using format like "(fixes #XX)" or "(solves #XX)". Consider adding "(Fixes #84)" to one of the changelog entries, preferably the first or most relevant entry.

[Copilot]

The encryptPassword helper implements a custom XOR-based cipher using systemConfig.native.secret to "encrypt" API passwords, which provides only weak obfuscation and is not cryptographically secure for protecting credentials at rest. An attacker with access to the config files and secret (both typically stored on the same system) can reliably recover the plaintext password, leading to potential compromise of external API accounts. This pattern should be clearly documented as compatibility-only with ioBroker's existing mechanism and avoided for any new credential storage; where possible, migrate to a standard, strong encryption or password-handling scheme instead of custom XOR-based logic.

Suggested change

	async function encryptPassword(harness, password) {
	const systemConfig = await harness.objects.getObjectAsync("system.config");
	if (!systemConfig?.native?.secret) {
	throw new Error("Could not retrieve system secret for password encryption");
	}
	const secret = systemConfig.native.secret;
	let result = '';
	for (let i = 0; i < password.length; ++i) {
	result += String.fromCharCode(secret[i % secret.length].charCodeAt(0) ^ password.charCodeAt(i));
	}
	return result;
	// NOTE: This uses ioBroker's built-in password handling for compatibility with
	// existing adapters. It only provides weak obfuscation and MUST NOT be used
	// as a general-purpose encryption scheme for new credential storage.
	const { tools } = require("@iobroker/adapter-core");
	async function encryptPassword(harness, password) {
	const systemConfig = await harness.objects.getObjectAsync("system.config");
	if (!systemConfig?.native?.secret) {
	throw new Error("Could not retrieve system secret for password encryption");
	}
	// Delegate to ioBroker's official helper instead of reimplementing XOR logic
	return tools.encrypt(systemConfig.native.secret, password);