Getting started with PANTRY

PANTRY is an app, not a layer: a single server you drop into any project that composes BATCH, GRAIN, MILL, and PROOF into one "developer cockpit". Run it in a project and you get that project's task board, framework docs, generated component and vocabulary references, and machine-readable indexes. PANTRY also gathers run reports, artifacts, decisions, and a project timeline into the same local cockpit. Nothing imports PANTRY; it imports the layers below it. This page is the fastest path from a bare project to a running cockpit. The full design lives in PLAN.md; the composition itself (which route comes from which layer) is documented in WHAT-IT-COMPOSES.md.

Two terms worth pinning down before anything else, since PANTRY's own README leans on them without defining them:

• "Host project" is whatever project you run PANTRY inside. PANTRY calls it that throughout its own source and config, so this page does too.
• "AI-legible, not AI-powered" is PANTRY's one hard constraint: it runs no language model of its own. It never calls an API and never generates text. What it does is expose your project's plans and docs as plain, fetchable JSON and text (/knowledge.json, /llms.txt) so your own coding agent can read them while it works. PANTRY is a librarian, not a chatbot.

Install

Unlike the layers below it, PANTRY is not published to a registry: it is an app, consumed as a Bun git dependency pinned to a commit. Add it as a dev dependency (it's tooling for the project, not something the project ships):

bun add -d @tjakoen/pantry@github:tjakoen/pantry#main

Nothing else to configure: the @tjakoen/* layers it pulls in behind it live on the public npm registry, so there is no .npmrc and no auth token anywhere in this. (Those layers sat on GitHub Packages until 2026-07-30, which required a read:packages token even though they were public.)

That one install brings BATCH, GRAIN, MILL, and PROOF with it as regular dependencies, plus the portfolio package (tjakoen.github.io) which is where BATCH's and GRAIN's explanatory docs and the personal writing standards are canonically homed. You do not add those separately.

Scaffold, then run

bunx pantry init             # scaffolds plans/ + pantry.config.json in the current project
bunx proof check              # lints the scaffolded plans (pantry init delegates plan scaffolding to PROOF)
bunx pantry serve              # boots the cockpit; prints a local URL (default port 4400)

pantry init is non-invasive: it only ever writes new files. It never touches an existing CLAUDE.md, never overwrites an existing pantry.config.json (unless you pass --force), and never moves or copies any docs your project already has. What it creates:

• plans/, a starter plan (000-welcome.md) and plans/README.md, via PROOF's own init (PANTRY mounts PROOF's board, it doesn't reimplement plan scaffolding).
• pantry.config.json, a minimal starting config: your project's folder name, plansDir: "./plans", docsDirs: ["./docs"].

After that, edit pantry.config.json to point docsDirs at wherever your project's own docs already live (see Config, below), then bunx pantry serve.

The hard rule: PANTRY is a lens, never a destination

Everything PANTRY renders, it reads from your files in place. It never copies your plans or docs into itself, never moves them, and never edits the framework docs it bundles. Your plan files stay the single source of truth for the plan board; the board at /plans is a read-only projection of them. If you're handing the install off to a coding agent rather than doing it by hand, INSTALL.md (bundled with the package) has a copy-pasteable prompt block that states these rules explicitly to the agent, plus the exact numbered steps above.

Config

PANTRY reads an optional pantry.config.(json|ts|js) from the host project's working directory. Every field is optional; a project with none of the below still runs with sane defaults.

The machine-readable indexes (/knowledge.json and /llms.txt), the mindmap (/map and /map.json), the About page, and the shared event stream are not individual surfaces toggles. Some configurable surfaces still disappear when their required source or package is missing.

Run it

bunx pantry serve --port 4400   # -p also works; default port is 4400
bunx pantry check                # CI-able: lints doc bodies for dead in-namespace links, exits nonzero on a break

Bare bunx pantry (no subcommand) is the same as pantry serve. On boot it prints the surfaces it mounted:

PANTRY cockpit on http://localhost:4400
  /          this project's cockpit
  /plans     this project's plan board
  /docs      the framework docs + this project's
  /reference the generated AI vocabulary + token slots
  /catalog   the GRAIN component catalog
  /runs      the run ledger
  /artifacts the run evidence shelf
  /timeline  the project history

A surface whose underlying source is missing (no plans/, no docs folder, the portfolio package not installed for /standards) disables itself quietly rather than erroring: the route and its nav link just don't appear. pantry check is a separate, narrower thing from proof check: it lints your doc prose for links that point at a route or .md twin the cockpit doesn't actually serve, so a renamed doc collection or a deleted page shows up as a build failure instead of a silent 404.

Read context and answers honestly

Doctor's context-size measurement reads Claude Code instruction and memory files. It honors CLAUDE_CONFIG_DIR when selecting the account and names that directory in the result. It does not measure Codex's context. Session-event discovery also depends on the configured event log; an absent emitter is an observation gap, not evidence that no development took place.

The answer channel distinguishes a missing log from an unreadable one. Malformed records are counted and valid records remain inspectable, while the CLI, JSON endpoint and doctor disclose that unread answers are unknown. Repair the log before waiting for or acknowledging answers; a corrupt inbox must not look like completed work.

Try it against one development task

Run the cockpit from the host repository's working directory, then use it to find the current plan, read the latest run's evidence, and identify any unanswered decision. Compare those steps with reading the same files in the coding agent. The board and rendered reports can help a reviewer inspect work; they do not replace the files or make a second task system necessary.

Keep doctor and plan checks available without running the dashboard. A live-session view requires an enabled control surface and a configured event feed. It does not discover native Codex chats automatically. If that feed is absent, zero observed sessions means no observations, not no activity. Similarly, an old report missing the expected schema is evidence about that report's format, not proof that the underlying code was never tested. Inspect the missing fields before turning such counts into a queue of work.

Adoption should earn its setup cost on this task. If the dashboard adds duplicate navigation while the CLI checks catch real failures, keep the checks and leave the dashboard optional. Choose an integration only after identifying an action the current workflow cannot already perform as well.

Compose it yourself instead

If you're building your own server rather than running PANTRY as-is, you don't have to import PANTRY at all (it isn't offered as an importable layer, by design). Import createProofRoutes and createMillRoutes straight from @tjakoen/proof and @tjakoen/mill into your own app; PANTRY's own app.ts is the reference implementation of exactly that composition. See WHAT-IT-COMPOSES.md for how the pieces fit together.

Next steps

• Read WHAT-IT-COMPOSES.md for how BATCH/GRAIN/MILL/PROOF each contribute a piece of the cockpit, what every mounted surface actually is, and what the "AI-legible" surfaces return.
• Read BATCH's getting-started and GRAIN's getting-started for the two layers PANTRY runs on top of.
• The canonical, most detailed source is PANTRY's own PLAN.md and INSTALL.md, bundled with the package.