Revise *.instructions.md: separate AI-relevant special knowledge from background information for contributors (#354)

Revising AI review instructions:
* Reduce context window use for AI review tools, by avoiding repeating common knowledge and API information that is (usually) part of the AI training datasets any way.
* Introduce a mechanism to maintain both parts in single files, to avoid "silent diversion" over time
* Adding a coderabbit path instruction that ensures cross-checking of both parts whenever a PR modifies instruction files

Objectives:
* Primary Goal: only inject content in AI-visible areas that are WLED-MM–specific or which deviate from general knowledge (the context window "token cost" of true false-positive suppressors is always worth it).
* Soft goal: keep each file's AI-facing section lean enough that the signal-to-noise ratio in the attention layer stays high — around 1,500–2,000 words per file type is a reasonable practical ceiling for current models.
* Aspirational: 500 words per file if achievable without sacrificing review quality.

This is an evolution of #353, based on the discussion in #353 (comment)

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: softhack007

.coderabbit.yaml

@@ -66,3 +66,19 @@ reviews:
         scoped to least privilege. Never interpolate github.event.* values directly
         into run: steps — pass them through an env: variable to prevent script
         injection. Do not use pull_request_target unless fully justified.
+
+    - path: ".github/*.instructions.md"
+      instructions: |
+        This file contains both AI-facing rules and human-only reference sections.
+        Human-only sections are enclosed in `<!-- HUMAN_ONLY_START -->` /
+        `<!-- HUMAN_ONLY_END -->` HTML comment markers and should not be used as
+        actionable review criteria.
+
+        When this file is modified in a PR, perform the following alignment check:
+        1. For each `<!-- HUMAN_ONLY_START --> ... <!-- HUMAN_ONLY_END -->` block,
+           verify that its examples and guidance are consistent with (and do not
+           contradict) the AI-facing rules stated in the same file.
+        2. Flag any HUMAN_ONLY section whose content has drifted from the surrounding
+           AI-facing rules due to edits introduced in this PR.
+        3. If new AI-facing rules were added without updating a related HUMAN_ONLY
+           reference section, note this as a suggestion (not a required fix).

.github/cicd.instructions.md

@@ -3,6 +3,12 @@ applyTo: ".github/workflows/*.yml,.github/workflows/*.yaml"
 ---
 # CI/CD Conventions — GitHub Actions Workflows
 
+> **Note for AI review tools**: sections enclosed in
+> `<!-- HUMAN_ONLY_START -->` / `<!-- HUMAN_ONLY_END -->` HTML comments contain
+> contributor reference material. Do **not** use that content as actionable review
+> criteria — treat it as background context only.
+
+<!-- HUMAN_ONLY_START -->
 ## YAML Style
 
 - Indent with **2 spaces** (no tabs)
@@ -60,6 +66,7 @@ schedule:
 - Name artifacts with enough context to be unambiguous (e.g., `firmware-${{ matrix.environment }}`)
 - Avoid uploading artifacts that will never be consumed downstream
 
+<!-- HUMAN_ONLY_END -->
 ---
 
 ## Security

.github/copilot-instructions.md

@@ -5,12 +5,19 @@ WLED-MM is a fork focused on higher performance (ESP32, ESP32-S3, PSRAM boards),
 
 Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
 
+> **Note for AI review tools**: sections enclosed in
+> `<!-- HUMAN_ONLY_START -->` / `<!-- HUMAN_ONLY_END -->` HTML comments contain
+> contributor reference material. Do **not** use that content as actionable review
+> criteria — treat it as background context only.
+
+<!-- HUMAN_ONLY_START -->
 ## Setup
 
 - Node.js 20+ (see `.nvmrc`)
 - Install dependencies: `npm ci`
 - PlatformIO (required only for firmware compilation): `pip install -r requirements.txt`
 
+<!-- HUMAN_ONLY_END -->
 ## Hardware Targets
 
 | Target | Status |
@@ -21,6 +28,7 @@ Always reference these instructions first and fallback to search or bash command
 | ESP32-P4/-C5/-C6 | Will be supported in the future |
 | ESP8266 | Deprecated — should still compile, but not actively maintained |
 
+<!-- HUMAN_ONLY_START -->
 ## Build and Test
 
 | Command | Purpose | Typical Time |
@@ -36,8 +44,15 @@ Common firmware environments: `esp32_4MB_V4_M`, `esp32_16MB_V4_S_HUB75`, `esp32S
 
 For detailed build timeouts, development workflows, troubleshooting, and validation steps, see [agent-build-instructions.md](agent-build-instructions.md).
 
+<!-- HUMAN_ONLY_END -->
 ## Repository Structure
 
+tl;dr: Firmware source: `wled00/` (C++). Web UI source: `wled00/data/`. Auto-generated headers: `wled00/html_*.h` — **never edit or commit**.
+Usermods: `usermods/` (`.h` files, included via `usermods_list.cpp`). Build targets: `platformio.ini`. CI/CD: `.github/workflows/`.
+
+<!-- HUMAN_ONLY_START -->
+Detailed overview:
+
 ```text
 wled00/                 # Firmware source (C++)
   ├── data/             # Web UI source (HTML, CSS, JS)
@@ -57,7 +72,7 @@ tools/cdata-test.js     # Test suite
 package.json            # Node.js scripts and release ID
 .github/workflows/      # CI/CD pipelines
 ```
-
+<!-- HUMAN_ONLY_END -->
 Main development branch: `mdev`
 
 ## General Guidelines
@@ -68,7 +83,7 @@ Main development branch: `mdev`
 - **When unsure, say so.** Gather more information rather than guessing.
 - **Acknowledge good patterns** when you see them. Summarize good practices as part of your review - positive feedback always helps.
 - **Provide references** when making analyses or recommendations. Base them on the correct branch or PR.
-- **Look for user-visible "breaking" changes**. Ask for confirmation that these were made intentionally.
+- **Look for user-visible breaking changes and ripple effects**. Ask for confirmation that these were introduced intentionally.
 - **Unused / dead code must be justified or removed**. This helps to keep the codebase clean, maintainable and readable.
 - **C++ formatting available**: `clang-format` is installed but not in CI
 - No automated linting is configured — match existing code style in files you edit. See `cpp.instructions.md` and `web.instructions.md` for language-specific conventions, and `cicd.instructions.md` for GitHub Actions workflows.
@@ -77,7 +92,8 @@ Main development branch: `mdev`
 Using AI-generated code can hide the source of the inspiration / knowledge / sources it used. 
 - Document attribution of inspiration / knowledge / sources used in the code, e.g. link to GitHub repositories or other websites describing the principles / algorithms used.
 - When a larger block of code is generated by an AI tool, mark it with an `// AI: below section was generated by an AI` comment (see C++ guidelines).
-- Make sure AI-generated code is well documented.
+- Every non-trivial AI-generated function should have a brief comment describing what it does. Explain parameters when their names alone are not self-explanatory.
+- AI-generated code must be well documented; comment-to-code ratio > 15% is expected. Do not rephrase source code, but explain the concepts/logic behind the code.
 
 ### Pull Request Expectations