Agent quick-start
zuppo-axi speaks forge APIs; vcs-axi manages local git/jj work. Neither is MCP.
zuppo-axi speaks forge APIs; vcs-axi manages local git/jj work. Neither is MCP. Build zuppo-axi from this workspace; vcs-axi lives in its own repository and must be installed separately. Read each installed command's --help: no aliases from the plan are implied.
Identity first
A person signs in with zuppo-axi auth login (device consent) or the web UI. Credentials are saved mode 0600 in ~/.config/zuppo/credentials.json. An agent instead receives ZUPPO_TOKEN from its runner's consented grant; set ZUPPO_HOST, ZUPPO_REPO=ORG/REPO, ZUPPO_ORG=ORG. HTTP is allowed for localhost evaluation only. Private CAs use SSL_CERT_FILE. Never copy the person's credentials file into the agent sandbox. Inspect auth status and grant show before work; scopes alone do not bypass sponsor, envelope or protected-path checks.
The following runnable evaluation continues after self-host setup and the API first call. The operator seeds main, registers a sponsored agent, records its session and explicitly issues a small envelope. This trusted local operator path is useful for an air-gapped alpha evaluation, not a replacement for person consent in a multi-tenant runner. In the web UI, Start implementation / GrantService.CreateGrant issues the once-shown token after the sponsor confirms the envelope; RevokeGrant ends it.
git init -q -b main seed git -C seed config user.name 'Docs User' git -C seed config user.email alice@example.com printf '# Demo\n' > seed/README.md git -C seed add README.md git -C seed commit -qm 'Initial commit' git clone -q --bare seed seed.git zuppo admin --state "$ZUPPO_STATE" import orgs/acme/repos/demo "$PWD/seed.git" jq -n --arg person "$DOC_PERSON" --arg host "$ZUPPO_HOST" '[ {register_agent:{org:"acme",agent:{id:"agt_docs",sponsor:{person:$person},max_role:"writer",client_id:null}}}, {put_session:{name:"orgs/acme/sessions/ses_docs",agent:"agt_docs",sponsor:$person, model:"local-evaluation",state:"SESSION_STATE_ACTIVE"}}, {issue_grant:{org:"acme",subject:$person,actor:["agt_docs","ses_docs"],client_id:"zuppo-axi", scopes:["repo:read","change:open","change:write","session:read","grant:request"], access_ttl_secs:3600,detail:{locations:[($host+"/acme/demo")], refs:["refs/changes/**","refs/heads/zuppo/**"],paths_allow:["docs/**"],rfc:null,stack:null, budget:{points:100,points_per_minute:60,lifetime:[null,null,null,null,null,null,null]}}}} ]' > agent-commands.json zuppo admin --state "$ZUPPO_STATE" apply agent-commands.json > agent-token.json ZUPPO_TOKEN=$(jq -er '.issued[0].access_token' agent-token.json) export ZUPPO_TOKEN zuppo-axi auth status zuppo-axi grant show curl --fail --silent --show-error -H "Authorization: Bearer $ZUPPO_TOKEN" \ "$ZUPPO_HOST/v1/orgs/acme/sessions/ses_docs" | jq -e '.session.agent == "agt_docs"' zuppo-axi code read README.md
Reads may see repository content beyond the writable envelope; it is write scope, not a promise of per-file read isolation. In a real RFC, bind the grant's rfc to the approved design and envelope hashes, not null. The example uses a 100-point/hour envelope; increase only with sponsor consent. Sessions record declared model/decisions/outcome; SessionService reads them, it does not offer a fictional zuppo-axi session start command. The runner/operator writes session records (put_session); transcripts are optional, not uploaded by default.
Clone-free changes
Open a whole stack in one call, ordered bottom to top. Each file entry contains whole file content, not a local filename. base can pin a commit; otherwise the target branch is used.
cat > stack.json <<'JSON'
{"target_branch":"main","changes":[{"id":"s1","title":"Document the demo","description":"A clone-free documentation change","files":[{"path":"docs/hello.md","content":"Hello from a sponsored agent.\n"}]}]}
JSON
zuppo-axi --json change open-stack --manifest stack.json > stack-result.json
CHANGE=$(jq -er '.changes[0].change' stack-result.json)
export CHANGE
zuppo-axi change view "$CHANGE"
zuppo-axi stack list
mkdir -p docs
printf 'Hello from a sponsored agent, revised.\n' > docs/hello.md
zuppo-axi change revise "$CHANGE" --base r1 --files docs/hello.md
zuppo-axi change view "$CHANGE" --since r1--base is a concurrency precondition, not a force switch. Stale-base replies name a structured conflict; read/reconcile instead of overwriting another revision. A stable idempotency key makes uncertain retries safe. TOON is the compact default; --json is for programs. Lists show totals; --full avoids truncation. Exit 1 is a server/action error; exit 2 is usage. Errors are on stdout, so check the exit code as well as parsing JSON.
Use review findings, checks failures and wait on a change/stack as reported by --help. wait --after uses the last event sequence and polls at most 25 seconds per request; persist the sequence between runs. Ask grant request --reason for added paths/refs; the sponsor decides. Use grant narrow only for a strict subset when delegating. Agents cannot mark ready, approve, enqueue/merge or edit protected CI/review policy. Independent people review every shown hunk; the author, sponsor and delegator cannot approve. CI's tool principal, not an agent's declared check, satisfies required checks on the current head.
Local stacks with vcs-axi
Install vcs-axi from its separate checkout with jj available for the jj backend (or choose its git backend). vcs-axi --help, vcs-axi push --help and vcs-axi stack --help are the installed interface. On an existing local stack whose remote points to Zuppo, vcs-axi push --stack --for main publishes refs/for/main; it does not push directly to protected main. The runner must supply git credentials for a git-audience token; an API-only token cannot push. To translate already pushed local commits to a forge stack, zuppo-axi change open-stack --from-local reads vcs-axi stack --json; it does not upload missing objects.
Choose the cheapest checkout: clone-free reads first; zuppo-axi checkout supports workset sparse tier 1, snapshot tier 2, read-only mount tier 3 and full tier 4. Consult its help for arguments. The tier-1 dependency closure can hydrate missing files in a batch. Tier 3 needs Linux FUSE (on this Mac use a Colima VM), not an invented native macOS mount. git-remote-zuppo is a separate optional helper for bundle downloads/resumable pushes; ordinary git also works.
The RFC 212 day
The complete, executable walkthrough is scripts/rfc212-day.sh, with scenario details. Run from the repository root; it starts its own isolated zuppo serve, cleans up its own server/temp state, and replaces the output directory named below. Pick a new output path, not one containing work you want to keep.
scripts/rfc212-day.sh smoke /tmp/zuppo-rfc212-docs
| Stage | What to observe |
|---|---|
| Brief and consent | Approved RFC 212/envelope; Mina sponsors Claude/Codex with separate grants/sessions |
| First two slices | Claude reads clone-free and creates the initial stack with the files manifest |
| Local continuation | Codex adds slices on the local stack and publishes through refs/for/main |
| Trust refusals | Out-of-envelope/protected-path writes and agent ready/approve/merge attempts fail |
| Review and correction | External reviewer reports a blocker; the next session fixes/restacks; people review actual hunks |
| Landing | CI reports required checks, a person marks ready/enqueues; the queue lands the atomic stack |
| Evidence | day.json, agent command logs and forge/ grants/sessions/events/queue/audit/attestations |
smoke uses scripted agent sessions and plain git in place of vcs-axi; it proves the local workflow, not real model reasoning or a vcs-axi live run. beta additionally exercises queue lanes/barriers, conflict API, tier-1 dependency closure/helper and Docker sandbox (explicit SKIP without Docker). real uses headless agents and vcs-axi from VCS_AXI_DIR/VCS_AXI, needs provider credentials, has time/spend caps and incurs model charges: it is never part of the fast documentation test. Session model names are declarations, not proof of the model used. Read the script header before opting into those modes.
Documentation checks
From the repository root, python3 scripts/doc-test.py builds the two local binaries if needed, starts a loopback-only forge on temporary state, then executes every sh runnable fence in self-host → API → operations → this guide. No external account, browser, model or Docker is used; server/temp files are always cleaned. --contract-only checks the generated endpoint table without starting a server. Build time is separate from the reported smoke runtime.