docs: add AGENTS.md with repo map, verification, and PR conventions

[nichochar]

AGENTS.md    +116/-0   repo map, verification commands, code style, PR conventions
CLAUDE.md      +1/-0   symlink → AGENTS.md

Top of the stack, on #509.

A short guide for agents (and new contributors) working in this repo. CLAUDE.md is a symlink, stored by git as mode 120000, so there's one file to maintain.

What's in it

A map, so the search phase starts from a hypothesis instead of a grep. A table of the ten places that matter, plus the two facts that are genuinely surprising: notebooks aren't in sqlite (each is a real npm project on disk), and packages/web imports @srcbook/components by deep source path rather than through its entry point.

Verification. The full check is one line — pnpm build && pnpm lint && pnpm check-format && CI=true pnpm test. CI=true is called out because the api test script is bare vitest and otherwise sits in watch mode, and --force is mentioned because turbo's cache will happily hand back a stale build. Also how to boot the real app, and a note to clean up ~/.srcbook afterwards.

Code style, kept short since the rule is mostly "match the file you're editing". The one thing spelled out is the comment bar: why not what, delete anything that restates the code, keep it to a couple of lines, and don't address the reviewer in a comment.

PR conventions, including the filetree requirement — every PR body opens with a plain-text tree grouped by directory with per-file diff counts, generated from git diff --numstat <base>...HEAD. The tree at the top of this PR is the format.

Graphite, now the documented workflow. The guide says to use gt rather than manual git rebase and explains why: this repo squash-merges, which breaks patch-id matching for any branch with more than one commit, so vanilla rebase replays already-merged changes and conflicts. That's exactly what would have happened restacking #508 by hand after #507 merges.

It points at DECISIONS.md for the why, REVIEW.md for the known-broken list, and tasks/ for the queue, rather than duplicating any of them.

Setup done

gt repo init with trunk main, and all three open branches tracked with their parents, so gt ls shows the real stack.

⚠️ One thing needs you: gt submit fails with "You can only submit to repos synced with Graphite" — srcbookdev/srcbook needs enabling at app.graphite.com/settings/synced-repos. Local commands (gt ls, gt sync, gt restack, gt create) already work; only PR submission is blocked. This PR went up via gh in the meantime.

[nichochar]

• docs: add AGENTS.md with repo map, verification, and PR conventions #510 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.