feat: mine reusable AeroSim channel lessons

references/diagrams-drawio-canonical-compliance.md

@@ -0,0 +1,91 @@
+# Canonical Draw.io Compliance for C4 Architecture
+
+Use this reference whenever an Architecture change creates, rewrites, or reroutes editable `.drawio` sources.
+
+## Authority and provenance
+
+1. Resolve the canonical global skill from `https://gitea.lego-cloud.eu/home-v1-skills-code-agent/diagrams-drawio`.
+2. Fetch its remote default/test ref and record the exact full commit. Do not treat an unversioned work copy or an old reference directory as authoritative.
+3. Read `SKILL.md` plus `references/capabilities.md`, `rules-layout.md`, `rules-style.md`, and `routing-best-practices.md` before editing.
+4. Ask the installed CLI for its actual supported actions with `node scripts/dist/cli/commands.js --help`. If prose and CLI action names differ, use the current CLI names and disclose the documentation drift; never silently skip a requested gate.
+
+## C4 wording contract
+
+- C1 is the System Context view.
+- C2 identifies containers.
+- C3 opens one selected C2 container and shows components inside it.
+- A C3 page does not turn its subject container into a component.
+- Prefer explicit titles such as `Web Application — Container` and `Web Application Container — C3 Component View`.
+- The container registry is navigation over C2 containers and their C3 views; it is not itself a C4 level and must not be called `Containers (C3)`.
+
+## Source invariants
+
+For every governed diagram:
+
+- preserve editable native mxGraph XML;
+- use `rounded=0`;
+- keep all relationship edges on root layer `parent="1"`;
+- forbid `exitX`, `exitY`, `entryX`, `entryY`, `exitDx`, `exitDy`, `entryDx`, and `entryDy` style pins;
+- use orthogonal routes and explicit waypoints only where needed;
+- place vertex `x`, `y`, `width`, and `height` on the canonical 40pt grid;
+- use a 40pt minimum gap and uniform sibling-row/column spacing;
+- keep labels concise (normally at most 80 characters) and move detailed behavior to surrounding prose/tables;
+- retain square C4 boundaries and visibly separate source-observed elements from target/unimplemented elements;
+- do not add relationships merely to eliminate an intentional orphan.
+
+Add repository-level fail-closed checks for invariants the global CLI does not enforce. Mutation-test these checks—for example, change one vertex from `x=40` to `x=20` and require validation to fail.
+
+## Canonical CLI gate
+
+Run the current CLI against every changed diagram. At the time this workflow was learned, the supported quality actions were:
+
+```text
+validate
+page-connectors-summary
+page-connectors-validation
+page-labels-validation
+page-shape-bbox-validation
+page-orphans
+page-recommendations
+page-hierarchy-full
+page-negative-space-summary
+```
+
+Use `task validate -- --file=<path>` when the canonical Task wrapper is available. If the wrapper executable is unavailable but the skill explicitly documents the built Node entry point, invoke `node scripts/dist/cli/commands.js --file <path> --action validate` and the supported quality actions directly. This is an entry-point substitution, not permission to invent replacement checks.
+
+Required acceptance targets:
+
+- valid XML/mxGraph compilation;
+- zero connector crossings;
+- zero single-port violations;
+- zero corner-port violations;
+- zero header-edge violations;
+- zero leaf-shape connector overlaps;
+- zero shape bounding-box overlaps;
+- zero empty, duplicate, or overlong labels;
+- no forbidden port pins or nested edges.
+
+Connector/shape diagnostics involving only the containing system or swimlane boundary are structural boundary crossings. Report them separately from leaf-shape overlaps; do not call every raw overlap total a blocker.
+
+## Visual QA after machine gates
+
+Render every affected route through the real Docusaurus production build and inspect it in the browser. Machine-clean geometry can still look poor. Check specifically for:
+
+- long edge prose rendered too small;
+- large perimeter detours introduced only to satisfy fan-in/fan-out rules;
+- multiple labels crowding a shared corridor;
+- overlapping final connector segments that make source attribution ambiguous;
+- labels crossing boxes or headers;
+- C2 container versus C3 component wording ambiguity;
+- source-observed and target/unimplemented regions blending together.
+
+Prefer moving external actors into aligned lanes, using a shared same-side fan-in/fan-out point, shortening edge labels, and positioning edge labels on distinct route legs. Rerun all machine gates after each visual correction.
+
+## Review and publication
+
+1. Run repository validators, tests, TypeScript, strict production build, production audit policy, and `git diff --check` on the exact final diff.
+2. Obtain independent fail-closed review that reads the canonical skill and distinguishes parent-boundary diagnostics from real leaf defects.
+3. Fix every blocker and request a fresh review; a pre-fix pass is stale.
+4. Refresh the default branch after review. Rebase safely and rerun exact-head validation if it moved.
+5. When delivery requires a PR, do not stop at a local commit or rebase. Push, open the PR, return the real URL/head, verify exact-head CI, merge when authorized, and verify integrated-head CI.
+6. State publication layers precisely: local, pushed branch, open PR, exact-head CI, merged, integrated-head CI, and deployed page-body verification.