chore: AGENTS.md as the shared instruction file

[mhenrixon]

Summary

• Moved the project rules from CLAUDE.md (tech stack, critical rules, architecture,
  the mental model, testing, deploy) into AGENTS.md, ahead of the existing
  cross-tool authoring guide ("the two things you'll be asked to do", verify
  commands). No content dropped — overlapping bullets (e.g. the old "Change the
  gem" checklist duplicating Critical Rules) were collapsed into one copy.
• CLAUDE.md is now a 3-line stub (@AGENTS.md + a pointer to .claude/),
  matching the shape Claude Code's own docs recommend for a shared
  AGENTS.md.
• Added a 2–3 line intro to AGENTS.md stating it's the instruction file for
  every agent (Claude Code imports it via CLAUDE.md; other tools read it
  directly).
• Added a "Screenshots on PRs and issues (always)" section — docs-kit ships a
  visual chrome (DocsUI:: components, the docs site itself), so UI changes
  should carry before/after pictures via gh pr create/comment --attach.
• Repointed 4 internal CLAUDE.md references (that meant "the project rules")
  to AGENTS.md: spec/spec_helper.rb, .claude/rules/agents.md,
  .claude/commands/plan.md (x2), .claude/commands/github-review-comments.md
  (x2).
• Checked the generator that installs docs-kit into other repos
  (lib/generators/docs_kit/install/install_generator.rb +
  templates/agents_md.erb): it already writes/merges a delimited
  <!-- BEGIN docs-kit --> … <!-- END docs-kit --> block into a consuming
  site's AGENTS.md (never CLAUDE.md), so this change needed no generator
  update — verified only, not touched. No <!-- BEGIN docs-kit --> block
  exists in this repo's own AGENTS.md (that block is only for consumers), so
  there was nothing to preserve there.
• docs-kit.gemspec ships whatever git ls-files tracks — CLAUDE.md was
  already shipping in the gem package before this change (now as the stub); no
  .gitattributes/.npmignore exists to adjust.

.rtk/filters.toml

Not added. Checked every command an agent runs here:

• bundle exec rspec, bundle exec rubocop, bun run build:css are already
  rewritten by the global rtk hook (rtk hook check confirms it) — no project
  filter needed.
• bundle exec rake (spec + rubocop together, the default Rake task and what
  CI runs) is not rewritten, and its raw output is noisy: a real local run is
  1366 lines, dominated by ~950 RSpec --format documentation example
  description lines (.rspec pins that formatter). A line-based
  strip_lines_matching filter can't safely tell a passing example line
  ( renders the expected markup) from a failing one printed the same way
  with a (FAILED - N) suffix in the same tree — Rust's regex engine (what rtk
  uses) has no lookaround, so there's no safe negative-match pattern either.
  Rather than ship a filter that could hide a real failure, AGENTS.md now
  tells agents to run bundle exec rspec and bundle exec rubocop separately
  (both already rtk-condensed) instead of bundle exec rake when they need to
  read the result.
• gem build / rake release[...] are publish/release commands — out of scope
  to run for filter-building per the task brief (no network publishing).
• No bin/setup, bin/* scripts, or other noisy custom scripts exist in this
  repo to filter.

Adopts getzazu/app#4104.

Test plan

• bundle exec rspec — 953 examples, 0 failures (ran in a fresh worktree
  with the checked-in Gemfile.lock copied over, since it's gitignored)
• bundle exec rubocop — 151 files inspected, no offenses (0 on the
  changed spec/spec_helper.rb, 151 on the full repo)
• rtk verify — 154/154 passed
• Manually grepped the whole repo (excluding .git, vendor,
  node_modules, the gitignored .claude/worktrees/) for CLAUDE.md —
  only the intentional self-reference in the new AGENTS.md intro remains

---

Summary by cubic

Moves the project rules from CLAUDE.md into AGENTS.md so every coding agent reads the same instruction file; CLAUDE.md is now a thin stub that imports it. No project rules were dropped — overlapping bullets were collapsed into one copy.

Changes

• AGENTS.md now holds the tech stack, critical rules, architecture, testing, deploy, and commands, plus a new screenshots-on-PRs section.
• Repointed internal CLAUDE.md references to AGENTS.md; the install generator already targets consuming sites' AGENTS.md, so no generator change was needed.

Why no .rtk/filters.toml

• bundle exec rspec, bundle exec rubocop, and bun run build:css are already condensed by the global rtk hook.
• bundle exec rake output can't be safely line-filtered, so AGENTS.md now recommends running rspec and rubocop separately when reading results.

^{Written for commit c4281ae. Summary will update on new commits.}