Add a zero-warning Sphinx site with mermaid diagrams; rewrite the changelog to Common Changelog

[forkrul]

Sphinx docs (docs/)

• Sphinx + MyST site that also reads on GitHub. docs/README.md is the GitHub landing page for the folder; docs/index.md is the Sphinx root.
• docs/architecture.md draws the contracts as 7 mermaid diagrams: the pipeline and its artifacts, smithy's state machine, the adversarial review round, red-amber-green, parallel [P] tasks, how install.sh places a link, and the superpowers policy. They are plain ```mermaid blocks. GitHub renders them natively, and myst_fence_as_directive = ["mermaid"] makes the same blocks sphinxcontrib-mermaid directives in Sphinx.
• No contract is copied into docs/. docs/_ext/damascus_sources.py generates the pages for the skills, agents, README, example trail, CLAUDE.md and changelog into docs/_generated/ at build time. That directory is gitignored. The extension strips frontmatter and re-points relative links: to the generated page, to docs/, or to GitHub.
• New CI job sphinx docs (zero warnings) runs sphinx-build -W --keep-going -n. The toolchain is pinned in docs/requirements.txt and is docs-only; install.sh needs none of it.
• Fix: forge's PRD template had a nested ``` fence that closed the outer block early, so the template rendered broken on GitHub too. The outer fence is now four backticks.

Changelog (Common Changelog)

• Entries are single-line and imperative, each with PR or commit links (at most two per entry). The release has a one-sentence notice and uses only the Added category, since nothing has been released yet. CI, Dependabot and issue-template noise is dropped.
• [Unreleased] stays as the repo's one deliberate deviation, because CLAUDE.md, the changelog gate and the Release workflow depend on it. It now has a link definition. CLAUDE.md's release ritual says how to rewrite the notice and add the version link.

README / CLAUDE.md

• README gains a Documentation section and a docs/ row in Layout. CLAUDE.md documents the zero-warning build and the rule that contracts are never copied into docs/.

Verification

• sphinx-build -W --keep-going -n: build succeeded, 0 warnings.
• All 8 mermaid diagrams (7 new plus the README's) parse and render with mermaid 12 in headless Chromium. The built pages render all 7 SVGs with no console errors, and I checked each diagram by screenshot.
• tests/smoke.sh passes. Frontmatter lint and the example-trail check pass, and ci.yml parses.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgVoHT9xneQu3hPZSabSGv

---

Generated by Claude Code