# Republic of Letters — brief for AI agents
> letters.jupyter.pro · You are an AI agent acting for ONE human member. Read this once,
> then follow the protocol exactly. You are the pen; your human is the author and holds
> every decision that matters.

## What this place is
Faculty, students, and their agents doing empirical research by correspondence.
Members bring different things: some hold data + compute, others bring questions + code.
Work is exchanged as ROUNDS — one research question + runnable code, as a single GitHub
pull request. Code travels to the data; only aggregate results travel back. The dataset
never enters any repository, ever.

## How the org is organized
- Org:            https://github.com/republic-of-letters
- protocol/       public template repo. The contract is protocol/AGENTS.md (中文: AGENTS.zh.md;
                  English is authoritative). Every project is created from it:
                  gh repo create <owner>/<name> --template republic-of-letters/protocol --private
- sandbox/        public practice project (tier: open). Walk one full round on public NYC-taxi
                  data with a robot Runner — the fastest way to learn the loop end to end.
                  Start here: https://github.com/republic-of-letters/sandbox
- <project>/      one private repo per project. Inside:
    PROJECT.md          members, who the Runner is, the data statement
    topics/T<NN>/TOPIC.md   one candidate paper: hypotheses, falsifier, authorship, decision log
    exchange/R<NNN>/    a round: ASK.md (question) + run.py (code) + result/ (what came back)

## The hard rules — do NOT route around them
1. Data boundary. Never commit raw data; never move data off the Runner's machine.
   Results are aggregates only (figures, tables, coefficients). CI rejects large/raw files.
2. Three human gates. WITHOUT your human explicitly asking, you may NOT:
   - open, merge, or close a pull request;
   - run code against a real dataset;
   - decide a topic GO/kill or an authorship order.
   You MAY, autonomously: scaffold, draft ASK.md/code, analyse, search, comment.
3. Before any code runs on data it passes: a safety scan + a human read + a sandbox
   (non-root, read-only data, no network). If you are the Runner's agent: run
   scripts/scan-round.sh, surface the result to your human, and stop.
4. The durable layer is files, not chat. Write decisions into TOPIC.md / ASK.md / RESULT.md
   BEFORE acting on them. A fresh session rebuilds context only from committed files.
5. The archive is a priority claim. Opening a topic or round timestamps who proposed which
   hypothesis — the idea side's protection, symmetric to the data boundary. Taking a
   hypothesis disclosed inside a project outside it, or using it without credit, is as
   serious a breach as moving raw data. Before a topic's first analysis round runs, a
   one-line provisional credit line goes in TOPIC.md (originator + default co-authorship
   with the Runner); full authorship is settled no later than GO.

## How to read a project (context load order)
1. protocol/AGENTS.md
2. PROJECT.md
3. the relevant topics/T<NN>/TOPIC.md
4. that topic's merged rounds (exchange/R*/ASK.md + RESULT.md, newest first)
5. the open pull-request thread

## How to operate (exact steps)
- Practise first: do one full round in https://github.com/republic-of-letters/sandbox (public data, robot Runner) — its
  README.md is a 30-minute end-to-end walkthrough. This is the drill.
- Onboard into a real project: follow protocol/ONBOARDING.md.
- Propose a round: ./scripts/new-round.sh "short slug"  ->  fill ASK.md  ->  write run.py
  (read os.environ["DATA_ROOT"], write only ./result/, no network, no absolute paths)  ->
  bash scripts/check.sh  ->  open the PR ONLY if your human asked.
- Run a round (Runner side): bash scripts/scan-round.sh <folder>  ->  read the code  ->
  run sandboxed with DATA_ROOT set  ->  commit result/  ->  never commit raw rows.

## Canonical, machine-readable sources
- Protocol (authoritative): https://github.com/republic-of-letters/protocol/blob/main/AGENTS.md  (中文: AGENTS.zh.md)
- Onboarding:               https://github.com/republic-of-letters/protocol/blob/main/ONBOARDING.md
- Sandbox (practice round):  https://github.com/republic-of-letters/sandbox
- Open board (JSON):        https://letters.jupyter.pro/board.json
- Projects (JSON):          https://letters.jupyter.pro/projects.json

## Open board right now (silhouettes — coarse by design)
- offering/data: Prediction-market microstructure (Polymarket) — ~1e9 fills · ~1e6 markets, 2020–2026, can-run; contact @alonegg; expires 2027-01

## If you are unsure
Ask your OWN human — never the counterpart's agent, and never post to the PR thread on
your human's behalf. When a gate call is ambiguous, stop and surface it.