Problem
fce generate only creates files — it never deletes a stale one. An error removed from the code leaves its page orphaned in the output directory. The repository's own CI must rm -rf the catalog before regenerating, and the workflow comment admits why (gendoc-docs.yml:60-62); but users following TheHtmlRenderer.en.md or CatalogVersioningCI.en.md to publish their own living catalogs will accumulate ghost pages for removed errors — precisely the drift the tool exists to prevent — with no mention of the workaround in the user docs.
Impact
The living-docs promise silently degrades for every external adopter of the documented CI publishing loop.
Direction
- Preferred: a manifest-based prune (delete only files a previous generation wrote — safer than
rm -rf for shared output directories) or a --clean flag on directory output.
- At minimum: move the wipe-before-regenerate guidance from the workflow comment into
TheHtmlRenderer and CatalogVersioningCI (EN+FR).
- While in those pages: add the mandatory
--service-name to TheHtmlRenderer.en.md's two copy-paste examples, which currently fail as written.
Acceptance criteria
- Removing an error and regenerating leaves no orphaned page (or the docs state exactly what to wipe and why); the HTML-renderer examples run as pasted.
Context
Surfaced by the 2026-07-20 architecture, design & ecosystem audit (doc/handwritten/for-maintainers/audit/2026-07-20-firstclasserrors-architecture-and-design-audit.md, §12.4/§14-HV15; branch claude/firstclasserrors-audit-83gap7).
Problem
fce generateonly creates files — it never deletes a stale one. An error removed from the code leaves its page orphaned in the output directory. The repository's own CI mustrm -rfthe catalog before regenerating, and the workflow comment admits why (gendoc-docs.yml:60-62); but users followingTheHtmlRenderer.en.mdorCatalogVersioningCI.en.mdto publish their own living catalogs will accumulate ghost pages for removed errors — precisely the drift the tool exists to prevent — with no mention of the workaround in the user docs.Impact
The living-docs promise silently degrades for every external adopter of the documented CI publishing loop.
Direction
rm -rffor shared output directories) or a--cleanflag on directory output.TheHtmlRendererandCatalogVersioningCI(EN+FR).--service-nametoTheHtmlRenderer.en.md's two copy-paste examples, which currently fail as written.Acceptance criteria
Context
Surfaced by the 2026-07-20 architecture, design & ecosystem audit (
doc/handwritten/for-maintainers/audit/2026-07-20-firstclasserrors-architecture-and-design-audit.md, §12.4/§14-HV15; branchclaude/firstclasserrors-audit-83gap7).