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

[mhenrixon]

Closes #21.

Problem

The user story behind the 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.

What this does

The install generator gains create_agent_docs, which scaffolds the docs-kit authoring contract in a machine-readable form — maintained in ONE place (the gem's templates), so "document this endpoint" works out of the box.

AGENTS.md (site root) — the cross-tool convention file (Claude Code, Cursor, Copilot, Aider, …). A terse, example-first contract:

• the one-command page flow (rails g docs_kit:page),
• the md <<~'MD' single-quoted-heredoc prose idiom,
• that DocsUI::Section owns page structure and the "On this page" TOC (never a Markdown ## for structure),
• the reference-material helpers (PropTable / FieldTable / RequestExample / Callout),
• the invariants an agent must not break (registry line required, JS-off must work, themes ↔ CSS build, no inline rubocop:disable).

It links the live /docs/authoring page for depth.

.claude/skills/write-docs-page/SKILL.md — a Claude Code skill: the task recipe (gather the subject → run the generator → write sections md-first → self-review against a checklist → run the gates). Frontmatter targets "write / add / update a documentation page," so Claude Code reaches for it automatically.

Idempotence (the interesting bit)

Situation	Behavior
No AGENTS.md	Created whole
Existing AGENTS.md	docs-kit block injected between <!-- BEGIN docs-kit --> / <!-- END docs-kit --> — user content preserved
Re-run	Only the delimited block is rewritten; user sections outside it stay intact; no duplication
Existing skill file	Never clobbered

docs-kit new inherits both files automatically (it runs the install generator). The gem's own repo gets an adapted AGENTS.md (dogfooding for agents contributing to docs-kit's docs site).

Test plan

New spec/generators/install_generator_spec.rb block (AI-authoring scaffold):

• fresh app → AGENTS.md + skill created, brand substituted, core idioms present (rails g docs_kit:page, md <<~'MD', DocsUI::Section),
• skill frontmatter targets "document" + names the page generator,
• existing AGENTS.md → docs-kit block injected between delimiters, user content preserved,
• re-run → no duplicate block; a hand-edited AGENTS.md's user sections stay intact,
• existing skill file → not clobbered.

Verification

• bundle exec rspec — 459 examples, 0 failures
• bundle exec rubocop — 94 files, no offenses
• End-to-end smoke: ran create_agent_docs against a throwaway destination — the generated AGENTS.md (with delimiters) and skill (with valid frontmatter) render with the brand substituted.

Out of scope (per the issue)

• Cursor/Copilot-specific rule files (AGENTS.md is the cross-tool bet).
• Auto-generating page content from source (that's the agent's job, given these conventions).

https://claude.ai/code/session_01FPQb6z3YwcKRMbvoJhdxnX