feat(ai-authoring): scaffold AGENTS.md + a write-docs-page skill into consuming sites

[mhenrixon]

Part of #8 (Phase 4). Best after the Phase 1 issues (it documents their idioms).

Problem / Goal

The user story behind this epic: "I am one of those developers who won't document" — the fix is letting an agent do the writing while the developer reviews. But an agent dropped into a consuming site today has to reverse-engineer the kit: it doesn't know md heredocs are preferred over plain chains, that the registry line is required, that docs_kit:page exists, or that headings belong to Sections. Every consuming site (and every future one from docs-kit new) should carry machine-readable authoring conventions so "document this endpoint" works out of the box.

Goal: the install generator and docs-kit new scaffold an AGENTS.md (cross-tool convention) plus a Claude Code skill (.claude/skills/write-docs-page/SKILL.md) that encode the docs-kit authoring contract, maintained in ONE place — the gem's templates.

Context (read these first)

• Critical Rule 8: required setup wires into the install generator AND the docs-kit new template — this issue is that rule applied to AI setup.
• lib/generators/docs_kit/install/install_generator.rb + lib/docs_kit/templates/new_site.rb — both scaffolding paths.
• The Phase 1 issues' final APIs (md helper, page generator, Registry v2, PropTable) — the content of the conventions.
• docs/app/views/docs/pages/authoring.rb — the human version of the same contract (keep the two in sync; the AGENTS.md should link the live page).
• app-4's inline-cop-disable pain (12+ rubocop:disable comments in docs pages) — conventions the file must state explicitly so agents don't fight site cops.

Decision

1. AGENTS.md template (agents_md.erb, written to the site root; if one exists, inject a clearly-delimited docs-kit section instead of overwriting). Contents — terse, imperative, example-first:
   • The one-command page flow: rails g docs_kit:page "Title" --group=…, then fill #content.
   • The authoring idioms: md <<~'MD' for prose (single-quoted heredoc, no escaping); DocsUI::Section owns structure/TOC (never markdown ## for page structure); PropTable/FieldTable/RequestExample for reference material; Callout levels.
   • The invariants an agent must not break: registry line required; JS-off must work; themes list ↔ CSS build.
   • Verification: bundle exec rspec && bundle exec rubocop, bun run build:css, and "render the page locally".
2. Claude Code skill template (.claude/skills/write-docs-page/SKILL.md): a task recipe — gather the subject (code/endpoint to document), run the generator, write sections (md-first), self-review against the checklist, run the gates. Frontmatter description targets "write/add/update documentation page".
3. Both live as ERB templates in lib/generators/docs_kit/install/templates/, rendered with app_brand; the install generator gains create_agent_docs (idempotent: skip or inject-into-delimiters); docs-kit new inherits automatically via the install run.
4. The gem's OWN repo gets the same AGENTS.md content adapted (dogfooding for agents contributing to docs-kit's docs site).

Alternatives rejected: CLAUDE.md instead of AGENTS.md (AGENTS.md is the emerging cross-agent standard; Claude Code reads it via the skill + users commonly symlink/import — note the option in the template header comment); shipping a full plugin/marketplace package (heavyweight; a repo-local skill needs zero install); an authoring MCP server (see the MCP issue — wrong tool for in-repo work).

Implementation steps (TDD)

1. Generator specs first (spec/generators/install_generator_spec.rb additions, harness from the CI issue): fresh app → AGENTS.md + skill file created with brand substituted; existing AGENTS.md → docs-kit block injected between delimiters, user content preserved; re-run → no duplication.
2. Write the two templates (keep AGENTS.md under ~120 lines — it's a contract, not a manual; link the live authoring page for depth).
3. Wire create_agent_docs into the install generator; confirm docs-kit new picks it up (template runs the generator).
4. Add the adapted AGENTS.md to the gem repo itself.
5. README: an "AI-assisted authoring" section (generator scaffolds it; what the skill does).

Verification gates

• bundle exec rspec spec/generators — green.
• bundle exec rubocop — no offenses.
• Live test: in the dogfood app, ask Claude Code (with the skill present) to "add a docs page about X" — it uses the generator, md-first prose, and passes the gates without human correction of conventions.
• Idempotence: re-running the generator leaves a hand-edited AGENTS.md's user sections intact.

Out of scope

• Cursor/Copilot-specific rule files (AGENTS.md is the cross-tool bet; add others only on demand).
• Auto-generating page content from source code (that's the agent's job, given these conventions).
• The gem repo's own CLAUDE.md restructure.