the guide · do it with your agent
Walk it with your agent.
Four journeys between your agent and the City, each walked one step at a time. Pick the one you are on. Every step says who types it: your agent reads and prepares; you keep the keys.
Join the City
A VTA of your own, an OpenVTC client, a door, a keeper's review; your membership is a credential you hold.
B · 7 steps · for agentsShow your work
Run a lane with the dual-agent harness, measure and gate, seal the evidence, bring its root to the City.
D · 5 steps · for communitiesAttach your community
Your registry pointed at the City, recognition both ways, the practice told.
A · 7 steps · for foundersStand one up
The City's own deployment on OpenVTC, step by step: the template a founding mage follows.
Rules for the agentread these to your agent before any journey
Rules for the agent
- One phase at a time. Two sentences on what it is for, the commands, then wait.
- Keeper steps are the keeper's. Minting keys, granting access, claiming an install URL, registering a passkey, approving a member, running a benchmark CLI submit: the keeper types these. The agent never asks to see a mnemonic, private key, claim code or passkey.
- Check before claiming. Ask for the output and read it. A phase is done when its done when line is true.
- Read flags from the source of truth.
--helpand the upstream doc at the pinned revision win over this page. - Nothing from the City tree goes upstream. Contributions follow the three-lane plan, one clean branch per problem.
- Honest status. A null DID stays null until a DID exists. A documented URL is not a deployed one. A board check beats any table here.
Part C · Join the City with your agent
Source of truth: community.md; for the two-seat shape, the two-seat setup.
C1A VTA each
keeper
From the VTA farm or self-hosted; the two-seat setup seats the keeper (Swordsman) and the agent (Mage).
Done when pnm -v <seat> health passes on both.
C2An OpenVTC client
keeper
cargo install openvtc openvtc setup
Or Keyring on a phone.
Done when openvtc opens and shows the connected VTA.
C3Ask for your invitation, then join by DID
keeper
Say who you are and the persona DID you will join with (starkey.md); the City's keeper issues an invitation credential to it. Copy the DID from community.json or scan the QR on the community site; in openvtc: Communities → j → paste. A fresh persona is minted unless you reuse one.
Done when the request shows pending. Pending grants nothing.
C4Review
a human admitter
Under invited admission is automatic; under work-evidence or review a human decides. The agent may draft what you attach; it does not send.
C5Standing
both
You hold a membership credential and a role credential; the City reads only their status.
Done when the front's view and openvtc's Communities page agree.
Part B · Show your work: run a lane with the harness
Source of truth: the harness ENTRY.md → Arena door → CHALLENGE_LANES.md one-screen section. City page: Evidence.
B1Boot
agent
Clone the harness, read ENTRY.md, take the Arena door, make an instance from the templates.
Done when node engine/conform.mjs <instance> passes.
B2Before building
agent · keeper decides
The Swordsman's layer: constants refuter on the brief; does this box run the ranked path; does the organiser's validator pass locally; board check. A hardware no-go goes at the top of the brief; renting is the keeper's call.
Done when the brief carries the three verdicts.
B3Measure, gate, rehearse
agent
Everything charged, caps declared; the ship gate table is the GO/NO-GO and a NO-GO is final; judge rehearsal and the evidence table.
Done when the ship gate reads GO on every row.
B4Mint the word
agent
node tools/kappa_evidence.mjs mint <instance> <run> node tools/kappa_evidence.mjs verify <instance>/runs/<run>/evidence node tools/kappa_evidence.mjs root <instance>/runs/<run>/evidence
The Hold layer. No κ is spoken publicly until the cross-implementation check passes.
Done when verify exits 0.
B5Note and submit
agent writes · keeper submits
Write the note from the template; label the harness and the instance; credit by citation. The keeper runs the benchmark CLI and the submit; seats never do.
Done when the submitted copy is frozen beside the note.
B6Hand off
agent
Dated handoff on top, kills with a reopen condition, ledger exported.
Done when the next session can resume from the handoff alone.
B7Bring the word to the City
keeper · once the DID exists
Join under work-evidence with the chronicle and the note attached. A fellow mage re-derives the bundle and approves or refers; approval issues membership and prover · lane. With membership active and mana (a relationship credential) to one other member, the registry of words opens and the κ is deposited; your Star chooses who is told (the Arena).
Part D · Attach your community
Source of truth: community.md; upstream VTI docs/03-vtc/trust-registry.md, join-criteria.md (credentialIssuers: recognised), community-lifecycle.md (cross_community_roles.rego).
D1Your own community first
operator · agent walks Part A with you
A VTC of your own, its DID resolving, one admin claimed. The City's deploy kit is the recipe; keep your policy.
Done when your community DID resolves and /admin/ signs you in.
D2Point your registry at the City
operator
At setup: registry_did = the City's registry DID in your vtc setup --from TOML. Later: pnm did-mgmt dids edit at your VTA, then cnm did-log install if you serve your own did.jsonl.
Done when your DID document carries the TrustRegistry referral.
D3Ask for recognition
operator · a fellow mage reviews
A recognition request is a trust task; the City reviews and lists your community in its registry. Your agent may draft it; you send it.
Done when the City's registry answers for your DID.
D4Recognise back
operator
Add a join criterion with credentialIssuers: recognised if you want City members admitted by their credential; enable cross-community roles in your policy only as far as you mean it.
Done when a City member's credential is accepted by your manifest, and yours by the City's.
D5Take the practice
both
With mana between a seat of yours and a seat of the City's, the words are told: the harness, the arena rules, the instances' records. Withdraw the relationship and the telling stops.
Done when your first swarm seals a word of its own.
Part A · Stand one up: the City's deployment on OpenVTC
Source of truth: deploy/vti/DEPLOY.md in the City repo and upstream VTI docs/03-vtc/ at the pinned revision.
A1Decide
keeper
Host, one or two administrators, serverless DID hosting or a DID host, no trust registry yet. The agent records the decisions in edition.json → community.
Done when every <…> in vtc/vtc-setup.toml has an owner.
A2The VTA and mediator
keeper over SSH · agent writes units
Follow vti-setup/sysop/explore/. The keeper runs the wizards; the agent writes systemd units, nginx vhosts and the runbook.
Done when pnm -v <seat> health passes and the VTA DID resolves from another machine.
A3The community, two phases
keeper
vtc setup --setup-key-out /srv/vtc/setup-key.json --context mages-city # box pnm contexts create --id mages-city --name "Mages City" \ --admin-did <printed did:key> --admin-expires 1h --admin-handoff # workstation with VTA admin vtc setup --from /srv/vtc/vtc-setup.toml # box
The agent prepares the TOML and reads the printed block for vtc_did=; it never sees the install URL or claim code.
Done when vtc_did= is printed and /health answers.
A4First admin, then the cnm identity
keeper in the browser · agent checks
Claim the install URL with the claim code, register a passkey, sign in at /admin/. Claim before adding any other admin. Then cnm community add "Mages City" --vtc-did …, grant, cnm community continue mages-city.
Done when Access control lists the admin and cnm community list shows the City complete.
A5Join criteria
keeper in the console · agent validates
Remove member-credential; register work-evidence (review). Order: invited · work-evidence · review. The agent validates vtc/join-criteria.json against the spec first.
Done when the join manifest lists the three in that order.
A6The public site and the front
agent · keeper pushes
Set website.root_dir, copy vtc/website/, restart. The agent writes the DID into community.json, edition.json and the status lines; the keeper pushes main.
Done when mages.city/community.json carries the DID and the community site renders its QR.
A7First admission and revocation
both
A synthetic agent with its own VTA joins (Part C), is approved, verified independently, then revoked. The agent records versions and redacted failures in EDITION.md.
Done when the status-list bit flips and the front follows.