Fit AGENTS.md inside what Codex reads

Merged
RO
1d ago
+938-799

Why

Codex reads only the first 32 KiB of AGENTS.md (project_doc_max_bytes) and drops the rest without saying so. Ours was 68 KB. Codex sessions in this repo were cut off mid-word in the paging section, so they never saw the SDK workflow, the examples rules (use @example.com), unit or smoke testing, or the code style pointer. Claude Code read all 68 KB at the start of every task, whatever the task touched.

What changed

  • The subsystem deep-dives move verbatim into one doc each under docs/architecture/.
  • AGENTS.md keeps the rules a change is most likely to break, plus a pointer for each subsystem. It goes from 68 KB to 15 KB.
  • A test fails when AGENTS.md grows past 32 KiB, or when a link in it or in docs/architecture/ no longer resolves.

Scope

  • Content moves. It is not rewritten. Removed: references to code that is already gone, and a second terminal-safety section that repeated the first.
  • Turning the remaining prose-only rules into tests (IsStyled outside writeMutation, new sdk.GetHTML callers) is left for a follow-up.

Tradeoffs

Package doc.go files would put the deep-dives next to the code. One Markdown file per subsystem was a plain move that keeps the text diffable against the old file, and it doesn't require rewriting everything as Go comments.

Blast Radius

Documentation and one test only. Agents now need to follow a pointer for subsystem detail. Each pointer sits under a heading that names its subsystem.

Verification

  • An equivalence script compared every body line of the old file against the new AGENTS.md plus docs/architecture/. 756 of 762 lines are still there verbatim. The 6 that changed are a stale TUI file list and a section list that left out Contacts.
  • I ran codex exec in the branch and read the session it recorded. Codex received all 15,384 bytes and quoted the final heading. Before this change, sessions in this repo recorded a 32,784-byte cut that ended at "Contacts ar".
  • I mutated the files to check the tests catch failures. They failed on oversize, on the original 68 KB file, and on a broken link in each kind of file. make test passes in 19 of 19 packages, and make lint reports 0 issues.

Summary by cubic

Shrinks AGENTS.md from 68 KB to 15 KB so Codex reads the whole file instead of cutting off at 32 KiB mid-page, which previously hid the SDK workflow, testing rules, and code style pointer from every session.

Changes

  • Subsystem deep-dives move verbatim into one doc each under docs/architecture/; AGENTS.md keeps the rules a change is most likely to break, with a pointer per subsystem.
  • Drops references to code that no longer exists and a duplicated terminal-safety section; content moves, it is not rewritten.
  • Adds tests that fail when AGENTS.md outgrows 32 KiB or a link in it or docs/architecture/ stops resolving.
  • Tightens four remaining summaries that claimed more than the doc they point to: boxes page by next_history_url rather than the Link header, the TUI re-reads a box's top page instead of the sync feed, only virtual days of a repeating event have id 0, and sigstore covers only hey upgrade's own install path.