[lessthanjacob]

Summary

Adds documentation to improve context for agents (and humans) working in the codebase.

Written by the author.

Changes

Added

• Codebase docs: docs/ adds an architecture explanation, configuration and extension-point references, and how-tos for making changes, testing, releasing, and writing docs, indexed in docs/index.md.
• Agent guidance: AGENTS.md sets hard rules, verification gates, and gotchas, and points agents to docs/index.md first.
• Doc trust fields: each doc carries a Diátaxis type plus OKF generated / verified frontmatter, so a reader can tell whether a person checked it against the code since its last change.

Changed

• Public API by tag: Transformer and AutoExtractor drop their @api private tags, and the private AutoExtractor#extractor is tagged @api public, since the README has users subclass both and override extractor.

Fixed

• Red CI on main: the Metrics/ClassLength exemption for ViewCollection moves from an inline disable/enable pair, which Style/DirectiveScope now flags, to .rubocop.yml.

Context

Why This Approach

• Docs
  • Design rationale sits next to the mechanism it explains in architecture.md, not in separate decision records, so it changes in the same edit as the mechanism.
  • docs/index.md is a hand-maintained table rather than generated, so there is no task or script to maintain for seven docs.
  • No directory-structure listing: it goes stale with every new file, and the index plus architecture.md cover where things live.
• Public API tags
  • Public API is defined by @api tags and the README, not Ruby visibility: nearly everything in Ruby is reachable, so visibility can't mark a compatibility boundary.
  • Retagging Transformer and AutoExtractor avoids carrying a "documented beats tagged" exception in the docs.
• Lint fix
  • It ships here because Test on main has failed on Style/DirectiveScope since d1e407b, so no PR can go green without it.
  • The exemption moves to .rubocop.yml instead of a # rubocop:disable-next directive: the Gemfile allows rubocop ~> 1.44, and the installed 1.88.2 doesn't recognize disable-next (1.91.0 does).

Testing: CI green on fa9a100 (Ruby 3.1–4.0, CodeQL, DCO); all three diagrams render

• ✅ CI on fa9a100: test passes on Ruby 3.1, 3.2, 3.3, and 4.0; CodeQL and DCO pass.
• ✅ bundle exec rake locally on 4fdf9b9 (later commits touch only CHANGELOG.md and Markdown under docs/ and AGENTS.md): 395 examples, 0 failures; RuboCop reports no offenses.
• ✅ Each Mermaid diagram in architecture.md renders with @mermaid-js/mermaid-cli@11 at 6322b47. Before that commit, the sequence diagram failed to parse because ; in a message label ends the statement.
• ✅ Every relative link and anchor in AGENTS.md and docs/ resolves, each docs/index.md row matches its doc's frontmatter, and all frontmatter loads with plain YAML.safe_load.
• ✅ Every path, symbol, behavior claim, and code example in docs/ was checked against the code, with each example run. Wrong claims were corrected and unsupported rationale removed.
• ✅ The author reviewed all seven docs against the code, recorded in each doc's verified field.

Checklist

• I have updated the necessary documentation
• I have signed off all my commits as required by DCO
• My build is green

---

_{current as of fa9a100}

🤖 Generated with Claude Code