Epic: decree-docs — advanced schema docs generator

[zeevdr]

Description

A standalone documentation generator for decree schemas, living in a new top-level contrib/ directory: multiple output formats (json, md, mdx, html), built-in themes, CSS style injection, and a template override system. The core sdk/tools/docgen package stays minimal and zero-dependency; decree-docs is the full-featured tool built on the same schema sources.

Design informed by a survey of Redoc/Redocly CLI, Swagger UI, Scalar, Stoplight Elements, RapiDoc, Slate/Widdershins, json-schema-for-humans, Adobe jsonschema2md, terraform-docs, helm-docs, and protoc-gen-doc. Key patterns adopted: self-contained single-file HTML (Redocly), CSS custom properties inside cascade layers plus user CSS injection (Scalar), embedded templates with export and layered overrides (helm-docs), marker-based inject mode (terraform-docs), and a first-class JSON doc-model output for third-party renderers (protoc-gen-doc) — the latter fulfilling the third-party-renderer goal stated in #117.

Architecture

loader (file via sdk/tools/validate | server via sdk/adminclient)
  → doc model (complete: info, examples, externalDocs, version_description, allowed_schemes)
  → emitters: json | md (plain, material) | mdx (docusaurus) | html (single-file, themed)
templates: Go text/template in embed.FS, export-templates command, --template-files layering
config:    decree-docs.yaml with global + per-format sections; every key has a flag twin; flags win

Non-goals

• Documenting this project's own site — the MkDocs site and opendecree.dev (Build opendecree.dev landing site #189) own that; decree-docs documents user schemas.
• Interactive try-it consoles (config schemas are not request/response APIs).
• Any dependency on an external site generator (the Widdershins→Slate trap; Slate was archived in 2026).

Tasks

• Design brief in .agents/context/ (Goal / Non-goals / Key decisions) before implementation starts
• docgen: map info, examples, externalDocs from schema YAML #911 — docgen: map info, examples, externalDocs from schema YAML
• docgen: online mode drops field metadata shown in --file mode #912 — docgen: online mode drops field metadata shown in --file mode
• decree-docs: scaffold contrib module and CI wiring #913 — decree-docs: scaffold contrib module and CI wiring
• decree-docs: doc model, schema loaders, and JSON output #914 — decree-docs: doc model, schema loaders, and JSON output
• decree-docs: Markdown backend (plain and material flavors) #915 — decree-docs: Markdown backend (plain and material flavors)
• decree-docs: HTML backend (self-contained, themes, CSS injection) #916 — decree-docs: HTML backend (self-contained, themes, CSS injection)
• decree-docs: MDX backend (Docusaurus) #917 — decree-docs: MDX backend (Docusaurus)
• decree-docs: config file and template override system #918 — decree-docs: config file and template override system
• decree-docs: inject mode for existing READMEs #919 — decree-docs: inject mode for existing READMEs
• decree-docs: documentation, example outputs, freshness CI #920 — decree-docs: documentation, example outputs, freshness CI

Acceptance criteria

• All child issues closed.
• Design brief written, kept current during the effort, and compressed into .agents/context/completed.md when the milestone closes (per docs/development/checklists.md).