## Summary
- Diagnose all `docs/` + `README.md` against a 10-point GitHub
doc-quality standard, then rewrite the high-impact files (README,
quick-start, docs/README, tdd-workflow, manual-verification,
contributing, every reference doc).
- Split `manual-verification.md` (24 KB single file mixing Tutorial /
How-to / Reference) into 4 files so each serves one reader type.
- Move `docs/guide/upgrade.md` §FAQ into `docs/faq.md` to eliminate the
double source.
- Rewrite the v0.1.15 CHANGELOG entry as the first conformant example of
the new writing convention (one-fact bullets, separate `### BREAKING`
with migration path table). Older entries explicitly grandfathered.
- Backfill `<!-- prompt: ... -->` comments into all 9 SVGs in
`docs/assets/`, plus a centralised `docs/assets/svg-prompt-template.md`
so future LLM regenerations stay visually consistent.
- Drop banned vague adverbs (一键 / 智能 / 只需 / 最简单 / 轻松 / simply / just /
obviously / easily) from all user-facing docs and from 3 SKILL.md files
(where they would otherwise bloat LLM context at runtime).
- Add `scripts/gen_cli_reference.py` (click --help → markdown, with
`--diff` mode) so CLI changes can't silently drift
`docs/reference/cli.md`.
## Anti-rot guards (10 → up from 8)
Two new doc-quality guards wired into both the per-PR `test.yml`
anti-rot block and the weekly `anti-rot.yml` sweep, plus pre-commit:
- `scripts/checks/check_no_marketing_words.py` — forbids vague adverbs
across `README.md`, `docs/**/*.md`, `.cataforge/skills/**/SKILL.md`,
`.cataforge/agents/**/AGENT.md`. Whitelist via inline `<!--
allow-marketing-words: <reason> -->` for legitimate quotation.
- `scripts/checks/check_no_design_residue.py` — forbids design-phase
comments (`<!-- 变更原因 -->`, `<!-- diagnostic # -->`, `TODO`, `FIXME`,
`prompt-version`, `last-regenerated`) in `.cataforge/agents` and
`.cataforge/skills`, since they bloat the LLM context at runtime.
## Test plan
- [x] `python scripts/checks/check_no_marketing_words.py` — `OK: scanned
65 files, no marketing-word violations`
- [x] `python scripts/checks/check_no_design_residue.py` — `OK: scanned
42 files, no design-phase residue`
- [x] All workflow YAML files parse cleanly (`yaml.safe_load`)
- [x] `python scripts/gen_cli_reference.py` runs and dumps click
`--help` for every command
- [ ] CI (`test.yml`) green on Linux + Windows
- [ ] CI anti-rot block reports 10 guards passing
- [ ] No regression in existing 8 anti-rot guards
[skip-changelog]
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: huancheng.lin@foxmail.com <huancheng.lin@foxmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
