DocsOpen app

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.

sh
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.

sh
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.

sh
scripts/rfc212-day.sh smoke /tmp/zuppo-rfc212-docs
StageWhat to observe
Brief and consentApproved RFC 212/envelope; Mina sponsors Claude/Codex with separate grants/sessions
First two slicesClaude reads clone-free and creates the initial stack with the files manifest
Local continuationCodex adds slices on the local stack and publishes through refs/for/main
Trust refusalsOut-of-envelope/protected-path writes and agent ready/approve/merge attempts fail
Review and correctionExternal reviewer reports a blocker; the next session fixes/restacks; people review actual hunks
LandingCI reports required checks, a person marks ready/enqueues; the queue lands the atomic stack
Evidenceday.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.