docs: preserve active documentation guidance

SKILL.md

@@ -187,8 +187,18 @@ Load the one that matches the task. Don't read all four.
 | Touch `docusaurus.config.ts` | [references/config-reference.md](references/config-reference.md) — the options that matter, sensible defaults, config anti-patterns |
 | Build or maintain a local YAML database that feeds React components and MDX | [references/local-yaml-data-database.md](references/local-yaml-data-database.md) — dedicated entity folders, `.yml` schemas, indexes, relationships, build-time loading, typed hooks, and validation |
 | Onboard or render an editable `.drawio` source | [references/drawio-source-diagrams.md](references/drawio-source-diagrams.md) — pnpm install, plugin registration, MDX raw-source import, viewer options, and verification |
+| Repair a docs section that builds but violates a required hierarchy or content contract | [references/architecture-ia-remediation.md](references/architecture-ia-remediation.md) — RED-first structure validation, approval-safe scaffolding, link pitfalls, browser checks, and remote PR/CI readback |
 | Ship the site, or debug a failing build | [references/deployment.md](references/deployment.md) — Vercel, Netlify, GitHub Pages, Cloudflare, and common failures |
 
+## Package-manager validation pitfall
+
+If `pnpm` is available only through `corepack`, `corepack pnpm validate` can still fail when the `validate` script invokes nested `pnpm` commands, because child scripts resolve `pnpm` from `PATH`. Before treating this as a repository failure, either:
+
+- add a trusted `pnpm` shim that executes `corepack pnpm "$@"` to `PATH`; or
+- run each validation script directly through `corepack pnpm`.
+
+Re-run the complete validator and production build after fixing command resolution. Do not report a successful build from the outer command alone.
+
 ## Getting Started
 
 Tell me:

references/architecture-ia-remediation.md

@@ -0,0 +1,42 @@
+# Architecture information-architecture remediation
+
+Use this workflow when a Docusaurus architecture section builds successfully but does not satisfy its required navigation or content contract.
+
+## Separate the three verdicts
+
+Audit and report these independently:
+
+1. **Structural compliance** — dedicated docs plugin/sidebar, exact ordering and nesting, stable document IDs, routes, and registry links.
+2. **Content completeness** — required C4 levels, registries, responsibilities, relationships, traceability, and explicit placeholders for gated decisions.
+3. **Build/render health** — structure validator, typecheck, strict broken-link production build, diagram-source validation, browser rendering, and console errors.
+
+A green build proves only build health. An autogenerated sidebar or matching headings inside one page does not prove structural compliance.
+
+## Safe remediation sequence
+
+1. Fetch the remote base branch and create a clean worktree/branch from its exact SHA.
+2. Encode the required hierarchy in a deterministic validator and run it once to prove RED.
+3. Replace autogenerated navigation with an explicit sidebar when semantic order matters.
+4. Add the smallest compliant pages and registries. If product/solution approval is absent, create visibly gated scaffolding rather than inventing requirements, decisions, tasks, interfaces, or versions.
+5. Keep editable `.drawio` sources beside the consuming architecture pages. Render them through `docusaurus-plugin-drawio` and MDX raw imports; do not substitute download links or static exports.
+6. Run the structure validator, Draw.io/XML validation, typecheck, strict-link production build, and `git diff --check`.
+7. Serve the production build and verify the actual sidebar nesting, representative routes, rendered diagram DOM, and browser console.
+8. Commit and push, open a reviewable PR, read back its head/base SHAs and changed-file list, and wait for the exact commit's CI status to reach a terminal state.
+9. Post one concise evidence message in the governing project channel with PR, commit, structure, validation, and remaining human gate.
+
+## Docusaurus link pitfall
+
+Docusaurus may resolve a source-relative link such as `./containers` from the generated page route (`/architecture/overview/`) rather than from the source-file directory, producing `/architecture/overview/containers/`. For links between sibling architecture documents, prefer explicit site-root routes such as `/architecture/containers/` and `/architecture/features/<id>/overview/`, then let the production build's broken-link check verify them.
+
+Do not weaken `onBrokenLinks` or broken-Markdown-link handling to make remediation pass.
+
+## Verification evidence to retain
+
+- base branch and SHA;
+- feature branch and commit SHA;
+- validator output;
+- strict production-build result;
+- Draw.io validation result for every edited source;
+- browser evidence for sidebar hierarchy and representative rendered diagram;
+- zero relevant console/JavaScript errors;
+- PR URL, mergeability, exact remote head SHA, and terminal CI result.