AmbitGet startedFAQReferenceGlossaryAll docsGitHubLive demo

Contributing

Fork → branch → commit → PR. This file gets you from a clone to a passing PR. AGENTS.md is what a change must not break, and it names the guide that maps each part of the code. The deep dive is what the model means: what a node is, what a check proves, what an authority grant does. The README is what Ambit is for.

Setup

git clone https://github.com/zz-plant/ambit.git
cd ambit
./bootstrap.sh

Node 22.18 or newer, and nothing else. CI runs 22 and 24. The engine, the CLI, the API server and the test runner all open the graph through node:sqlite; the visualizer is Vite, which runs on Node too. A checkout keeps its graph in the checkout (toolchain-viz.db), so your working graph is never the one an installed copy uses — ambit where prints the path either way.

./bootstrap.sh web does all of that and then serves the map on :3000, which is worth opening once before you change anything behind it. Once you are editing the client, npm run dev runs the API on :3001 and Vite on :3000 together.

You can also open the repository in Codespaces; the devcontainer seeds a graph and starts the map, so nothing needs installing to read the code and the canvas side by side.

Iterate on the site

From a fresh worktree, run npm ci and then npm run dev:fixture. Open the URL Vite prints, normally localhost:3100/ambit/. Vite waits for the API before listening and reloads client edits. The API on port 3101 reads a temporary SQLite graph and OpenCode config. You can try the My Setup switches and discard the session with Ctrl+C. Set both AMBIT_WEB_PORT and AMBIT_API_PORT if another worktree uses those ports. Use npm run dev for your own setup.

The fixture's Briefing shows what an agent receives when it connects. Briefing and Environment require the local API.

The hosted demo and its plain-text index work without a local server. For a local preview of the published docs, run npm run build and npx vite preview, then open /ambit/docs/ on the URL Vite prints.

Use the same screenshot cases at each stage. Chrome is found at the default macOS path or via CHROME_PATH pointing to the executable.

npm run shots -- --help
npm run shots -- --only map-rest --size phone --strict
npm run shots -- --url http://localhost:3100/ambit/ --live --only live-setup --strict --out output/shots/dev
npm run shots -- --url https://zz-plant.github.io/ambit/ --only map-rest --size phone --strict --out output/shots/prod

Without --url, the runner makes and serves a temporary production build. With --url, it visits the running site as served. Open index.html in the output directory for the contact sheet or read report.json for the target, frame findings, and each page's published revision when present. --strict fails when a frame is flagged. After the Pages workflow completes, add --expect-revision <full-commit-sha> to fail if any page is still serving a different build or has no revision.

The checks CI runs

Every push and pull request runs all of these, twice, on Node 22 and Node 24. Running them locally first is faster than a round trip, and npm run check runs them all, one line each, with the fix beside a failure (npm run check -- --fast is lint, typecheck and the suite):

npm run test:coverage        # the suite, plus the coverage floors a bare `npm test` does not apply
npm run lint                 # Biome, formatting included
npm run build                # typechecks both projects, then builds the client
npm run assets:check         # the shipped images are the right shape, and the hero GIF is not stale
npm run prose:check          # the corpus ceiling on em dashes and "rather than"
npm run docs:examples:check  # every console block in the README still matches what the command prints
npm run demo:check           # the published demo still matches what the engine would build from its fixture

CI also runs ./bootstrap.sh against a machine with no agent config, because that is the first thing a new user does and it is the path that has broken twice.

A separate job runs scripts/windows-smoke.ts on Windows, since the suite itself assumes a POSIX shell.

One more workflow, reach.yml, asks a different question: whether merged work gets to main. It fails a pull request whose base is neither main nor the head of an open pull request on its way there, and on every push to main and once a day it fails if any merged pull request never reached main. npm run reach:check asks the same with your gh login.

The last three commands are the ones an ordinary change trips. prose:check measures the whole corpus, not your paragraph: it fails when a pass pushes either of the two constructions it counts past the ceiling in scripts/check-prose.ts. That ceiling sits above where the corpus stands, so the next drift up fails and every improvement can lower it. docs:examples:check re-runs the real commands behind the README's console blocks, so a block that stops matching is a fact that moved, not a typo. demo:check rebuilds the published demo from its fixture, which is how a model change fails at the commit that caused it instead of going stale in a screenshot nobody reopens.

What is worth contributing

Three kinds of change are small, self-contained, and worth more than their size. They are the standing list: no backlog of scoped issues sits behind them, and an issue carries good first issue once somebody files one against them. Start from a bullet.

The nine eras and their dependencies are curated and encode opinions that deserve argument — whether a capability is real, what it genuinely requires, which era it belongs to. Open a capability-model issue rather than a PR if the change is a judgment call.

Sending it

Branch off main and keep the pull request to one thing. The template's checklist is conditional, so most changes tick nothing: it asks only when the change touches the API server, where the graph is stored, the curated tree, or the set of runtime readers and declared checks, and each question is the one a review would ask anyway. A first pull request gets an automatic reply, then a person.

Stacked pull requests. When one pull request is based on another's branch, merge the bottom one, then retarget the next one up to main before merging it. Merged into the old base instead, its work stops on a branch nothing will merge again: that is how #97, #98 and #99 were merged and never shipped. The reach check fails the next one up as soon as the bottom merges, which is the time to retarget it.

Things to keep true

The invariants a change must not break are stated once, in AGENTS.md. Two of the four under Security posture bear on ordinary changes: loopback only, and no entry creation over HTTP. Two more are numbered rules: one resolver decides where the graph is, and nothing that travels may execute. Each is one line there and in full in the guide for its area: read the servers guide before touching src/server/api.ts, and the engine guide before sync.ts or anything under assure/.

Release and launch mechanics, including the directory-submission table, live in .github/launch-kit.md.