DOC: add AGENTS.md and CLAUDE.md for AI coding agents

[mvdoc]

Closes #706.

Adds repository guidance for AI coding agents (Claude Code and any tool that reads the cross-tool AGENTS.md standard).

What's in it

• Commands: editable install with the Cython extensions (--no-build-isolation), the headless extra + Playwright setup, running the full suite / a single file / a single test, the per-test timeout, which tools tests self-skip on (Inkscape, Playwright, FreeSurfer), and the docs build.
• Architecture: the filestore/Database layout, the dataset braindata × Dataview class hierarchy, the mapper families and their caching, quickflat's layer-composition design, the WebGL pipeline (Package → CTM packs → Tornado templates → Three.js r69 app, JSProxy, shaderlib.js), the shared overlays.svg ROI system, and configuration (options.cfg, filestore/colormaps).
• Gotchas: silent pervasive caching and recache/db.clear_cache, import cortex side effects, CTM vertex reordering, package_data enumeration for new webgl resources, CRLF line endings in some JS files.

Layout

Per @kroq-gar78's suggestion in #706, the content lives in AGENTS.md and CLAUDE.md imports it with Claude Code's @AGENTS.md syntax. I used an import rather than a symlink so Windows checkouts (recently fixed in #701) don't degrade the link into a plain text file.

🤖 Generated with Claude Code

[mvdoc]

Overall it looks OK to me. Anything worth adding @kroq-gar78 @alexhuth @marklescroart ?

[kroq-gar78]

It would also be great if we strongly suggest (require?) new Python code to have type annotations. I'm not sure where in the file that would go.

[mvdoc]

@claude address the comments in this review

[claude]

Claude finished @mvdoc's task in 2m 40s —— View job

---

Addressing review comments

• Gather context: review comments, PR discussion, current AGENTS.md content
• Confirm which review items were already resolved (Python-version pinning removed, overlays.svg note added in earlier commits)
• Switch install/test/docs commands in AGENTS.md to uv, per the discussion resolved in this thread
• Note the new-code type-annotation expectation raised in the PR comments
• Commit and push

Summary

Pushed be2d191 to this branch. Two review items were already handled by earlier commits on this branch (removing hard-coded Python versions from the CI line, and the overlays.svg pretty-printing note), so I focused on the still-open thread:

• Install/build: replaced the 4-line pip sequence with uv sync --all-extras (headless/playwright extra + the dev dependency-group, which is included by default), followed by uv run playwright install --only-shell chromium.
• Tests: prefixed all pytest invocations with uv run.
• Docs: sphinx_gallery/numpydoc aren't in a dependency group yet, so I kept them as an ad hoc uv pip install, then run make html via uv run so it picks up the synced venv.
• Type annotations: added a short note in the Tests/CI bullet that new Python code should carry type annotations, per @kroq-gar78's comment. I didn't add enforcement (e.g. a CI mypy gate) since that's a bigger decision than this doc file should make on its own — happy to open a follow-up issue if you'd like to pursue it.

Not verified: I don't have uv or network access in this sandbox, so I could not actually run uv sync / uv run pytest against this checkout to confirm the commands work end-to-end (including whether the Cython extensions build correctly under uv's isolation model without the old --no-build-isolation workaround). Worth a manual sanity check before merging.

[mvdoc]

@claude uv should now be enabled in your sandbox; verify commands work.

[claude]

Claude finished @mvdoc's task in 10m 1s —— View job

---

Verifying uv commands in AGENTS.md

• Check uv is available in sandbox
• Run uv sync --all-extras (build/install)
• Run uv run playwright install --only-shell chromium
• Run uv run pytest (or a subset) to confirm tests work
• Run docs build commands
• Report results

Result: uv is still not available in this sandbox

Despite the note that it "should now be enabled," uv is not on PATH here:

$ uv --version
/bin/bash: line 1: uv: command not found

I couldn't find it anywhere reachable from the session (no writable access outside the repo checkout to search typical install locations like ~/.cargo/bin), and I wasn't able to install it either — pip install uv and curl-based installers are blocked by this sandbox's tool-permission gate (no interactive approver in this headless run). So I could not literally execute uv sync, uv run pytest, uv run playwright install, or uv run make html end-to-end.

What I could verify, using the pip-based environment that's pre-installed in this sandbox (cortex importable, pytest on PATH directly):

• pytest collects all 138 tests cleanly.
• pytest cortex/tests/test_formats.py — 1 passed.
• pytest cortex/tests/test_webgl_headless.py — 42 passed, 2 skipped in ~7m10s (Playwright/Chromium is present here, so the WebGL headless path documented in AGENTS.md genuinely works; the 2 skips are pre-existing known-flaky/manual cases, not environment issues).
• pyproject.toml confirms the uv sync --all-extras line's claim: headless is an optional extra (playwright), and dev is a [dependency-groups] entry (test + types) — since there's no [tool.uv] override, uv's default behavior is to install the dev group automatically on uv sync, so uv sync --all-extras does get you extras + dev deps as the comment says.
• docs/Makefile and docs/conf.py (referencing sphinx_gallery/numpydoc) exist as described, but I couldn't execute make html or check sphinx-build/playwright CLI directly — those invocations were blocked by the same permission gate.

Bottom line: the commands in AGENTS.md are consistent with the actual repo config (pyproject.toml, CI workflows), and the underlying tools they wrap (pytest, playwright/Chromium) do work in a real environment — but I was unable to execute the uv-prefixed commands themselves in this particular sandbox because uv isn't installed here and I have no permitted way to install it. For a true end-to-end confirmation of the exact uv sync / uv run invocations, that'll need to happen in an environment where uv is actually present (or the sandbox config that's supposed to enable it here needs a look) — happy to re-run this verification once that's available. No changes made to AGENTS.md since nothing was found to be factually wrong, just unverifiable in this session.

[mvdoc]

@claude uv should finally be enabled. verify commands work.

[claude]

Claude finished @mvdoc's task in 13m 46s —— View job

---

Verifying uv commands in AGENTS.md

• Check uv is available in sandbox
• Run uv sync --all-extras (build/install)
• Run uv run playwright install --only-shell chromium
• Run uv run pytest (full suite)
• Run docs build commands
• Report results

Result: uv is now available, and uv run pytest works end-to-end — network-touching uv subcommands are still blocked in this sandbox

Good news first: uv (0.12.7) is genuinely on PATH this time, and commands that only touch the already-installed local environment work exactly as documented:

• uv run pytest cortex/tests/test_formats.py — 1 passed in 4.6s.
• uv run pytest (full suite, no extra flags) — 132 passed, 6 skipped in 733.67s (~12 min). The 6 skips are the expected ones from AGENTS.md's own description (FreeSurfer mri_surf2surf not installed, Connectome Workbench not installed, one known-flaky headless Chromium cmap-texture case, and the manual visual-comparison test gated behind RUN_VISUAL_COMPARISON=1).
• As a side effect, filestore/db/S1/overlays.svg got rewritten by the test run (pretty-printing only) — confirms the "Gotchas" note in AGENTS.md is accurate; I did not commit that change.
• pycortex was already installed editable in this environment (uv pip list shows pycortex 0.0.0 /home/runner/work/pycortex/pycortex, plus playwright, pytest, pytest-cov, pytest-timeout present), so this run didn't exercise a from-scratch Cython build via uv sync.

However, every uv subcommand that needs to hit the network was rejected with "This command requires approval" and there's no interactive approver in this headless run, so I could not execute them end-to-end:

• uv sync --all-extras
• uv run playwright install --only-shell chromium
• uv pip install sphinx_gallery numpydoc (needed before cd docs && uv run make html)

This is a narrower version of the same sandbox limitation from the last verification pass — previously uv itself wasn't installed at all; now it's installed and local/offline invocations work fine, but anything that fetches packages or browser binaries over the network is still gated. I don't have a way to grant that approval myself in this session.

Bottom line: uv run pytest ... (the command most agents will actually run day-to-day, assuming the environment is already synced) is confirmed working and matches AGENTS.md exactly, including its documented skip set. The install/build (uv sync), Playwright browser install, and docs commands remain unverified end-to-end — they're consistent with pyproject.toml/CI config on inspection, but actually executing them needs a sandbox where outbound package/browser downloads are permitted (or the network approval prompts need a human/approver present to click through).