documentation-docusaurus/references/generated-evidence-registries.md

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.