Generate website reference documentation from `xmd` CLI output

[taras]

Story

As someone using Executable.md, I want the website reference to be generated
from the released product, so its component catalog, command documentation, and
displayed version remain complete and consistent.

What the website shows

The website combines two kinds of documentation:

1. Released product reference comes from the latest published xmd release.
   It includes the component catalog, command reference, displayed version, and
   link to that exact GitHub Release.
2. Authored documentation comes from current main. It includes guides,
   recipes, navigation, layout, and other editorial content.

A site-only or documentation change may publish without creating another
product release. It reuses the latest released reference and must remain
truthful for that release. Documentation for unreleased behavior remains
separate and cannot appear as a stable product claim.

The site does not maintain another component list, command list, flag list, or
release-version string.

Example release update

For release vX.Y.Z, the release workflow:

1. builds and verifies the release candidate;
2. runs that exact candidate to collect its component catalog, command help, and
   version;
3. creates and verifies a deterministic reference snapshot;
4. verifies every stable recipe with the same candidate;
5. prepares the complete website from the tagged source and verified snapshot;
6. publishes the GitHub Release and its snapshot; and
7. promotes the already prepared site.

The resulting website displays vX.Y.Z, links to that exact release, and
documents the same binary that was published.

If generation, verification, recipe testing, or site preparation fails, neither
the release nor the website is published.

Example documentation update

For a guide, recipe, renderer, navigation, or layout change on main, the
website workflow:

1. resolves the latest published release;
2. downloads and verifies its reference snapshot;
3. verifies stable recipes with that release's binary;
4. combines the released reference with the current authored documentation; and
5. deploys the resulting site without changing the released product reference.

Immediately before deployment, the workflow confirms that its selected release
is still the latest published release. A stale build refuses instead of
overwriting a site prepared for a newer release.

Executable documentation program

An executable Markdown program provides documented targets for generating the
reference, verifying it, and building the website. Its rendered output explains
what each target did and what it produced.

Markdown owns sequencing, command capture, refusals, artifact production, and
verification policy. TypeScript is limited to typed parsing, comparison,
classification, and formatting. Shell only invokes programs.

Component reference

Generate the public component reference from xmd syntax.

• Inspect the released standard component catalog without discovering
  repository-local components such as this repository's AGENTS components.
• Include every built-in category and every catalog field needed to use a
  component: description, forms, props, captures, body context, return contract,
  and origin.
• Preserve the catalog's meaningful ordering.
• Explain how someone can inspect their own effective catalog with --include
  without presenting those additional components as product built-ins.
• Refuse the complete generation when syntax inspection fails. Never publish a
  partial catalog.

Command reference

Generate command syntax and options from the selected binary's own help output.

• Cover the root command and the public run, plan, test, syntax, and
  workflow commands.
• Explain each command in reader-facing Markdown rather than publishing an
  unexplained help dump.
• Explain document-aware xmd run <document> --help separately from generic
  command help.
• Describe workflow actions using the grammar the product actually ships.
• Detect a newly public command that the generated reference failed to include.

Released reference snapshot

Attach one reference snapshot to every published GitHub Release:

website-reference-vX.Y.Z.tar.gz
├── release.json
├── catalog.json
├── components.md
├── cli.md
└── cli/
    ├── root.txt
    ├── run.txt
    ├── plan.txt
    ├── test.txt
    ├── syntax.txt
    └── workflow.txt

The archive is a release artifact. It is not a checked-in generated copy and is
not bundled into the xmd executable.

Generate it at the tagged revision with the exact released
x86_64-unknown-linux-gnu binary. release.json records:

• snapshot schema version;
• release tag and URL;
• source commit;
• binary asset and reported version;
• catalog version; and
• content digests.

Normalize archive paths, entry order, modes, ownership, and timestamps so the
same inputs produce the same bytes. Add the archive digest to the release
checksums.

A release rerun may reuse an existing byte-identical snapshot. It refuses a
conflicting snapshot and never silently replaces documentation already attached
to a published release.

Keep the raw component catalog and command help beside their generated Markdown.
They provide completeness evidence and allow later releases to compare public
surfaces without rebuilding an old checkout.

Website rendering

The release snapshot contains Markdown, not rendered HTML. The website may
improve its presentation without changing which product revision the Markdown
describes.

During the site build, a dedicated documentation renderer:

• renders the tables, headings, paragraphs, links, lists, blockquotes, and fenced
  code emitted by the generators;
• gives headings stable fragment links;
• preserves only the language classes needed to style code;
• disables raw HTML;
• sanitizes the rendered result before serialization; and
• bundles the sanitized result into the site.

The deployed server does not read documentation files, inspect releases, or
regenerate reference material while handling a request.

This renderer is separate from the stricter WebForm renderer used for untrusted
interactive document output.

Executable recipes

Publish task-oriented recipes from main as canonical runnable Markdown files.
The page, copied source, downloaded source, and verified source are the same
bytes.

Each recipe:

• begins with the task outcome;
• explains prerequisites and important effects before they occur;
• states its required inputs and permissions;
• gives the exact xmd invocation; and
• includes validated metadata for its title, summary, route, and compatibility.

Generate recipe navigation from that metadata rather than another maintained
list.

The site build renders component syntax as inert source and never executes a
recipe. Verification uses temporary state, scripted answers, and fake or local
providers rather than performing production effects.

For a documentation deployment, verify every stable recipe with the latest
released binary. For a release, verify every stable recipe with the exact
candidate binary. A recipe requiring unreleased behavior remains outside the
stable index.

A candidate that breaks a stable recipe cannot become the latest release. The
workflow reports every failing recipe and preserves the existing release and
website until the recipe or product is corrected.

Publication and recovery

GitHub Actions is the only production deployment path. Disable the separate
Deno Deploy Git integration so every deployment can prove which released
reference and recipe evidence it contains.

Release and main deployments share one production concurrency group. Two
builds cannot promote simultaneously.

Every deployment records:

• site source commit;
• released reference tag and snapshot digest;
• recipe-evidence identity; and
• complete built-artifact digest.

Generation and building require no deployment credentials. Only the final
promotion job receives them.

Failure or cancellation before promotion leaves the existing website intact.
The promoted site uses one immutable, verified build artifact.

GitHub Release publication and website promotion cannot be one transaction.
All other fallible work therefore finishes before publishing the release. If
promotion then fails, the release remains published, the previous website stays
available, and the same verified site artifact can be promoted again. The
workflow never deletes or rewrites the release to hide that failure.

A missing production deployment configuration is a failure, not a successful
skip.

Acceptance

• The executable Markdown program owns reference generation and verification
  policy.
• Component documentation contains every standard catalog entry exactly once
  and no repository-local component.
• Command documentation covers every public command and obtains syntax and flags
  from the selected binary.
• The website maintains no duplicate component, command, flag, or release-version
  inventory.
• The displayed version agrees with the selected binary and links to its exact
  release.
• Every release carries one deterministic, checksummed reference snapshot that
  identifies its tag, commit, binary, and contents.
• A conflicting snapshot, version mismatch, incomplete reference, or failed
  verification refuses publication.
• Generated Markdown renders safely with stable heading links and no active raw
  markup.
• The website bundles verified documentation at build time and does no
  request-time reference lookup or generation.
• Every stable recipe has one canonical source and passes against the released
  or candidate binary the site presents.
• A broken stable recipe withholds a release or documentation deployment.
• GitHub Actions serializes every production promotion and prevents a stale
  main build from overwriting a newer release deployment.
• Every deployment records enough identity to associate the site, released
  reference, recipe evidence, and built artifact.
• Failure before promotion leaves the existing website intact; failure after
  release publication supports retrying the same verified site artifact.
• Release configuration and specs/release-process-spec.md describe the same
  publication lifecycle.

Out of scope

• Evaluating or changing xmd plan; Refine xmd plan against hand-authored reference workflows #679 owns that evaluation.
• Treating generated Plans as authority for this production workflow.
• Hand-authoring information already exposed by xmd syntax, command help, or
  the selected release.
• Publishing repository-local components as standard built-ins.

Related work

• Refine xmd plan against hand-authored reference workflows #679 compares xmd plan output with this settled production contract. That
  evaluation does not block or redefine this work.

[taras]

Follow-up evaluation is tracked by #679. It uses this issue as its settled oracle and does not block or redefine the production workflow.