ci(gendoc): regenerate the catalog on PRs, gate breaking changes at release

[Reefact]

Summary

Wire the CI/CD generation angle #142 called for, using doc/generated/gendoc/ (created by #164/#165 as the living-documentation target). Two closed-loop pieces:

1. A dedicated workflow regenerates GenDoc's own Markdown catalog and an informational diff report on every pull request, committing both back onto the PR's own branch (never main) — the regenerated content goes through normal review, exactly like any other change.
2. release.yml gates the cli train release (GenDoc has no package of its own — it ships bundled inside fce): a breaking change to GenDoc's error catalog must be matched by a major version bump, or the release is refused. After a successful publish, the baseline is accepted and pushed to main — the one direct-to-main write in this design, and only ever after a deliberate, already-published release.

Type of change

• Bug fix
• New feature
• Breaking change
• Refactoring
• Analyzer / diagnostic change
• Tests
• Documentation
• Build / CI / tooling

Changes

• Add .github/workflows/gendoc-docs.yml: on pull_request (same-repo only — a fork PR gets a read-only token by GitHub's own default), builds fce + FirstClassErrors.GenDoc, regenerates doc/generated/gendoc/catalog/ (Markdown, split layout — wiped first so a removed error's page never lingers), runs fce catalog diff --report markdown --fail-on none against a committed baseline into doc/generated/gendoc/errors-diff.md (informational only, never blocks the PR), and commits both to the PR's own branch when changed.
• Bootstrap doc/generated/gendoc/errors-baseline.json and the initial catalog/diff content — neither existed before this PR, so fce catalog update explicitly accepts the current 16-error surface as the starting contract. Remove the now-redundant .gitkeep.
• Update doc/generated/README.md to describe the new gendoc/ sub-structure (catalog/, errors-baseline.json, errors-diff.md).
• release.yml, cli train only, before Pack: run fce catalog diff --fail-on breaking against the baseline; if breaking (exit 2) and the new tag's major component does not exceed the previous cli-v tag's, fail the release with a clear message. Runs on dry runs too. After a successful non-dry-run cli publish: fce catalog update refreshes the baseline and pushes it to main, best-effort (a push race degrades to a ::warning::, never fails an already-successful release).
• Record ADR-0010 ("Treat GenDoc's error catalog as a versioned contract", EN + FR) for the policy this enforces, and accept ADR-0009 ("Report the tooling's failures as first-class errors", drafted in Model GenDoc's own failures as documented first-class errors #163) alongside it since the two ship together.

Testing

• dotnet build FirstClassErrors.sln
• dotnet test FirstClassErrors.sln
• Analyzer tests pass (FirstClassErrors.Analyzers.UnitTests)

No source changed, so the suite is unaffected; ran a full solution build (-warnaserror, 0 warnings) as a sanity check. Verified for real: built fce + FirstClassErrors.GenDoc locally and ran the exact commands used by both workflows — fce generate --layout split (19 files, verified content), fce catalog update (baseline created, 16 errors), fce catalog diff --fail-on none (correctly reports "No catalog changes" against the fresh baseline). Validated the release-gate's version-comparison shell logic standalone against 6 scenarios (no breaking change; breaking + major bump; breaking + no major bump correctly failing; breaking on a train's first release; breaking + major bump with a pre-release suffix; an unexpected fce exit code correctly failing loud) — all matched the intended behavior. Confirmed fce catalog diff --fail-on breaking really returns exit code 2 on a simulated breaking change (a removed code) against a scratch baseline copy — no repository file touched by that check.

Documentation

• Public API / error documentation updated
• README / doc/ updated
• French translation updated if user-facing behavior changed
• No documentation change required

doc/generated/README.md's existing bullet for gendoc/ is extended, not rewritten; ADR-0010 is added in EN + FR; doc/handwritten/for-users/CatalogVersioning*.md already documents the underlying fce catalog commands this reuses verbatim, no new CLI behavior to document.

Architecture decisions

• No architectural decision in this pull request
• New decision recorded — ADR: ADR-0010 ("Treat GenDoc's error catalog as a versioned contract"). Accepted in this PR at the maintainer's explicit request, together with ADR-0009 (drafted Proposed in Model GenDoc's own failures as documented first-class errors #163) which this work completes.

Related issues

Closes #167
Refs #142

🤖 Generated with Claude Code

https://claude.ai/code/session_0148FgVG3MkKn2kudM2TkmGa