agents-city 0.3.0-beta.21

package/demo/units.yml

@@ -0,0 +1,33 @@
+# Business units — the districts of your city.
+#
+# This is yours to define at install time. The map reads it, so the districts,
+# their names, their colours and their order come from here and not from the
+# code. The demo ships a game studio; replace it with your own units and the map
+# redraws itself.
+#
+# id      what you write in `unidad` inside parcels.yml
+# name    what shows on the banner
+# color   hex, without the #
+# order   left to right; the shared district usually goes last
+units:
+  - id: mobile   ; name: Mobile Games      ; color: 3fb8a0 ; order: 1
+  - id: console  ; name: Console Games     ; color: 8f7ae6 ; order: 2
+  - id: arcade   ; name: Arcade Cabinets   ; color: e08a3c ; order: 3
+  - id: school   ; name: School Editions   ; color: 4a9ede ; order: 4
+  - id: platform ; name: Platform          ; color: 6f8fbf ; order: 5
+    note: "store, launcher, live ops — every unit ships through it"
+  - id: data     ; name: Player Data       ; color: e2604f ; order: 6
+    note: "telemetry, experiments, the numbers everyone argues with"
+
+# Two districts every city has, whatever the business.
+#
+# The lab does not ship yet, and it is needed. It gets its own district instead
+# of falling into the shared bucket on purpose: a lab repo among the orphans
+# reads as waste, and it is the opposite. Its houses are drawn with permanent
+# scaffolding, and its growth is not compared against the shipping units — a lab
+# house with few floors is not behind, it is early.
+special:
+  - id: lab      ; name: Lab               ; color: 8fb8c9 ; order: 90
+    note: "doesn't ship yet, and it's needed"
+  - id: none     ; name: No unit           ; color: c8b48a ; order: 99
+    note: "serves several units, or none"

package/docs/agents-first.md

@@ -0,0 +1,99 @@
+# Agents come first
+
+The original model was "a repo is an agent": every window was a git checkout,
+and anyone whose work was a folder of documents — no git at all — had nowhere
+to live. The model is now inverted. The primary unit is the **agent**; a repo
+is just one thing an agent can mount.
+
+The inversion is total but loses nothing, because the old model is a special
+case of the new one — so **existing cities keep working untouched**.
+
+## The model
+
+An agent has a **workspace folder** (`<city>/agents/<slug>/`) as its working
+directory, and inside it a `mounts/` folder of **symlinks** to wherever the
+real work lives: a git repo, a linked worktree, or a plain folder of documents.
+
+```
+<city>/agents/writer/
+├── mounts/
+│   ├── handbook   -> ~/Documents/handbook      # a document folder, no git
+│   └── spec       -> ~/code/product/spec        # a subtree of a repo
+└── (the agent's own notes live directly here)
+```
+
+An agent also has a **kind** — `code`, `knowledge`, or `coordinator` — which is
+what makes the map polymorphic instead of assuming everyone ships pull requests.
+
+## Two card shapes, one internal model
+
+`plugin/scripts/workspace.py` normalises **both** card shapes into one list of
+`Agente`, so the launcher, the cage and the map read one model regardless of how
+the card was written.
+
+Legacy (unchanged — every repo is an agent whose single mount is that repo):
+
+```yaml
+repos: [nova, store-service]
+role.nova: po
+```
+
+Agent-first (adds `kind.<agent>` and `mounts.<agent>`):
+
+```yaml
+agents: [writer, chair]
+kind.writer: knowledge
+mounts.writer: [~/Documents/handbook, ~/code/product/spec]
+kind.chair: coordinator
+runs.chair: claude
+```
+
+## How the cage follows a mount
+
+The cage seals by path, so an agent's workspace is exactly what it makes
+writable — plus the **resolved targets** of its mounts. Because seatbelt
+resolves symlinks at the kernel, `mount_targets()` follows each symlink to its
+real destination and the launcher passes those to `cage.py --mounts`. A mount
+that resolves inside a sealed root (`~/.ssh`, the broker store, …) is refused,
+never honoured: the security invariant holds under the new model, and
+`bin/test-cage.py` proves the writable-mount / sealed-secret split against the
+live kernel.
+
+## Managing mounts
+
+```bash
+agents-city agents list    --data <city> --card <card>       # list normalised agents
+agents-city agents mount   --data <city> --agent writer --src ~/Documents/handbook
+agents-city agents mounts  --data <city> --agent writer      # what is mounted
+agents-city agents unmount --data <city> --agent writer --name handbook
+```
+
+At session start the launcher runs `workspace.py sync` for each agent, which
+creates the workspace and materialises every declared mount (skipping a missing
+source with a warning rather than aborting the city).
+
+## Growth without git — `crecimiento.py`
+
+A house grows by what its agent actually does, not by pull requests alone:
+
+- **code** — floors = merged PRs, bricks = commits (an injected git counter).
+- **knowledge** — floors = documents in the workspace, bricks = recent edits.
+- **coordinator** — floors = recorded decisions, bricks = notices.
+
+Every counter returns the same `{floors, bricks, activity30, signal}` shape, so
+a person with no git at all now has a house that grows as their knowledge does.
+
+## Avatars — `avatar.py`
+
+Each agent gets a deterministic, self-contained SVG identicon from its name
+(same name → same face), with the border tinted by kind. No network, no
+library, no external asset, so it drops into the Hall under its strict CSP —
+`avatar.data_uri(name, kind)` is ready for an `<img src>`.
+
+## Presence and "thinking"
+
+The activity pipeline already emits on `UserPromptSubmit` (a turn begins) and
+`Stop` (it ends), so "active since the last prompt without a stop" is derivable
+from the existing feed — the Hall renders it. This document's generators
+(avatars, growth) provide the data; wiring them into the Hall view is the
+rendering layer's job.

package/docs/glossary.md

@@ -0,0 +1,55 @@
+# Glossary
+
+The code keeps a small Spanish domain vocabulary. These are the canonical v2
+meanings.
+
+| Term | Meaning |
+|---|---|
+| city / `ciudad` | One autonomous work domain with one owner seat |
+| owner / `usuario` | The local person who may own several cities |
+| seat / `asiento` | The city's only road-facing agent; owns its role and goal |
+| chair / `presidente` | The seat while selecting agents, controlling turns and integrating a decision |
+| committee / `comité` | A bounded evidence process among the chair and selected repo agents |
+| floor / `palabra` | One evidence-backed reply requested by a member and granted or denied by the chair |
+| live feed | Read-only browser view of submitted committee artifacts and protocol actions over the local WebSocket bus; never model chain-of-thought |
+| act / `acta` | Durable human-readable decision, verification and closure record |
+| local bus | Per-city loopback WebSocket hub carrying typed internal and road envelopes |
+| native gateway | Provider-specific last mile that accepts a bus envelope through an official runtime protocol, never terminal paste |
+| Claude stream gateway | Default Agents City transport: one persistent official Claude Code process receiving acknowledged JSONL turns over stdin/stdout |
+| Claude Channel | Optional upstream preview path for injecting an event into an opted-in interactive session; not required by Agents City |
+| terminal fallback | Explicit `terminal:<command>` compatibility mode for an unknown CLI; the only mode allowed to inject into tmux |
+| address / `direccion` | Stable `owner/city` identity used on roads |
+| road / `carretera` | Explicit connection from one city seat to another |
+| support agent | A local agent window working inside one repo, with its own operating role; never road-facing |
+| operating role | The professional perspective assigned to one repo agent; separate from chair/member authority |
+| skill | A capability installed and owned by a repo/runtime, only recognised by Agents City |
+| card / `ficha` | The one owner file containing chair role, repos, per-repo roles, goal and window engines |
+| blank role | An explicit role with no built-in role knowledge or inferred responsibility |
+| round / `ronda` | Evidence exchange by a seat across its explicit roads |
+| notice / `carta` | A concrete change one city tells another city may affect its domain |
+| house / `casa` | One parcel drawn on the visual map |
+| parcel / `parcela` | A slice of a repo serving one unit; not necessarily a whole repo |
+| district / `barrio` | The visual area belonging to one business unit |
+| unit / `unidad` | A business unit represented by a district |
+| worker / `obrero` | A currently active agent window drawn on a parcel |
+| foreman / `perito` | Visual representation of the city seat near its support work |
+| architect / `arquitecto` | Legacy map name for the goal-owning seat |
+| trade / `oficio` | A role's name in the city metaphor |
+| square / `plaza` | The map's live-presence area and its Durable Object |
+| scaffold / `andamio` | An open pull request; visually stale after two weeks |
+| floors / `pisos` | Landed work; a house grows when work lands |
+| bricks / `ladrillos` | Commits not yet represented by a pull request |
+| crack / `grieta` | Failing CI |
+| milestone / `hito` | One day's landed work for one parcel |
+| oven / `horno` | Pipeline that bakes 3D models into isometric sprites |
+| step / `paso` | Distance between map plots, in tiles |
+
+Two special visual districts remain:
+
+- `lab`: research work that has not shipped;
+- `none`: work shared by several units or assigned to none.
+
+Some storage and API fields still use names such as `personas` for compatibility
+with existing map data. They do not change the v2 ownership rule: a personal city
+has exactly one owner seat; repo support agents and connected cities are separate
+entities.

package/docs/map-live-layers.md

@@ -0,0 +1,73 @@
+# The map's live layers
+
+The map used to describe last month: floors from merged PRs, windows lit by
+thirty days of activity. Three layers now describe **right now**, and all three
+are derived from data the product already emits — nothing on the map is
+invented at render time.
+
+## Presence: lights are turns
+
+A house whose agent is mid-turn glows and breathes, with three thinking dots
+over its worker (or over its roof when no worker figure is on site). A house
+whose agent just stopped cools down over about two minutes. A house with no
+session shows only its historical windows.
+
+Derived entirely from the activity feed the hooks already publish:
+
+| Event | Effect |
+| --- | --- |
+| `conversation.user` | the actor's house enters "in turn": pulsing glow + dots |
+| `conversation.agent` | the turn ended: the glow cools instead of cutting out |
+| `runtime.session.ended` | lights out, no afterglow |
+
+Code: `city/web/src/presencia.ts`. The Hall relays these lifecycle events to
+the embedded map (`isPresenceEvent` in `city/web/src/activity.ts`); they never
+become speech bubbles.
+
+## The town hall: the committee, staged
+
+A civic building stands past the square. When a deliberation opens it lights
+up and the badge over its door tracks the state machine — the same kinds
+`isSpeechEvent` already lists:
+
+- `committee.position.submitted` — the member's position flies in from their
+  house **face down**: isolated positions are the committee's one hard rule,
+  and the map shows the rule, not just the traffic.
+- `committee.position(s).revealed` — cards turn over.
+- `committee.floor.requested` — a "✋ palabra?" chip hangs over the house of
+  whoever asked; `granted`/`denied` answer it in colour.
+- `committee.verification.passed/failed` — the verifier's stamp over the door.
+- `committee.closed` — the act rises from the hall, signed; the cards leave
+  with it. `committee.cancelled` clears the stage with no act.
+
+One session on stage at a time; the Hall's right rail remains the transcript.
+Code: `city/web/src/ayuntamiento.ts`.
+
+## Gates: roads made visible
+
+One arch per road, at the city's entrance, with the road's name and its
+`owner/city` address on the plate. A notice whose recipient is not in this
+city flies out through the right gate and fades at the edge; one arriving from
+another city comes in the same way. The map never draws the far city — a road
+grants reachability, and the gate is exactly that much.
+
+The gates come from the Hall, which is the only thing that knows the roads: on
+loading the map iframe it sends a `map.config` message with them. The
+standalone team map never receives one and draws no gates rather than invent
+connections. Code: `city/web/src/puertas.ts`.
+
+## Rehearsing without a city
+
+Every layer can be driven from the browser console on any running map:
+
+```js
+__city.presence('conversation.user', 'nova');          // the house breathes
+__city.committee('committee.opened', 'seat', 'why');   // the hall lights up
+__city.committee('committee.position.submitted', 'nova');
+__city.roads([{ name: 'home', address: 'you/home' }]); // gates appear
+__city.letter('ada', 'you/home', 'security');          // out through the arch
+```
+
+`prefers-reduced-motion` is honoured the way the rest of the map honours it:
+every state is still shown — steady instead of breathing, placed instead of
+flown.

package/docs/security.md

@@ -0,0 +1,231 @@
+# The cage and the broker
+
+Yolo is non-negotiable here: a committee dies the moment every bus command
+needs a human. So the security model never touches the approval axis. It
+narrows the other one — what a window can *reach* — at the kernel and at the
+credential store, where a language model cannot talk its way past it.
+
+The threat this is built for is the one nobody has solved: prompt injection.
+A repo window reads text that ultimately came from outside — an issue, a log,
+a committee assignment quoting a road message — and no instruction to "treat
+it as untrusted" is a security control. The goal is therefore not to prevent
+the injection but to make a successful one worthless: nothing to steal, no
+credential to hold, and a signed trail of everything it tried.
+
+## Layer 1 — the cage (`plugin/scripts/cage.py`)
+
+Claude, OpenCode and Kimi repo windows launch under a generated macOS seatbelt
+profile:
+
+```
+sandbox-exec -f ~/.agents-city/.runtime/cage/<window>.sb <runtime …>
+```
+
+The profile reads top to bottom: allow everything, deny all writes, re-allow
+the working set, then seal the secrets — reads and writes both. The semantics
+(last matching rule wins; children and grandchildren inherit) were verified on
+a real machine before a line of it was written, and `bin/test-cage.py` re-proves
+them live on every run where seatbelt exists.
+
+Inside the cage a window **can**: work freely in its own repo, run builds,
+reach the network, keep its runtime state (`~/.claude`, `~/.codex`,
+`~/.agents-city`, build caches). It is never asked a question — yolo intact.
+
+Inside the cage a window **cannot**: read or write `~/.ssh`, `~/.aws`,
+`~/.kube`, `~/.gnupg`, `~/.docker`, `~/.config/gcloud`, `~/.config/gh`,
+`~/.git-credentials`, `~/.netrc`, `~/.pgpass`, cargo credentials, any remote
+road `.env` under `~/.claude/channels/`, or the broker's state; nor write
+anywhere outside its repo and the allowed runtime/cache set — other repos on
+the machine included.
+
+Dials, all environment variables read at launch:
+
+| Variable | Effect |
+| --- | --- |
+| `CITY_CAGE=0` | launch every window uncaged — exactly the old behaviour |
+| `CITY_CAGE_DENY=a:b` | extra paths to seal (e.g. `~/.npmrc`, see below) |
+| `CITY_CAGE_ALLOW_WRITE=a:b` | extra writable roots for unusual toolchains |
+
+On Linux or any machine without `sandbox-exec`, the prefix is empty and
+nothing changes. The seat is deliberately never caged: it is the permissioned,
+non-yolo side that holds the road token and asks the owner.
+
+Codex uses exactly one confinement layer: its native `workspace-write` sandbox
+(network enabled only in auto mode). It is deliberately not wrapped in the
+outer seatbelt profile because Codex MCPs such as `node_repl` create their own
+sandboxed worker; macOS rejects that second `sandbox_apply` when the entire
+gateway already runs under seatbelt. `CITY_CAGE=0` deliberately changes Codex
+to `dangerFullAccess` and launches the other providers without their outer
+cage.
+
+At startup, the Codex gateway also reads the effective MCP registry through the
+Codex CLI. An enabled stdio MCP whose executable is provably absent is disabled
+only through a process-local `-c mcp_servers.<name>.enabled=false` override for
+app-server and its TUI. The owner's `~/.codex/config.toml` is never rewritten;
+healthy, URL-based and uncertain integrations are left alone. Each scoped
+disable is recorded as `codex.mcp.unavailable.disabled` without MCP environment
+values.
+
+## Layer 2 — the credential broker (`plugin/scripts/broker.py`)
+
+A caged window cannot read the `gh` token — that is the cage working. But
+opening a pull request is legitimate work, so the window asks a small process
+the owner runs outside every cage, and that process acts with the real
+credentials after validating the request:
+
+```bash
+CITY_BROKER=1 agents-city seat            # start the session with a broker
+python3 plugin/scripts/broker.py call pr --title "Add X" --body "why"
+python3 plugin/scripts/broker.py call push
+```
+
+- One token per window, minted at session start, **bound to one repo**: a
+  stolen token cannot choose a different target.
+- Only the SHA-256 of a token is stored; the token itself travels as a file
+  path whose read is the single exception the window's cage re-allows.
+- The broker refuses any action on the default branch, always. Pushes are
+  `git push origin HEAD` — no force, no refspec.
+- The broker is opt-in (`CITY_BROKER=1`) while it covers only `pr` and `push`;
+  stop it with `broker.py stop --data <city-dir>`.
+
+## Layer 3 — the audit chain, with an evidence vocabulary
+
+Every broker request — served or refused — appends one line to
+`~/.agents-city/.runtime/broker/<id>/audit.log`, and each line carries the
+SHA-256 of the previous one. The cage denies repo windows the whole directory,
+so an agent cannot rewrite its own history, and `broker.py verify` catches a
+single flipped byte. `bin/test-broker.py` proves both directions.
+
+A hash chain proves a line was not altered; it says nothing about what the line
+proves. So every line also carries an evidence state (`plugin/scripts/evidencia.py`):
+`enforced` (a control decided the outcome), `attribution-only`, `unattributed`,
+`unknown`, `ambiguous`, `unsupported`. Two rules hold wherever it is read —
+`unknown` never means allowed, and `ambiguous` is never resolved by picking a
+candidate. A missing binding is `unknown`, which authorises nothing; only
+`enforced` is proof a control fired.
+
+## Layer 4 — path containment, resolved twice
+
+The cage's write-allow set and the broker's repo binding both trust paths, and
+`plugin/scripts/rutas.py` answers the same question for both: it resolves a path
+through the deepest ancestor that exists — so a missing leaf under a symlinked
+parent still lands on the real target — and refuses a path both when it sits
+inside a sealed root and when it *covers* one. The cage's own guarantee is the
+ordering (the secret-deny block is emitted last and wins), so a covering
+writable root is safe; what containment adds is refusing a repo rooted on the
+credential store and dropping an owner `CITY_CAGE_ALLOW_WRITE` that lands inside
+a seal. `bin/test-rutas.py` drives the primitive directly.
+
+## Layer 5 — road admission as a gate graph
+
+An inbound road message is admitted by an ordered gate graph
+(`plugin/scripts/admision.py`), not a boolean: address → road → sender →
+payload, first blocker decisive. It returns a stable reason code
+(`road_missing`, `sender_not_paired`, …) and, per gate, a redacted diagnostic —
+counts and opaque ids, never a raw allowlist entry — so a refusal is
+explainable without leaking who is allowed. A road that matches but whose sender
+does not is an explicit block; an unknown sender under pairing yields
+`pairing-required` rather than a silent drop.
+
+## Layer 6 — road pairing
+
+An unknown city earns the right to write to a seat through a short code
+(`plugin/scripts/pairing.py`): eight characters from an unambiguous alphabet, a
+one-hour TTL, at most three pending per city, and an opaque approval id so
+tooling never echoes the human code. The code is revealed once per sender per
+window, so re-messaging cannot re-spam it. Approving grants exactly one thing —
+permission for that address to write to this seat — never road membership, never
+chair authority. The store is consulted only under the pairing policy; it can
+never widen an existing allowlist.
+
+## Layer 7 — untrusted road text
+
+Text arriving over a road is wrapped once, on arrival, in an unforgeable
+boundary (`plugin/channel/untrusted.ts`): the opening marker carries a fresh
+random id per wrap, so a message that pastes its own closing marker cannot guess
+the id and cannot smuggle the rest as trusted text. Chat-template role tokens
+(`<|im_start|>`, `[INST]`, `<start_of_turn>`, …) are defanged first, so text
+cannot forge a synthetic system or assistant turn on a self-hosted backend. It
+is defence in depth for the seat, not a promise the model obeys the boundary.
+
+## Host-bound secrets — the broker without handing over the key
+
+A caged window cannot read an API token, and the broker does not hand it one.
+The owner binds a secret to an exact host set (`broker.py secret-set OPENAI
+--value … --allow-host api.openai.com`; no wildcards, no ports), and a window
+asks the broker to make the call carrying the secret by *name*
+(`broker.py call fetch --secret OPENAI --host api.openai.com --path /v1/…`). The
+broker injects the value only when the target host matches a bound one, and
+never returns it. A leaked transcript or `ps` line holds the request, never the
+credential.
+
+## The Hall protocol — writing to the seat from a page
+
+When the local web Hall is built, it talks to the bus that serves it over one
+same-origin socket, on the contract in `plugin/scripts/hall_protocol.py`: three
+frames (`req`/`res`/`event`), a per-connection monotonic sequence, and the rule
+that events are never replayed — on a gap the client re-fetches a snapshot. The
+method set is closed (`os.system` is not a method); writing to the seat is one
+call with a queue mode (`start`/`steer`/`queue`/`note`) so an idle and a busy
+seat are the same call. Loopback is a pairing convenience, never a substitute
+for the seat's own admission.
+
+## Config migrations — `doctor`
+
+The runtime reads one config schema. Every change that can invalidate an
+existing config ships a migration in `plugin/scripts/doctor.py` that detects the
+old shape, explains it in one line, writes a timestamped backup, and rewrites to
+canonical form. Migrations are idempotent and ordered, so a file needing several
+converges in one pass and a canonical file is left untouched. `--fix` writes;
+the default is a dry-run report.
+
+## The ratchet
+
+`bin/test-security.py` is not a unit suite but a firewall of cross-cutting
+invariants: the secret set always contains `~/.ssh`/`~/.git-credentials`/gh, the
+seal block is always emitted after the write-allow block, `unknown` evidence
+never authorises, an admission decision never carries a raw allowlist entry, the
+Hall method set stays closed, and the launcher never wraps the seat window in
+the cage. Each past sharp edge becomes a line here, and the line stays.
+
+## Scope — the conscience stays inside the city
+
+Installing the plugin does not enrol every Claude session on the machine.
+Every hook sources `plugin/hooks/solo-en-ciudad.sh` first: outside a city
+runtime — no `CITY_BUS_ACTOR`, the identity only `city-session.sh` sets — the
+hook answers `{}` and leaves. No review passes, no digging notes, no notice
+judgements, no token counters in plain conversations. The MCP server already
+declared itself inactive without an actor identity; this extends the same rule
+to the hooks, which were the remaining machine-wide surface.
+
+The machine-wide conscience still exists as an explicit choice:
+`CITY_HOOKS=everywhere`, in the environment or in
+`~/.claude/channels/city-bus/.env`. Second-order effects are opted into, never
+discovered. `bin/test-contracts.py` holds both sides: every hook is mute
+outside a city, and both opt-in paths open the gate.
+
+## What this does NOT do, in writing
+
+- **Prompt injection still exists.** The cage bounds what it is worth.
+- **Keychain credentials travel over IPC, not file reads.** A jailed `git
+  push` still works when GitHub credentials live in the macOS keychain; the
+  broker and forge-side protected branches are the guard there. If you keep
+  `~/.git-credentials` in plain text, move it: `git config --global
+  credential.helper osxkeychain`.
+- **Outbound network stays open** — that is what keeps yolo useful. A window
+  can still exfiltrate what it can already see: its own repo.
+- **Everything runs as your OS user.** The cage narrows file reach; it is not
+  hostile-process isolation. Untrusted code still belongs in a separate user,
+  VM or container.
+- `~/.npmrc` stays readable by default because denying it breaks `npm install`
+  for owners with a registry config. If yours holds tokens, add it to
+  `CITY_CAGE_DENY`.
+
+## Where this lands against an exposed-gateway agent
+
+The criticisms that stuck to OpenClaw-class setups were: reachable from the
+network, broad host access, credentials in reach of the model. Here: nothing
+listens beyond `127.0.0.1`, writes are kernel-bounded per repo, and the
+credentials a hijacked window would want are either unreadable (cage) or never
+held (broker). The fourth problem — the model reads untrusted text — remains
+everyone's, and the three layers above exist to make it survivable.

package/docs/self-host.md

@@ -0,0 +1,151 @@
+# Self-hosting remote roads
+
+Local cities and local roads need no external server: each city automatically
+starts its loopback WebSocket hub. Self-host this transport only when two city
+seats on different machines must exchange messages.
+
+The Cloudflare Worker is a narrow relay:
+
+- a token authenticates one owner prefix;
+- each running seat registers as its stable `owner/city` address;
+- the relay carries the same `agents-city-bus/2` envelope as the local hub;
+- only `scope: road` envelopes from `seat` to `seat` are accepted;
+- the channel still filters senders and recipients through that city's
+  `roads.json`;
+- offline direct messages wait for at most 72 hours, up to 200 per city;
+- message bodies are not logged unless `LOG_CONTENT = "1"` is deliberately set.
+
+The relay does not distribute configuration, skills, files or authority. It
+cannot carry an internal committee envelope.
+
+## 1. Deploy the relay
+
+Set the Cloudflare account id in `bus/worker/wrangler.toml`, then:
+
+```bash
+cd bus
+npx --yes wrangler@4 login
+./scripts/deploy.sh
+```
+
+The deploy script creates the `TOKENS` KV namespace when necessary and deploys
+the Worker plus its SQLite-backed Durable Object. Keep the URL it prints.
+
+## 2. Mint one token per owner
+
+An owner can run several cities with the same token because every address shares
+that owner's prefix:
+
+```bash
+cd bus
+./scripts/mint-token.sh joseluiscases
+```
+
+Only the SHA-256 hash is stored in KV and the token is printed once. Store it
+privately. It permits addresses such as `joseluiscases/home` and
+`joseluiscases/product`, but cannot register as another owner.
+
+An optional `--to` restriction can narrow the relay-level destinations:
+
+```bash
+./scripts/mint-token.sh joseluiscases --to alice,bob/research
+```
+
+This is defence in depth. `roads.json` remains the city-level allowlist.
+
+## 3. Configure each machine, not each city
+
+The installed plugin accepts the remote roads URL and token. For a manual
+development setup, use:
+
+```text
+~/.claude/channels/city-bus/.env
+```
+
+with:
+
+```dotenv
+CITY_BUS_URL=https://city-bus.example.workers.dev
+CITY_BUS_TOKEN=rb_...
+```
+
+Do not put `CITY_BUS_AGENT` in new configuration. The seat derives its own
+`owner/city` address from the selected city at runtime, which is what lets
+several local cities use one plugin installation safely.
+
+The token can instead live in the macOS keychain under the service
+`city@agents-city`; that is where the plugin configuration stores sensitive
+values.
+
+## 4. Exchange city invitations
+
+Authentication makes a seat reachable; a road makes it allowed. Each side sends
+the other its public invitation and accepts it independently:
+
+```bash
+# machine A
+agents-city road invite product > product.invitation.json
+agents-city road connect product research.invitation.json
+
+# machine B
+agents-city road invite research > research.invitation.json
+agents-city road connect research product.invitation.json
+```
+
+Transfer invitation files by any ordinary channel. They contain no token:
+
+```json
+{
+  "version": 1,
+  "id": "city_…",
+  "name": "product",
+  "owner": "joseluiscases",
+  "address": "joseluiscases/product"
+}
+```
+
+Open both seats. `bus_roster` — or `/city:team`, kept as a compatibility command
+name — reports only explicit roads and whether their destination seats are
+online. Messages to an offline remote city are queued by the relay.
+
+Validate the relay and its durable typed queue locally before deploying:
+
+```bash
+cd bus/worker
+npm ci
+npm run typecheck
+npm run test:local
+```
+
+## Trust boundary
+
+A valid road grants permission to deliver text, not permission to act. The seat
+must treat incoming text as untrusted context, verify claims locally and ask for
+the same user confirmation that would be required without the road.
+
+Repo support windows authenticate only as members of their local committee bus.
+They receive no road tools or remote URL/token; attempts to invoke road commands
+are rejected by the hub ACL. Never copy an inbound request into an autonomous
+repo agent as an instruction; open a bounded evidence request and bring
+consequential actions back to the seat.
+
+These local credentials enforce routing, not hostile-process isolation: every
+runtime normally executes as the same OS user. Use separate OS/container users
+for untrusted code. Remote owner tokens remain genuine network credentials and
+must never be exposed to repo runtimes.
+
+## Optional map deployment
+
+The visual map is independent of road delivery. A city can run entirely without
+it, and a map outage must not stop the relay.
+
+To deploy a map, build `city/web`, create the D1 database from
+`city/worker/schema.sql`, seed one chosen city with `city/scripts/seed.py`, set a
+long `CITY_SECRET`, then deploy `city/worker`. Put an identity proxy such as
+Cloudflare Access in front of it and set `REQUIRE_ACCESS = "1"`; the map exposes
+the shape and activity of the selected codebase and should not be public by
+default.
+
+If the relay should report delivery metadata to that map, configure `CITY_URL`
+in `bus/worker/wrangler.toml` and the same `CITY_SECRET` in both Workers. The
+relay works normally when either value is absent.