feat: merge Docusaurus and Gitea documentation skills

2026-08-14 12:32:08 +00:00
parent cfb006d7ea
commit b08614dc90
28 changed files with 4202 additions and 1 deletions
@@ -0,0 +1,40 @@
+# Generated evidence registries in Docusaurus
+
+Use this pattern when a canonical Markdown corpus must also expose a cross-client registry such as systems, products, suppliers, or services.
+
+## Preserve the canonical layer
+
+- Keep client/source Markdown and its validator authoritative.
+- Generate ignored MDX copies and registry pages at build time.
+- Never edit generated pages to improve evidence; improve canonical table rows and regenerate.
+- Emit a machine-readable registry JSON alongside human-readable pages.
+
+## Conservative identity model
+
+1. Parse only the canonical, schema-defined table under the expected heading.
+2. Preserve every source observation with client ID, client route, relationship, meaning/context, contractor, evidence, and confidence.
+3. Normalize case, whitespace, dashes, and Markdown decoration for matching only; preserve observed labels for display.
+4. Maintain explicit reviewed alias rules in durable source data. Merge only unmistakable product/shared-service identities.
+5. Keep composite labels separate unless evidence proves their components and relationships.
+6. Scope generic labels such as “official website”, “institution portal”, or “virtual exhibition” to the client; identical wording across clients does not prove one shared system.
+7. Use stable hash-derived registry IDs/slugs so later insertions do not renumber established records.
+
+## Docusaurus integration
+
+- Use a separate `@docusaurus/plugin-content-docs` instance with its own `id`, generated path, route base, and sidebar file.
+- Include every docs-plugin route base in local-search configuration.
+- A flat sidebar can be produced by generating all docs into one directory and using `{type: 'autogenerated', dirName: '.'}`; range directories create folder categories.
+- Keep existing client slugs explicit when changing generated-directory layout.
+- Validate source rows, unique records, generated routes, observation totals, representative pages, JSON output, and search-index terms after the real production build.
+
+## Deployment verification behind authentication
+
+A successful Actions run is not sufficient. First prove `HEAD == origin/main` and that the run's `head_sha` matches. Then verify deployment.
+
+For an authentication-protected Pages ingress:
+
+- unauthenticated public `302` to the configured OAuth start path is expected, not a publish failure;
+- do not weaken or bypass authentication for users;
+- verify content through an authorized browser session or the internal static-site service/backend when operational access permits it;
+- check the homepage, one canonical dossier, registry index, one generated registry dossier, machine-readable JSON, and search index;
+- distinguish ingress/authentication changes from static publication failures before rolling back application code.