# 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.