docs: epic agent DX polish — docstrings, CLI tips, scaffold, RFC archive

[lbliii]

Summary

Closes the five agent-DX discoverability gaps identified in the 2026-04-20 cold-read evaluation, across five independently-shippable sprints tracked in plan/epic-agent-dx-polish.md:

• S1 — Core-type docstrings: Site/Page/Section "When to use" intent coverage 1.2% → 71.6% (58/81 members), ~100% on the targeted non-trivial subset. Plain domain facets (config getters, word_count, parent) intentionally left alone per CLAUDE.md.
• S2 — AGENTS.md "Extending Bengal" section: 91 lines covering 4 extension points (template functions, content types, CLI commands, build phases) with a 3-bullet Milo-vs-Click primer. End-to-end verified by a fresh-agent read.
• S3 — bengal new content-type <name> scaffold: Generates a working ContentTypeStrategy subclass with When to use: docstring, default_template, sort_pages(), and register_strategy() call. 6 unit tests covering creation, import+register cycle, PascalCase, duplicates, invalid names.
• S4 — CLI error-guidance pairing: Every cli.error(...) in bengal/cli/ now has a cli.tip/cli.info/cli.render_write follow-up within 3 lines (27.1% → 100%, 70/70). New AST gate test tests/unit/cli/test_cli_error_gates.py enforces the rule for new additions.
• S5 — Stale RFC archive: Moved 4 bucket-B RFCs with unambiguous done-signals to plan/complete//plan/evaluated/. Root plan/*.md count 69 → 65. 3 cross-refs updated. plan/README.md gained an Archive Structure section.

Test plan

• pytest tests/unit/cli/ — 123 passed (includes new gate test + 6 scaffold tests)
• ruff check bengal/cli/ tests/unit/cli/ — clean
• ty type checker — passes (pre-commit)
• End-to-end: scaffolded content-type strategy imports, registers, and get_strategy() returns it
• End-to-end: fresh agent reads "Extending Bengal" and writes a working bengal hello command
• Re-run 2026-04-20 cold-read evaluation after merge to confirm gaps closed (success metric: 8.1/10 → 9.0/10)

🤖 Generated with Claude Code