Skip to content

AGENTS.md

Latest commit

 

History

History
108 lines (83 loc) · 18.3 KB

AGENTS.md

File metadata and controls

108 lines (83 loc) · 18.3 KB
Raw

AGENTS.md

Entry point for AI agents (and people) working in this repository. Read this file first, then the files in "Read first". Rules here bind every agent; the full rulebook is docs/AI-AGENTS.md.

What this repository is

A workbench for the Vesuvius Challenge: reading carbonized Herculaneum scrolls from X-ray CT. It does not reimplement the official pipeline (ScrollPrize/villa); it plans runs of it, scores ink maps against published labels, checks results across devices, records provenance, and keeps dated research notes. Owner: Chase Hendrick (GitHub ChaseHendrick). Machine: Apple M1 Pro (MPS GPU, no CUDA).

Public and private work

ChaseHendrick/Scrolls-private is the home for all work that cannot be public (user decision, 2026-10-07). Read its handoff and relevant branches before starting or continuing a private investigation. Keep candidate outputs, private research notes and submission material there or in its ignored local data directories. This public repository holds tools, public-data benchmarks and material cleared for public release. Never copy private findings into public commits, PRs, CI logs or documentation.

Read first, in this order

When the private checkout is available, refresh the combined session context from that checkout with python3 -m kit.repo_handoff context --private-root . --public-root ../Scrolls. Its handoff helper installs local Git hooks in both checkouts and writes combined context only inside the private workspace. Hooks do not push, run hosted jobs or copy private notes into this repository. Read the generated private context before private work; never paste it into public artifacts.

Many files here are long: read the top of each and search the rest.

  1. docs/HANDOFF.md: the one handoff, open items first, then recent dated sections, newest first (rule 14). Older sections are in docs/HANDOFF-archive.md; search it, do not read it whole.
  2. docs/README.md: the docs index, one home per topic. Check it before any research or writing (rule 13).
  3. docs/AI-AGENTS.md: the rulebook.
  4. docs/MAP.md: the repository map, one row per module and script. Search it for a tool or a path.

At session start, any agent runs python3 -m kit routines run --due and reads python3 -m kit routines status (rulebook).

Released tools are listed in the README's "Released tools" section, including Unroll, the interactive 3D viewer released as a Hugging Face Space (v1.0.0, Apache 2.0 code; guide: docs/unroll-space.md).

Terms used in the code and docs are defined, A to Z, in GLOSSARY.md. Add a term there when you introduce one.

Open these when the task needs them:

  • docs/plans/roadmap.md: pointer to the roadmap, which now lives in Scrolls-private (access required). Gate A's public rule is in kit/gate.py.
  • docs/results.json: every benchmark number with its settings and source. It is over 200 KB, so print only the part you need; python3 -c "import json; print(list(json.load(open('docs/results.json'))))" lists its sections. The README section "Novel findings" lists only results not published elsewhere, one line each; their full text is docs/FINDINGS.md. Reproductions stay in results.json and the logs. Keep all three in step when numbers change.
  • docs/logs/: dated research notes; open the one a handoff row or the docs index names, and the newest for the latest numbers. Literature (arXiv, journals, Zenodo, Kaggle): docs/logs/2026-10-07-literature.md and machine-readable docs/papers.json.

Hard rules (short form)

  1. Never publish or describe a possible finding. Target-scroll maps, triage lists and verdicts belong in Scrolls-private or its ignored local data directories. The prize terms forbid disclosure before the official announcement. This repository is public.
  2. An ink map is model output, not a reading. Never write that letters were found or read.
  3. Preregister before looking. Readout rules are fixed (python -m kit run init, or a committed file in docs/prereg/) before any target map exists.
  4. Every check must be able to fail. Device agreement needs a control (kit verify --control); AUC needs the reverse-depth map as control.
  5. Cite real URLs and dates for facts about prizes, people and published results. Label claims: Sourced fact, Community report, Model output, Interpretation, Untested idea (docs/NOVELTY.md).
  6. No scroll data, maps or weights in git.
  7. kit/ changes need tests in tests/.
  8. Nothing outward without the user's go-ahead: no posting, submitting, renting compute or opening upstream PRs. Forum posts, Hugging Face uploads and Spaces are allowed, each only after the user says yes to that post, and never with private work or target-scroll data (user decision, 2026-10-13; it lifts the 2026-10-07 ban). Standing yes (2026-10-18): an agent may redeploy a Space Chase already approved, from merged main, with public data only, and may publish a GitHub release, not marked Latest, whose files are byte-identical to a merged PR or an approved package branch; each gets a handoff row and a live recheck. Since 2026-10-21 a package released from Scrolls-private to GitHub (a PR into this repository, or a release not marked Latest) needs no review of its file list by Chase: it goes out once it passes an agent leak and quality review that finds no private work, possible findings, target-scroll data, held-out labels or Discord text, and Chase gets a list of what went out. Since 23 Oct 2026 an agent may push to this repository and open or update PRs here without Chase's OK on each text, once the leak check kept in Scrolls-private (run on the diff, the commit messages and the PR text) passes and the agent's own review finds nothing private; a pre-push hook runs it. New Spaces, model cards, posts and prize submissions still need a yes for each.
  9. Log local compute. Wrap every local run (Mac CPU or MPS) with python -m kit run local SLUG -- COMMAND so wall time and electricity cost reach the ledger (docs/compute.md).
  10. Style: plain sentences; never U+2014 or U+2013 dashes; commit messages end with the session's attribution lines.
  11. Paid compute runs on Hugging Face (user decision, 2026-10-23; it replaces the Modal rule of 2026-10-08 to 10-21). Before starting any job, estimate its time. On Chase's Mac a CPU job runs locally unless it would take over 10 minutes there; in a Claude cloud container it runs locally when it fits the container, finishes within about 30 minutes and adds under about 5 GB to the disk (2026-10-18); otherwise, and for any GPU work, it runs on Hugging Face: a Hugging Face Job, ZeroGPU or the inference router. No new paid Modal launches: Modal is kept only for jobs already running and for history, so docs/compute/modal-pricing.md, docs/compute/modal-specs/ and kit/cloudcost.py describe past runs. Launch rules, per-run caps, the run ledger and the spend guard are in Scrolls-private's AGENTS.md rule 10 (access required); follow them for every paid launch. Only generic, public-data jobs are described here; anything about a target scroll belongs in Scrolls-private.
  12. Public writing for villa and the community (user decision, 2026-10-12). Issues, PRs, comments and prize submissions get a clear, specific title that says what is wrong or what changes. Use the community's established villa and VC3D terms; never our internal names (growcut, arm B, autopipeline and the like) unless the text defines them. Keep it short, in the user's own voice, with no long dashes. Maintainers close issues with unclear titles, invented terms, or text that does not read as written by the person. Agents draft; the user posts to villa. Guide: docs/AI-AGENTS.md.
  13. Check the docs index before you research or write (user decision, 2026-10-13). docs/README.md names one home per topic. Read the home and grep docs/ first; extend the existing note instead of starting a new one, and add any new note to the index. Do not repeat research that is already written down.
  14. One handoff (user decision, 2026-10-13). docs/HANDOFF.md is the only handoff for this repository and every agent: update its open-items table when you start or finish something, link longer notes from their row, and merge it into main at milestones: a launch, a collected result, a decision from Chase, and always before you stop. The handoff change may ride in the PR of the work it describes (2026-10-18). Private work hands off only in Scrolls-private's docs/HANDOFF.md.
  15. Releases list themselves in the README (user decision, 2026-10-14). Whatever is released from Scrolls-private into this repository adds its entry to docs/releases.json in the same change, with python -m kit releases add ENTRY.json, which rewrites the README's "Released tools" section from that list. One entry per standalone product; command-line kit tools share the Scrolls kit entry (user decision, 2026-10-20). A new version or fix of a released product replaces that product's entry, under the same id and title, and a new version of a kit tool replaces its line in the Scrolls kit entry's tools list under the tool's id, instead of adding another (user decisions, 2026-10-14 and 2026-10-20). AutoPipeline is pinned to the top of the section (python -m kit releases pin), so new releases go below it until Chase says to unpin it (user decision, 2026-10-14). Never edit the section by hand: python -m kit releases check, run by the tests, fails when it and the list disagree. The entry is part of the package's reviewed file list (since 2026-10-21, the agent leak and quality review of rule 8). For a Progress Prize package, the private exporter writes the entry itself and pushes it as a release-readme/<submission_id> branch for a PR into main.
  16. Tools (Chase, 16-17 Oct 2026): every tool and technique needs complete headless agent workflows and aims for competitive community performance. Every tool needs a page; follow the interface and evidence standard. Update its page in the same PR; start new pages with python -m kit.tooldocs new. New tools register as stage options; workflows pick stages through the registry, never hard-coded (25 Oct).
  17. Terminal look (Chase, 23 Oct 2026): every terminal gets one styled look, spacing and mouse, with no install step. Every command posted for Chase must render in it: a kit command, or a script whose main() calls termstyle.script() behind an isatty() guard, with child commands through termstyle.run(); try it in a pseudo-terminal first. Print plain lines and let kit.termstyle style them; draw panels and tables with its helpers, never hand-rolled color codes; keep --json and pipes plain; kit live -- CMD gives any output mouse scrolling.
  18. Token thrift (Chase, 6 Nov 2026; details). More work per Claude token, never less work. Batch independent tool calls in one turn. Search with git grep; never read a file over about 50 KB whole (docs/MAP.md, docs/README.md, docs/results.json): grep it, head, or read with offset and limit. Tail logs and test output. Pick the cheapest model that does the job as well: routine checks (CI, PR state, test pass or fail) go to the checker agent (Haiku), search and summaries to scout (Sonnet), and anything that decides a result stays on the session's model. Unsubscribe from PR events on a PR merged at once; start new large work in a fresh thread. Wait with PR subscriptions or --wait, never polling loops.

Standing user decisions

One line per decision still in force. The dated record, with every superseded decision, is in docs/DECISIONS.md.

  • Private plans, findings and submission material live in Scrolls-private (2026-10-07).
  • Leave docs/contrib/villa-1865-m1pro-comment.md alone (2026-10-07).
  • The decisions behind rules 8, 11, 12, 15, 16 and 17 (Hugging Face compute; posts, releases and pushes; villa writing; the generated Released tools section; one page per tool; the terminal look) are stated in those rules; their dates are in DECISIONS.md.
  • Call the owner Chase (Chase Hendrick), never Bob (2026-10-13).
  • AutoPipeline's short name is AP, defined once per document; write it in full for villa and the community (2026-10-14).
  • Public commits: author and committer Chase Hendrick <326338179+ChaseHendrick@users.noreply.github.com>; never another users.noreply.github.com address or an AI account (2026-10-14).
  • Public media: concept, synthetic and interface pictures; real-data stills, GIFs and short videos only from public scans that are not prize-eligible and show no held-out labels, at most 1920 px and 4 MB, with a credit sidecar; never model output, prize-eligible scrolls, volumes, segments or weights; hard rule 6 unchanged (2026-10-18, rule, record).
  • Merged branches are deleted automatically; start new work from main (2026-10-18).
  • Never ask Chase to paste a command into a terminal: after his yes, agents run steps that need his Mac (GitHub releases, local credentials) through a Remote Control session themselves (2026-10-24).
  • Every Space, now and future, gets a Connect your tool panel (kit spaceconnect, a connect.json per Space, listed in spaces/connect/spaces.json): data URLs and tested snippets for villa, VC3D, neuroglancer, Python and others' tools; data linked, never rehosted (2026-10-24).
  • Every Space keeps one page scroll bar: nothing inside a page scrolls on its own (onescroll.html from kit spaceconnect); one-screen viewers keep one scrolling list at most (2026-10-27).
  • American English in every Space, card and release entry; names from others keep theirs (kit spaceconnect spelling, run by check) (2026-10-27).
  • A frozen test may be rerun after a technical break, or after a noise-limited near miss on new seeds or sites preregistered first; each rerun is a new disclosed freeze with its attempt count and earlier result, never tuned on the spent result (2026-10-29).
  • Agents may use swarm bursts, many subagents at once each trying a different route, to solve problems; preregistration and freezing before any test, the held-out rules and rule 8 still bind (2026-10-29).
  • Token thrift: more work per Claude token, never less work; Sonnet for search and summary subagents (2026-11-06, rule 18).

Repository map and commands

One row per module and script: docs/MAP.md; grep it for a tool or a path. Top level: kit/ (the python -m kit package, standard library only except numpy, tifffile and zarr for the map tools; every subcommand in kit/cli.py), scripts/ (Mac GPU scripts in bash 3.2, the letter reader, the Center Finder, and scripts/experiments/: saved records of past public-data jobs, keep their wording), docs/ (indexed by docs/README.md; frozen evidence in docs/evidence/, do not edit), spaces/ (Hugging Face Space sources), tests/, experiments/ and templates/.

python -m unittest discover -s tests -v        # all tests; map tests skip without their numerical dependencies
python -m kit run all --dry-run --refresh        # AutoPipeline over every open-data bucket volume: priced plan, launches nothing
python -m kit auc MAP.tif --control MAP_reverse.tif --labels L/inklabels.zarr --mask L/supervision.zarr [--json]
python -m kit.tooldocs show auc --section "For agents"   # any tool's page, or one section of it
bash -n scripts/*.sh                            # syntax check; scripts must stay bash 3.2 compatible (macOS)

Off a Mac: SMOKE=1 EXPECT_GPU=cpu WORK=<scratch dir> bash scripts/mac-w045.sh. Never edit a script in place while a run of it is going; replace files atomically.

Glossary

Term Meaning here
ink_9um The team's released 9 µm ink model (scrollprize/ink_9um), seeds 42 and 43 at step 75,000
v8in Youssef Nader's ResNet3D-50 ink model (YoussefMoNader/ink-8um-v8in, 2026-09-28); v8in-1447 is its PHerc1447 fine-tune
d9v2, Reader v2 Community fine-tunes of ink_9um (TAUIL-Abd-Elilah; Domenico Russo); drop-in ink_9um checkpoints
w035 PHerc0139 training segment: a pipeline check only (the model reproduces its own labels there)
w045 PHerc0139 segment unseen by v8in but not held out from ink_9um, which trained on its 2.4 um render (pherc0139-w029); d9v2 and Reader v2 inherit that, and Reader v2 also trained on it; so did Hecate and its base model (log, exposure log)
PHerc0841 Scroll with labeled segments w00, ag896, ag405, in the training data of none of ink_9um, v8in, v8in-1447, d9v2 and Reader v2: the fair generalization test for them. Not held out from Hecate: its base model's committed trainer lists all three segments, although Hecate's own published split rule, applied to the published masks, would keep PHerc0841 validation-only (log, held_out in results.json)
AUC Probability a labeled ink pixel scores above a labeled background pixel, inside the supervision mask
As stored / reversed Depth order of the surface volume; reversed is the control and should sit near or below 0.5
Crop, --inner 64 The 640 px window of densest labeled ink per segment; 64 px edge left out so bare-crop and full-map scores match
QUICK mac-w045.sh mode that scores everything on the crop only
Atlas rodriguescarson's renders of 340 automatic meshes on eligible scrolls
Provenance digest SHA-256 over a run's record; publishable alone as a timestamped commitment