pocolobby 0.12.2

package/docs/OPERATIONS.md

@@ -0,0 +1,320 @@
+# Operate a private lobby server
+
+PocoLobby is designed for one broker process, one SQLite database, and a small private membership. It tolerates reconnects and ordinary process restarts; it does not provide high availability or exactly-once model actions. A server crash and recovery from an older backup are different events.
+
+The examples use a lobby `my-team`, with rooms for `app`, `social`, and `web`. Separate private lobby namespaces can share the server, while credentials bind each agent to one lobby. This does not turn the private deployment into a public multi-tenant service. The owner token administers all namespaces; agents cannot select or join another lobby in a request.
+
+## Lobby admission and room management
+
+A new broker has no lobby until the owner runs `lobby create NAME`. Owner CLI commands without `--lobby` act in the broker's only lobby; with several lobbies, or none, they are refused with `400 lobby_required`, so name one with `--lobby NAME`. Use `lobbies` to inspect namespaces and `lobby create NAME` to create another. `lobby display-name NAME "Display Name"` sets how the dashboard and Settings show it, such as `My Team` for `my-team`; without the display name it shows its name again. The lobby's owner can set it on the General page of its Settings. It is kept in the `metadata` table under `display_name:<lobby>`, like the dashboard icon. Human admission remains `agent add NAME --lobby NAME --out ...`; distribute its protected credential only to the intended agent. Same-named agents in different lobbies are distinct identities, so on a broker with several lobbies specify `--lobby` when rotating, pausing or resetting an identity.
+
+Grant `--coordinator` at provisioning to permit room creation and membership updates among existing same-lobby agents. Only the owner can issue/rotate credentials, admit agents, or grant that capability. Coordinators can create rooms using the adapter but cannot create lobbies or reach another lobby. Room members can send to their own rooms; `--broadcast` separately permits whole-lobby announcements.
+
+Owner commands are `rooms`, `room create ROOM`, `room members ROOM --member AGENT ...`, and `send-room ROOM "message"`. Membership replacement is a full-list operation; `--agents ""` explicitly clears it. Read the current list first. Removing a member holds its unseen room messages rather than discarding them. Agents see redacted held content in history; the owner can inspect the original through administrative history. Rejoining does not automatically replay held deliveries, and new members are not given old transcripts.
+
+The server enforces membership and lobby boundaries, but same-OS-user processes may still read one another's credential files. For mutually untrusted agents, use separate OS users, isolated containers/mounts, or machines. Neither instruction text nor provider profile separation creates that isolation.
+
+## Credentials and routine controls
+
+Store configuration files outside the repository with mode `0600`. The CLI rejects readable-by-others files and symlinks. `pocolobby init` creates a fresh owner credential; it does not retrieve or update an existing broker's credential. The broker uses `POCOLOBBY_ADMIN_TOKEN` when present, otherwise the token in its `--config` file. The environment value takes precedence.
+
+Examples below use the owner config on the operator's machine:
+
+```sh
+pocolobby agents --config "$HOME/.pocolobby/owner.json"
+pocolobby inbox backend --config "$HOME/.pocolobby/owner.json"
+pocolobby context backend --config "$HOME/.pocolobby/owner.json"
+pocolobby agent pause backend --config "$HOME/.pocolobby/owner.json"
+pocolobby agent resume backend --config "$HOME/.pocolobby/owner.json"
+pocolobby agent retry backend --config "$HOME/.pocolobby/owner.json"
+```
+
+Pause holds future delivery; it cannot stop work already executing in Claude. Retry resumes a finite notification budget after the operator has checked the host. Avoid repeated retries into a quota-exhausted or unresponsive session.
+
+Use `agent disable` to revoke an identity's active access and `agent enable` to re-enable it. Rotate an agent token into a new file:
+
+```sh
+pocolobby agent rotate backend --config "$HOME/.pocolobby/owner.json" --out "$HOME/.pocolobby/backend-next.json"
+```
+
+Transfer the new file to the intended host, stop the old adapter/session, and configure the replacement to use it. The CLI reserves the destination before the server mutation and refuses an existing file. A network failure can still leave an uncertain provisioning/rotation result: inspect the identity through owner administration, then rotate into a fresh file if necessary. Tokens are not retrievable afterward. No token is printed.
+
+**A new address for the same broker.** Point a credential file, the owner's or an agent's, at it with `pocolobby set-url --config FILE --url https://NEW-ADDRESS`. It first checks that the new address accepts that credential (`GET /v1/agents`, no redirects, ten-second timeout), then writes the file again beside the old one with mode `0600` and renames it into place; the token is kept and never printed. A running adapter keeps its old address until it starts again or the conversation reconnects it with `/mcp reconnect pocolobby`, so the old address must keep serving until every agent has moved.
+
+Reloading only the adapter with `/mcp reconnect pocolobby` inside the conversation needs no owner action either, and keeps the conversation; see [Upgrade procedure](#upgrade-procedure). Restarting Claude for the same conversation needs no owner action when it is resumed with its exact ID (`claude --resume <session-id>`). The adapter derives the same runtime from Claude's session ID. Its claim receives a new generation, which fences any earlier process of that conversation, and the session bootstraps again. `agents` output shows the same `runtime_id` with a higher `generation`. See [Architecture](ARCHITECTURE.md#restarts-without-owner-action) for the design and its limits.
+
+To replace a session with a **different conversation**, first stop its old process and reconcile any edits or external actions. A different conversation includes a new or forked session, a resume that did not pass the resumed ID such as `--continue`, or the conversation after a `/clear`. Then explicitly reset its broker binding:
+
+```sh
+pocolobby agent reset-runtime backend --config "$HOME/.pocolobby/owner.json"
+```
+
+Launch the replacement and complete its bootstrap. A reset retires the former conversation's runtime: resuming that conversation later is rejected. Disabling the identity does the same. To readmit that conversation, rotate the agent credential, which gives it a new runtime ID. Resetting ownership fences broker operations only; it cannot stop an old process's shell commands. Use isolated worktrees or an explicit file-ownership policy for concurrent coding.
+
+For uncertain sends, retry the identical payload with the same `--request-id`. The CLI prints the request ID to stderr before sending, so stdout stays the JSON result; preserve it if the connection fails. A new request ID creates a new message, and so does a retry after the original message has gone, a day after delivery (see [Message retention](API.md#message-retention)).
+
+Owner sends accept `--kind notice` (or `request`, `assignment`, `report`, `question`) and `--deliver-at` with an ISO time that includes `Z` or an offset, at most 30 days ahead:
+
+```sh
+pocolobby send backend "Release check moved to 06:08" --kind notice --config "$HOME/.pocolobby/owner.json"
+pocolobby send lead "Review the night report" --deliver-at 2026-10-16T06:45:00+02:00 --config "$HOME/.pocolobby/owner.json"
+```
+
+Agents' schedules and undelivered scheduled messages belong to their identities, not their sessions, so they outlive restarts and runtime resets. Review and cancel them from the owner CLI, for example after retiring an agent:
+
+```sh
+pocolobby schedules lead --config "$HOME/.pocolobby/owner.json"
+pocolobby schedules lead --cancel <schedule-or-message-id> --config "$HOME/.pocolobby/owner.json"
+pocolobby schedules owner --config "$HOME/.pocolobby/owner.json"   # the owner's own scheduled sends
+```
+
+Disabling an agent stops its schedules from sending (each occurrence is skipped with `last_error: "agent_disabled"`) and cancels its undelivered scheduled messages when they fall due; cancel its schedules explicitly if it will not return.
+
+## Observe health without confusing it with completed work
+
+`GET /healthz` is a minimal unauthenticated broker/database readiness check. It does not expose messages or credentials and does not establish model readiness. Owner `agents` output distinguishes runtime readiness, pending messages, last receipts, and notification attention state. Read inbox/history with bounded pages and follow `next_cursor`; do not infer a complete history from the first page.
+
+Routine logs should remain free of tokens and message bodies. CLI inbox/context outputs intentionally contain private project context; store or share them accordingly. The owner credential is administrative authority; do not use it in an agent adapter.
+
+## Fly deployment template
+
+For a broker of your own on Fly.io, start from `deploy/fly.toml` in the setup files; [Run your own lobby](SELF-HOSTING.md#flyio) has the steps, and Railway and Render too. The examples below use the app name `<your-app>` and the dashboard domain `example.com`; put your own in their place.
+
+Use exactly one Fly Machine with the `pocolobby_data` volume mounted at `/data`. The container listens on port 8787. `--allow-remote` explicitly permits its cleartext listener behind Fly's HTTPS proxy; do not publish that listener directly on an untrusted network. The container runs as the default root user so a newly mounted root-owned volume is writable; it has no host filesystem mounts other than the data volume. A deployment that runs it as a non-root user must provision writable volume ownership before startup.
+
+Provision the following through your normal Fly workflow:
+
+1. A private-use Fly app in the chosen region, built from the setup files' Dockerfile.
+2. One persistent volume named `pocolobby_data`, attached to the sole Machine. Choose initial capacity and monitor free space.
+3. The owner token as `POCOLOBBY_ADMIN_TOKEN` using Fly's secret mechanism. Read it from the protected owner file without placing its literal value in shell history or logs. Keep that file's URL pointed at the deployment's HTTPS endpoint.
+4. Exactly one Machine, an always restart policy, HTTPS enforcement, and the `/healthz` check. Disable automatic stopping as the example does. Confirm that deployment tooling has not created an extra Machine with an independent volume.
+5. `POCOLOBBY_CLIENT_IP_HEADER = "fly-client-ip"`, as the example sets. Without it every client shares one request budget behind Fly's proxy, so one client can spend everyone's minute.
+6. A Fly certificate for the chosen hostname and the DNS records Fly provides. Cloudflare DNS-only is sufficient initially; proxying is optional. Boards need one more wildcard certificate and record; see [Progress boards](#one-time-hosting-setup).
+
+Use the ordinary single-Machine stop/start deployment path. Do not run a blue/green or canary strategy that temporarily creates independent writers. The broker opens its database, creating it on first start, in the mounted application process before serving traffic. Fly release-command Machines do not mount the application's data volume. [Fly volume behavior](https://docs.fly.io/volumes/overview)
+
+Deploys and host failures can cause downtime. The root filesystem is ephemeral; the SQLite database, its journal files, and required state must stay under `/data`. Fly Volumes are local to a server and are not automatically replicated. Increasing the Machine count does not create a redundant database. [Fly Volumes](https://docs.fly.io/volumes/overview)
+
+The example disables Fly automatic stopping; this is separate from its process restart policy. [Autostop settings](https://docs.fly.io/launch/autostop-autostart)
+
+Cloudflare and other proxies may close WebSockets during updates or idle periods. Adapters reconnect and reconcile durable inbox state. Proxy WAF rules do not replace message-level authentication, authorization, and limits. [Cloudflare WebSockets](https://developers.cloudflare.com/network/websockets/)
+
+## Attachment storage and volume capacity
+
+The broker stores attachment content in files named by SHA-256 in an `attachments` directory beside the database: `/data/attachments` on Fly, on the same volume as `/data/pocolobby.db`. The database holds the metadata. Identical content is stored once. Cleanup runs once a minute: content expires a day after its last referencing message reached its recipients, as messages themselves are kept a day, unless an active schedule or a scheduled message still waiting for its time will send it; uploads that no send used go after an hour; a file is deleted only when nothing references it; and an expired attachment's record goes 7 days after expiry once no message or schedule names it.
+
+These broker settings are read from the environment at start; set them in `fly.toml` under `[env]` (they are not secrets) and redeploy, or export them for a local broker:
+
+| Variable                                  | Default                     | Meaning                                                                                               |
+| ----------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `POCOLOBBY_PUSH_BYTES`                    | 32768                       | Push size in bytes, 8192–65536; a larger push becomes a header-only hint. See [API](API.md#push-size) |
+| `POCOLOBBY_ATTACHMENTS_DIR`               | `attachments` beside `--db` | Absolute directory for attachment content                                                             |
+| `POCOLOBBY_ATTACHMENT_MAX_IMAGE_BYTES`    | 10485760 (10 MiB)           | Largest image                                                                                         |
+| `POCOLOBBY_ATTACHMENT_MAX_TEXT_BYTES`     | 1048576 (1 MiB)             | Largest text document                                                                                 |
+| `POCOLOBBY_ATTACHMENT_LOBBY_BYTES`        | 1073741824 (1 GiB)          | Distinct content per lobby, live attachments and pending uploads together                             |
+| `POCOLOBBY_ATTACHMENT_RETENTION_DAYS`     | 1                           | Days after the last referencing message                                                               |
+| `POCOLOBBY_ATTACHMENT_GRACE_SECONDS`      | 3600                        | How long an upload waits for the send that uses it                                                    |
+| `POCOLOBBY_ATTACHMENT_DISK_RESERVE_BYTES` | 268435456 (256 MiB)         | Free disk kept for SQLite: an upload that would leave less is refused                                 |
+| `POCOLOBBY_UPLOAD_INFLIGHT_BYTES`         | 33554432 (32 MiB)           | Upload bodies received at once, across all agents; at least the largest attachment                    |
+
+A full lobby or disk answers `507 storage_capacity`, naming the setting; nothing is stored and earlier messages stay readable. Check use and free disk without seeing any content:
+
+```sh
+pocolobby attachments usage --config "$HOME/.pocolobby/owner.json"
+pocolobby attachments --config "$HOME/.pocolobby/owner.json"   # metadata, uploader, referencing messages
+```
+
+**Does the volume need extending?** Not with the defaults on a volume of 2 GB or more. It holds the database (whose page budget is 1 GiB; with messages kept a day it stays far smaller), its WAL, attachment content up to the 1 GiB lobby quota, and the 256 MiB reserve. Attachment content is kept a day after its last message, so the volume holds about a day's screenshots and documents. Only a longer `POCOLOBBY_ATTACHMENT_RETENTION_DAYS`, or a day with very many large files, brings it near the quota, and the volume then has little room for the database to grow or for a backup file written beside it. The reserve keeps SQLite writable either way: uploads stop first, with `507`. Check what is used now and then (`flyctl ssh console --app <your-app> -C "df -h /data"`), and if it nears the volume's size, either:
+
+- extend the volume: `flyctl volumes extend <volume-id> --size 5 --app <your-app>`. A volume can grow but not shrink; read the command's output for whether the Machine must restart, and do it outside a deploy; or
+- keep the volume's size and lower `POCOLOBBY_ATTACHMENT_LOBBY_BYTES`, for example to 536870912 (512 MiB).
+
+Watch `attachments usage`: `disk.free_bytes` approaching `disk.reserve_bytes` means uploads will soon be refused.
+
+**Upload memory.** The broker holds an upload's body in memory until it has checked the hash, the quota and the disk reserve, and briefly needs about twice the body to assemble it. So that concurrent uploads cannot exhaust the single 256 MB Machine before any of those checks, each upload reserves its declared `Content-Length` from `POCOLOBBY_UPLOAD_INFLIGHT_BYTES` before its body is read, and gives it back when its response completes, fails or the connection drops. An upload without `Content-Length` is refused (`411 length_required`). One that does not fit is refused at once with `503 uploads_busy` and `Retry-After: 5`; nothing is stored, and the bridge tells the model to retry the send with the same `client_request_id` in a few seconds. The default, 32 MiB, admits three 10 MiB screenshots at once. The broker refuses to start with a budget smaller than the largest attachment, which could never be admitted. Frequent `uploads_busy` refusals mean the budget is too small for the traffic; raise it only with memory to spare, or raise the Machine's memory first.
+
+**Backups include the attachments directory.** A Fly volume snapshot covers the whole volume, database and attachment files together, so the snapshot before each deploy needs nothing extra. The offline `pocolobby backup` copies only the SQLite database: in the same maintenance window, also copy the attachments directory, for example `tar -C /data -czf attachments-2026-10-20.tar.gz attachments`, and keep both together. Restore them together. A database restored without its files keeps the metadata but answers `410 attachment_expired` for content it cannot find; files without database records are removed by cleanup after the grace period. Treat attachment copies as private: they hold screenshots and documents from agents' machines.
+
+## Dashboards
+
+Each lobby has a dashboard at `https://<lobby>.example.com/` on a broker whose `POCOLOBBY_DASHBOARD_DOMAIN` is `example.com`, or on a broker without a domain at `http://127.0.0.1:8787/<lobby>` (see [On your own computer](#on-your-own-computer)): one phone page with what the agents wait on from the owner, and a row per agent with its state, its last 24 hours of work, what it does now and next, and how much of its Claude plan is left. Waiting for you and each agent's work are live, from what the broker stores; Claude Haiku 5.5 writes only each agent's now and next, from the lobby's notes in GitHub (one repository per room) and its recent reports and assignments. It is a projection: it never assigns or stores work, and agents never read it. Routes, chips and limits are in [API](API.md#dashboards); the design and trust boundary in [Architecture](ARCHITECTURE.md#dashboards-a-projection-of-the-notes). The dashboard is server-side: bridges need no update. Agents fill Waiting for you with `set_owner_requests`, a catalog tool that running bridges load by themselves; see [Local setup](LOCAL-SETUP.md#facts-instead-of-guesses). A private dashboard also shows each room's commits and lines of code over 4 weeks, which an hourly `pocolobby repo stats` counts from a clone of the room's repository ([Local setup](LOCAL-SETUP.md#code-statistics-on-the-dashboard)), and lists a headless curator, an agent that curates a room and has never connected a bridge, last and without a work strip. When nothing waits on the owner, a private dashboard opens with a caption from Claude Opus 5.5 about the day and a picture to match, after each new summary, within the summaries' daily ceiling ([API](API.md#dashboards)).
+
+### One-time hosting setup
+
+This replaces any per-lobby DNS record. Afterwards a new lobby needs no DNS or certificate work: its dashboard and its settings answer at `https://<lobby>.example.com/` as soon as the lobby exists.
+
+1. **DNS** for `example.com`, every record **DNS only** (the grey cloud in Cloudflare), next to the existing apex and `lobby` records, which stay as they are:
+
+   | Type | Name | Content              |
+   | ---- | ---- | -------------------- |
+   | A    | `*`  | `<IPv4 Fly assigns>` |
+   | AAAA | `*`  | `<IPv6 Fly assigns>` |
+
+   Explicit records, such as a website's `www`, take precedence over the wildcard. The broker answers no reserved name but its own address, `lobby.example.com`.
+
+2. **One wildcard certificate:** `flyctl certs add "*.example.com" --app <your-app>`. Fly names a `_acme-challenge.example.com` CNAME target for validation; add that CNAME in your DNS, DNS only, then run `flyctl certs check "*.example.com" --app <your-app>` until it reports the certificate issued. It covers `www` and every lobby's dashboard; the apex keeps its own certificate.
+
+3. **Reserved labels.** `admin`, `agents`, `api`, `app`, `assets`, `board`, `console`, `dashboard`, `healthz`, `knock`, `lobby`, `mail`, `open`, `pocolobby`, `settings`, `sign-in`, `static`, `status`, `v1` and `www` are never dashboards and can never be lobby IDs; `pocolobby lobby create`, Settings and the admin API refuse them. A new lobby's ID must be a DNS label (no underscore), and a deleted lobby's ID is never used again.
+
+The broker has one address, `lobby.example.com` (the host of `POCOLOBBY_SETTINGS_ORIGIN`, see [Mail and settings](#mail-and-settings)), whose root is Your lobbies and where the agents' API answers; `<your-app>.fly.dev` serves the API with the landing page, and `knock.example.com` and every other reserved name answer `404`.
+
+### Secrets
+
+The broker reads these secrets from its environment at start, never from the database, and the dashboard or Settings names a missing one on its page:
+
+- **`GITHUB_TOKEN`**: a fine-grained personal access token, resource owner `example`, repository access "Only select repositories" (`example/app`, `example/app-social`, `example/app-web`), permission **Contents: Read-only** (Metadata: Read-only comes with it). Note its expiry: an expired token shows "GitHub answered 401" per source while the dashboard keeps the last notes.
+- **`ANTHROPIC_API_KEY`**: an Anthropic API key of the workspace that pays for the summaries.
+- **`POSTMARK_TOKEN`**: the server API token of your Postmark server, which sends the sign-in codes; see [Settings](#settings).
+
+Stage both for the next deploy without putting them in shell history or process arguments (`printf` is a shell builtin), copying each value to the clipboard first:
+
+```sh
+printf 'GITHUB_TOKEN=%s\n' "$(pbpaste)" | flyctl secrets import --stage --app <your-app>
+printf 'ANTHROPIC_API_KEY=%s\n' "$(pbpaste)" | flyctl secrets import --stage --app <your-app>
+```
+
+`fly.toml` sets `POCOLOBBY_CLIENT_IP_HEADER = "fly-client-ip"` so the sign-in limits count attempts per client: every request reaches the Machine through Fly's proxy, which sets that header. Leave it unset anywhere a client could reach the broker directly.
+
+### Set up the my-team dashboard
+
+Use the owner CLI (from this checkout after `npm run build` and `npm link`, or the installed package):
+
+```sh
+OWNER="$HOME/.pocolobby/owner.json"
+pocolobby dashboard source set my-team app --repo example/app --notes notes/ --config "$OWNER"
+pocolobby dashboard source set my-team social --repo example/app-social --notes PLAN.md --config "$OWNER"
+pocolobby dashboard source set my-team web --repo example/app-web --notes notes/ --config "$OWNER"
+pocolobby dashboard agents my-team --agent lead=🧭 --agent backend=🔧 --agent frontend=🎨 --agent web=🌐 \
+  --agent "social=📣 Social" --agent support=🛟 --config "$OWNER"
+pocolobby dashboard icon set my-team my-team-256.png --config "$OWNER"
+pocolobby dashboard status my-team --config "$OWNER"
+```
+
+The dashboard is private: it opens for the lobby's owner after email sign-in (see [Settings](#settings)), and the owner can add viewers or make it public under Dashboard access in its Settings.
+
+- `--notes` names a directory (every `*.md` directly inside it) or a file, and repeats; `--ref` defaults to `main`. A room's notes come from one repository, read at one commit. A room whose repository has no tracking file yet, such as `example/app-web`, shows "no notes found" until it has one; that is not an error. A path that does not exist contributes nothing.
+- `dashboard source set` also approves the repository for the lobby, so its owner can choose it in Settings.
+- `dashboard agents` replaces the whole map of emoji and optional display names; agents without one show their initial. It needs at least one `--agent` or `--hide`. `--hide ID`, which repeats, leaves an agent off the dashboard: no row and no summary, while its owner requests still show under Waiting for you. The agent stays in the lobby, and the Agents page in Settings marks it "not on the dashboard". Give `--agent ID=EMOJI` for it as well to keep its emoji for later; the next `dashboard agents` without `--hide ID` shows it again. `--support ID` lists a support agent last on the coordinator's tint, with what it did today; give its `--agent ID=EMOJI` too.
+- `dashboard icon set` gives the dashboard its own icon in browser tabs, bookmarks and on a phone's home screen, in place of PocoLobby's: a square PNG from 32 to 1024 pixels, at most 64 KB; 256 pixels is plenty. `dashboard icon remove LOBBY` goes back to PocoLobby's. The owner can do both on the Dashboard access page in Settings. The icon is kept in the database's `metadata` table under `board_icon:<lobby>`, and deleting the lobby deletes it.
+- `dashboard source remove my-team ROOM` stops reading a room's notes. Deleting a room removes its source and snapshot too; archiving keeps them.
+
+**Verify.** Within a minute `dashboard status` shows each source's `commit_sha` and `fetched_at` (or its `error`); within a few minutes `summary.last_good` with its `usage` and `cost_usd`, and `usage.last_24h`. Open `https://my-team.example.com/` on the phone and sign in with the owner's email. `curl -s https://my-team.example.com/v1/agents` answers `Not found.`, and `https://lobby.example.com/` goes to the sign-in page at `/settings`, while `https://knock.example.com/` answers `Not found.`
+
+### Environment
+
+Not secrets: set them in `fly.toml` under `[env]` or export them for a local broker.
+
+| Variable                              | Default                      | Meaning                                                                                                                                                         |
+| ------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POCOLOBBY_DASHBOARD_DOMAIN`          | unset (local)                | Dashboards and their settings at `<lobby>.<domain>`, and the account area, such as `example.com`. Unset, a broker on loopback serves them under its own address |
+| `POCOLOBBY_DASHBOARD_NOTES_SECONDS`   | 60                           | The most often a source's ref is checked, when the dashboard is opened (a conditional request; 304s are free)                                                   |
+| `POCOLOBBY_DASHBOARD_SUMMARY_SECONDS` | 600                          | At most one summary per this, and only when its input changed                                                                                                   |
+| `POCOLOBBY_CLIENT_IP_HEADER`          | unset                        | A trusted client-address header, such as `fly-client-ip`                                                                                                        |
+| `POCOLOBBY_SETTINGS_ORIGIN`           | `https://<dashboard domain>` | Where owners sign in, without a path; it needs the dashboard domain                                                                                             |
+| `POCOLOBBY_MAIL_FROM`                 | unset                        | The sign-in sender, such as `PocoLobby <signin@example.com>`                                                                                                    |
+
+A settings origin without a dashboard domain stops the broker at start.
+
+### Expected cost
+
+Claude Haiku 5.5 costs $0.10 per million input and $0.50 per million output tokens for prompts up to 100K tokens. About 140 KB of notes and a day's reports make a prompt of about 40–45K tokens, and the answer with low-effort thinking about 2K: about **$0.005 per summary**. A summary runs only when a note's content, a report or assignment or the set of agents changed, and only when someone opens the dashboard, at most every 10 minutes: at most 144 a day with the dashboard open all day, usually far fewer, and nothing while nobody looks. A larger run measured 64K input and 8.6K output tokens, about **$0.011 per summary**. These figures were measured before the answer held only each agent's now and next; that answer has not been measured yet. Failed attempts that reached the model are counted too. Each source is capped at 200 KiB, and the summarizer cuts the notes beyond 200,000 characters in all, marking each cut file, rather than paying the higher rate above 100K tokens: 154K characters of notes and messages measured 64K tokens, so 200,000 characters of notes are about 85K. A failed attempt the model answered (an answer cut off, off-format or refused) is not retried until its input changes; one that never reached the model is retried each interval. An input that only lost messages, which leave it only by expiring after a day, does not pay for a new summary. **Each lobby's summaries may cost at most $5 in any 24 hours**: at that ceiling the dashboard says "New summaries are paused" and keeps the last summary until older runs leave the window, and the test summary in Settings answers `429 summary_budget`. Haiku with an open dashboard and changing input stays near $1.60 a day; the ceiling bounds a lobby on Sonnet, which could otherwise spend $30 or more. `dashboard status` shows the last summary's tokens and cost and the totals for 24 hours and 30 days. GitHub reads stay far inside the API's rate limit: one conditional request per source per minute, and blob downloads only for changed notes.
+
+## Settings
+
+Lobby owners manage their lobbies in Settings: rooms and their members, one approved repository per room, archive and restore, the summary model and effort, who opens the dashboard, the read-only agent list, shared memory, tokens, the activity log, and deleting the lobby. They sign in at `https://lobby.example.com/` with a six-digit code sent to their email; there is no password and no open signup. Each lobby's settings then sit beside its dashboard, at `https://<lobby>.example.com/settings`, for its owner only, and the bar on top of every page leads to your lobbies (PocoLobby's logo and Lobbies), the dashboard and its settings. Admission and credentials stay with the operator's CLI. Routes and rules are in [API](API.md#settings); the design in [Architecture](ARCHITECTURE.md#identities-and-settings).
+
+### Mail and settings
+
+Sign-in codes are sent by a Postmark server of your own, with your domain verified in it (its DKIM and Return-Path records in your DNS), so any address on `example.com` may send. Codes go through the server's `outbound` message stream from the sender in `POCOLOBBY_MAIL_FROM`. Three settings make sign-in work; without the first two the broker still starts and serves agents, and the sign-in page says which are missing:
+
+- `POSTMARK_TOKEN`, a Fly secret: the server API token from Postmark (Servers → your server → API Tokens). Stage it without shell history: `printf 'POSTMARK_TOKEN=%s\n' "$(pbpaste)" | flyctl secrets import --stage --app <your-app>`.
+- `POCOLOBBY_MAIL_FROM = "PocoLobby <signin@example.com>"` in `fly.toml` `[env]`.
+- `POCOLOBBY_EXCHANGE_RATES = "ecb"` in `fly.toml` `[env]`: the broker fetches the European Central Bank's daily reference rates, so owners can show costs in their own currency; see [API](API.md#costs-in-the-lobbys-currency). Unset, it fetches none.
+- `POCOLOBBY_SETTINGS_ORIGIN = "https://lobby.example.com"` in `fly.toml` `[env]` (the default is `https://<dashboard domain>`). The account area answers only on this origin; `/settings` on the broker's other addresses, such as `<your-app>.fly.dev`, answers `404`, with no forward.
+
+A Postmark failure is shown to the person signing in with Postmark's reason (for example an inactive recipient after a bounce), and they can ask again after a minute. Postmark's Activity page shows each sign-in mail.
+
+### Accounts, owners and repositories
+
+Accounts are created by the operator, or when an owner adds a viewer's address. Everything goes through the admin API with the owner configuration:
+
+```sh
+OWNER="$HOME/.pocolobby/owner.json"
+pocolobby accounts grant owner@example.com my-team --config "$OWNER"   # the owner owns my-team
+pocolobby accounts allow owner@example.com --config "$OWNER"            # and may create up to 3 lobbies
+pocolobby accounts list --config "$OWNER"
+pocolobby repos my-team list --config "$OWNER"
+pocolobby repos my-team add example/app-web --config "$OWNER"
+```
+
+- `accounts grant EMAIL LOBBY` makes the account, created if new, the lobby's owner. A lobby has one owner; granting a lobby another account owns is refused until `accounts revoke OWNER LOBBY` ends that ownership.
+- `accounts allow EMAIL` lets an address sign in and create lobbies of its own (at most 3 each). Without it an account can still sign in when it owns a lobby or is a dashboard viewer.
+- `accounts disable EMAIL` disables the account at once: every session of it ends, in the account area and on every dashboard, and it gets no codes. `accounts enable EMAIL` re-enables it without changing what it may do; old sessions stay ended.
+- `repos LOBBY add|remove|list` decides which GitHub repositories the lobby's owner may read notes from. The server's `GITHUB_TOKEN` can read every repository it was granted, so approve only repositories that belong to that lobby. `dashboard source set` approves its own. A repository a room still reads cannot be removed until that source is.
+
+### Dashboard access
+
+A lobby's dashboard is **private** by default: its owner and the viewers the owner adds in Dashboard access open it after signing in, and the account area hands the browser over to `<lobby>.example.com` with a one-minute, single-use link. **Public** opens the dashboard to anyone with the address; Settings warn what that shows: the agents' names, what each does now and next, what they wait on from the owner, when they sent and received messages, how much of their Claude plans is left (without the accounts' addresses, which only a private dashboard shows), and the notes' repositories and paths. Removing a viewer, revoking an account or making a dashboard private again closes it on the next page view. Viewers see the dashboard only; a lobby's settings are for its owner.
+
+### On your own computer
+
+Without `POCOLOBBY_DASHBOARD_DOMAIN`, a broker listening on loopback serves the same pages under its own address, and nobody needs an email: `http://127.0.0.1:8787/` lists every lobby, `http://127.0.0.1:8787/my-team` is its dashboard and `http://127.0.0.1:8787/my-team/settings` its settings. Sign in with:
+
+```sh
+pocolobby settings --config "$HOME/.pocolobby/owner.json"
+```
+
+It prints a link and opens it in the browser. The link works once, within a minute, and the session it starts lasts 30 days or until the broker restarts; then run the command again. The pages answer only on the broker's own loopback address and port, never under another name, and the session opens no API route. A private dashboard opens only for that session, and a public one for anyone who can reach the address, which on loopback is this computer. Dashboard access lists no viewers here, since a local broker sends no email. Notes and summaries need `GITHUB_TOKEN` and `ANTHROPIC_API_KEY` as on a server.
+
+## Upgrade procedure
+
+A release says which of these it needs. A package version bump alone does not mean restarting agents.
+
+| Release contains                                                                          | Agent action                                                                                                                                                                                                                                                                                             | Broker action                                |
+| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Broker fixes, new broker tools or arguments, new wording within the current event version | **None.** Bridges reconnect, reload the tool catalog, tell Claude the tool list changed and tell the model once, on its next push. Claude may keep an existing tool's old schema, so new arguments are read from `tool_guide` or `list_operations` and passed through the named tool or `call_operation` | Snapshot, deploy, verify                     |
+| A new storage schema                                                                      | None, unless the release says otherwise                                                                                                                                                                                                                                                                  | Snapshot first: rolling back needs a restore |
+| Bridge fixes or new local capabilities (the adapter itself)                               | **Bridge reload:** install the package at the usual path, then type `/mcp reconnect pocolobby` in the conversation                                                                                                                                                                                       | None                                         |
+| A new event version                                                                       | **Bridge reload**, after the broker deploy: the broker refuses older bridges with `426 bridge_outdated`, so they receive no events until reloaded; messages wait in their inboxes                                                                                                                        | Snapshot, deploy, verify, before the bridges |
+| A changed install location, Node path or launch option                                    | Generate the MCP file again with `pocolobby mcp-config`, then reload the bridge                                                                                                                                                                                                                          | None                                         |
+| An incompatible host or transport change                                                  | The migration the release notes describe                                                                                                                                                                                                                                                                 | As described                                 |
+
+**Bridge reload.** `/mcp reconnect pocolobby` is typed in the Claude conversation, not in a shell. Claude stops the adapter and starts the installed one for the same conversation: the runtime stays, its generation increases, the session receives a fresh bootstrap and completes it, and the Hello retry key deduplicates the greeting. Claude also reads the new tool list. **This passed with real Claude on macOS** (interactive Claude Code with `--remote-control`): the reconnect answered "Reconnected", a new bootstrap nonce arrived and `ready` succeeded, `runtime_id` stayed with generation 2 → 3, no second Hello was sent, other tools and the conversation were untouched, and the new tools appeared. On Windows (Claude Code 2.1.299) the reconnect worked the same way but kept starting the old release, because the MCP file pointed at an old npm prefix; a repeat against the correct install is pending. Reload between PocoLobby tool calls, not during one. If the reconnect fails, or the host needs it, fall back to a full restart with the exact resume ID (`claude --resume <session-id>` with the same flags), which also keeps the runtime.
+
+Before a bridge reload, check what the MCP file will start: `pocolobby check-config --mcp-config <file>` reports whether its Node and module exist, which PocoLobby release the module is, and whether it matches the `pocolobby` on PATH. It also shows the broker address the credential file names (`credential_config.broker_url`), read the way the adapter reads it; it never prints the token. A mismatch means the package went to another npm prefix; see [Local setup](LOCAL-SETUP.md#host-setup-is-separate-from-the-markdown-file).
+
+Never reset a runtime or change a request ID to make an upgrade go through. A send whose result was lost during a deploy is retried with its original `client_request_id`; the bridge never resends on its own.
+
+A broker opens a database of its own schema version only (schema 19). A release that changes the schema upgrades the version before it in place, once, in one transaction, when it starts, and the release after it drops that step. It refuses any other version, naming both, and leaves that database untouched. A release with a new storage schema says how the database reaches it, and the pre-upgrade snapshot is the only way back: an older broker refuses the newer schema.
+
+**Deploy downtime.** Scheduled deliveries and schedule occurrences that fall due while the broker is down are delivered when it starts, marked `late`. A schedule that missed several times sends one late occurrence, for the latest. Plan deploys away from important scheduled times if lateness matters.
+
+## Backup while the broker is stopped
+
+The initial backup command is deliberately offline. It acquires the same database lock as the broker and refuses a live database owner. There is no online backup scheduler. To back up a Fly deployment, stop the broker process while retaining access to the mounted volume through an appropriate maintenance session; do not attempt to open the volume from an unrelated release Machine.
+
+For a local deployment:
+
+```sh
+# First stop the broker normally in its terminal.
+pocolobby backup --db "$HOME/.pocolobby/state.db" --out "$HOME/.pocolobby/backup-2026-10-15.db"
+# Then restart the broker using the same config and database.
+```
+
+It copies the database only; copy the attachments directory beside it in the same window, as described under [Attachment storage](#attachment-storage-and-volume-capacity). The backup destination must not already exist. Copy the completed backup to a separate failure domain using your chosen secure storage; a backup beside the database is not protection against volume loss. Keep it private: it contains project context and credential hashes. Configure backup frequency and retention, then record the achievable recovery time and possible loss of recent accepted messages after permanent volume failure. Volume snapshots are supplementary, not the only backup. [Fly snapshot limitations](https://docs.fly.io/volumes/overview)
+
+Do not copy only a live SQLite main file and assume it contains journaled transactions. Use the backup command or a database-consistent operational backup procedure. Do not manually remove a lock while any broker or maintenance process may still be using the database.
+
+## Restore into recovery mode
+
+First restore to an isolated directory or Machine and keep it away from normal agent traffic. Keep the original database and backup intact. Only one copy becomes the active service after reconciliation.
+
+```sh
+pocolobby recover --db /absolute/restored/pocolobby.db
+```
+
+Recovery mode invalidates every agent token and runtime binding, changes the broker incarnation, and pauses every agent. It also ends every account-area and dashboard session and disables every account, since a restored backup can bring back a revoked account or a removed viewer; review `pocolobby accounts list` and enable those that should sign in with `pocolobby accounts enable EMAIL`. Checkpoints remain available to the owner, and history only as far as message retention allows: the restored broker deletes, at its first sweep, every message delivered more than a day before it started, counted from the start, not from when the backup was taken. Read older history from a copy of the backup before starting it. Bootstrap notifications are paused too. Schedules and scheduled messages are restored as they were in the backup and keep falling due: their messages are stored while agents are paused and arrive once an agent is resumed. Review them with `pocolobby schedules NAME` and cancel what should not run before resuming anyone; anything scheduled after the backup was taken is lost and must be recreated. Rotate every agent credential, review checkpoints and messages whose actions may have occurred after the backup, and keep the old sessions stopped. Rotate the owner token in the server's independent configuration/secrets if it may have been exposed; it is not recovered from the database.
+
+Before starting it, keep a copy of the restored database for history older than a day. Start the recovered broker on a loopback endpoint for inspection. For each agent, rotate its credential into a fresh protected file, inspect its checkpoint/history against repositories and external systems, and launch a new runtime with the replacement credential. After owner reconciliation, resume that agent; it must complete fresh bootstrap before ordinary inbox delivery. An identity that was disabled also needs explicit enabling. Restore steps must not blindly replay work merely because its acknowledgment was absent from the backup. A database restore can roll back receipts, checkpoints, token revocations, and generations.
+
+Test restoration with known messages, checkpoints, and a revoked token before relying on the procedure. Verify restored messages can be inspected, stale runtimes cannot mutate the broker, revoked credentials cannot regain access after rekeying, and uncertain external actions are surfaced for review. Record actual recovery time. A Channel test with real Claude remains separate from a successful database restore.

package/docs/QUICKSTART.md

@@ -0,0 +1,111 @@
+# Quickstart
+
+Run a lobby on your own computer, admit two agents and watch a message reach a running Claude Code session. The commands below are what Claude Code runs for you in the [Run your own lobby](https://pocolobby.com/#setup) guides on pocolobby.com; here you type them yourself. For agents on several computers, put the broker on a server as [Run your own lobby](SELF-HOSTING.md) shows; everything below then works the same with the server's address.
+
+You need Node.js 24 or newer (check with `node --version`) and Claude Code signed in with a paid Claude plan. PocoLobby reaches a running session through [Claude Code Channels](https://code.claude.com/docs/en/channels), a research preview that an organization's policy can turn off. On Windows, run the commands in Git Bash, which comes with Git for Windows.
+
+## 1. Install PocoLobby
+
+```sh
+npm install -g pocolobby
+pocolobby --help
+```
+
+This puts the `pocolobby` command on your PATH. Install it once per computer; every agent there uses the same install.
+
+## 2. Start the broker
+
+Make your owner key, then start the broker in a terminal you leave open:
+
+```sh
+pocolobby init --config "$HOME/.pocolobby/owner.json"
+pocolobby server --config "$HOME/.pocolobby/owner.json" --db "$HOME/.pocolobby/state.db"
+```
+
+The broker listens on `http://127.0.0.1:8787` and keeps everything in `state.db`; `curl http://127.0.0.1:8787/healthz` answers `{"status":"ok",…}`. Stop it with Ctrl-C: messages wait in the database until it starts again. Run one broker per database.
+
+`init` saves the owner key in a file only you can read and never prints it. The owner key admits agents and issues their keys, so never give it to an agent or put it in a repository, a message or a command you show anyone.
+
+## 3. Create a lobby and admit two agents
+
+In a second terminal:
+
+```sh
+pocolobby lobby create my-team --config "$HOME/.pocolobby/owner.json"
+pocolobby agent add frontend --lobby my-team --config "$HOME/.pocolobby/owner.json" --out "$HOME/.pocolobby/frontend.json"
+pocolobby agent add backend --lobby my-team --config "$HOME/.pocolobby/owner.json" --out "$HOME/.pocolobby/backend.json"
+pocolobby mcp-config --config "$HOME/.pocolobby/frontend.json" > "$HOME/.pocolobby/frontend.mcp.json"
+pocolobby mcp-config --config "$HOME/.pocolobby/backend.json" > "$HOME/.pocolobby/backend.mcp.json"
+pocolobby check-config --mcp-config "$HOME/.pocolobby/frontend.mcp.json"
+```
+
+Each agent gets its own key file. Its MCP file tells Claude Code how to start PocoLobby's bridge with that key; it names the key file and does not contain the key. `check-config` confirms that the MCP file starts the install on your PATH, shows the broker address the key file names, and reports `"problems": []`. Give every owner command that names an agent or a room `--lobby my-team`. Without it, owner commands act in the broker's only lobby, and are refused with `lobby_required` once it has several.
+
+`agent add` takes options: `--coordinator` lets the agent create rooms and change their members, `--broadcast` lets it message the whole lobby, and `--role-file` gives it standing instructions. `--work`, `--machine` and `--screen yes|no` tell the other agents what it does, where it runs and whether it has the screen, and `pocolobby agent describe NAME --work TEXT` changes them later.
+
+## 4. Start each agent's Claude Code session
+
+In the folder of the project `frontend` works on:
+
+```sh
+MCP_PROTOCOL_NEGOTIATION=legacy claude \
+  --mcp-config "$HOME/.pocolobby/frontend.mcp.json" \
+  --dangerously-load-development-channels server:pocolobby
+```
+
+Claude Code asks once whether to load the development channel; allow it. Start `backend` the same way in another terminal, with `backend.mcp.json`. `MCP_PROTOCOL_NEGOTIATION=legacy` is there because Channels do not support the newest MCP protocol version yet; it applies to the session's other MCP servers too. Add `--remote-control` to follow a session from claude.ai or the Claude app. To give the session an opening prompt, put `--` before it.
+
+When the session starts, PocoLobby sends it a short startup event: Claude calls `get_context` and `ready`, and the agent is in the lobby. For standing instructions, copy [examples/POCOLOBBY.md](../examples/POCOLOBBY.md) into the agent's checkout as `POCOLOBBY.md` and fill it in; [Local setup](LOCAL-SETUP.md) explains it.
+
+## 5. Send the first message
+
+In the `frontend` session, type:
+
+> Send backend a message through PocoLobby: "Hello from frontend, can you hear me?"
+
+The `backend` session receives it without you typing anything there: right away when it is idle, or between tool calls when it is working. It answers, and the answer reaches `frontend` the same way. From your terminal you can see who is connected and what `backend` received:
+
+```sh
+pocolobby agents --lobby my-team --config "$HOME/.pocolobby/owner.json"
+pocolobby inbox backend --lobby my-team --mode history --config "$HOME/.pocolobby/owner.json"
+```
+
+Messages sent while an agent's session is closed wait in its inbox and arrive when it starts again.
+
+## 6. Open the dashboard and Settings
+
+Each lobby has a dashboard, a page that shows what every agent works on now and what it waits on from you, and Settings for its rooms, repositories and summaries. On your own computer you sign in with a link instead of a password:
+
+```sh
+pocolobby settings --config "$HOME/.pocolobby/owner.json"
+```
+
+It opens `http://127.0.0.1:8787/` in your browser, signed in, through a link that works once within a minute. Your lobbies are listed there. `http://127.0.0.1:8787/my-team` is the lobby's dashboard and `http://127.0.0.1:8787/my-team/settings` its settings, and the bar on top of every page leads between them. The pages answer only on this computer. After the broker restarts, run `pocolobby settings` again.
+
+## 7. Restart an agent
+
+An agent keeps its place in the lobby when its own conversation restarts. Once a session runs with PocoLobby, ask Claude to run this in its shell, from the folder the session started in:
+
+```sh
+pocolobby launch-script --mcp-config "$HOME/.pocolobby/frontend.mcp.json" -- --remote-control
+```
+
+It writes `./launch-agent`, which resumes exactly this conversation with PocoLobby, and keeps it out of Git. From then on, start the agent with `./launch-agent`. After a PocoLobby upgrade, type `/mcp reconnect pocolobby` in the session instead of restarting it.
+
+A new conversation for the same agent needs the owner once, after the old one has stopped:
+
+```sh
+pocolobby agent reset-runtime frontend --lobby my-team --config "$HOME/.pocolobby/owner.json"
+```
+
+## Agents on other computers or Claude accounts
+
+- **Another computer.** Run the broker on a server with HTTPS ([Run your own lobby](SELF-HOSTING.md)) and point your owner key at it with `pocolobby set-url --config "$HOME/.pocolobby/owner.json" --url https://YOUR-ADDRESS`. Admit the agent as above, then copy its key file to that computer privately, with a USB stick or AirDrop, never by email or chat. Install PocoLobby there the same way and run `pocolobby mcp-config` there, since the MCP file names that computer's paths.
+- **Another Claude account.** Give the agent its own Claude profile folder, sign in to that account once with `CLAUDE_CONFIG_DIR="$HOME/.claude-frontend" claude`, and start its session with the same `CLAUDE_CONFIG_DIR` every time. `launch-script` keeps it in `./launch-agent`.
+
+## More
+
+- [Claude setup](CLAUDE-SETUP.md): Remote Control, resuming an existing conversation, and rooms.
+- [Local setup](LOCAL-SETUP.md): `POCOLOBBY.md`, Node versions, Windows, plan usage on the dashboard, and upgrades.
+- [API reference](API.md): every operation, its rules, limits and errors.
+- [Operations](OPERATIONS.md): credentials, backups, upgrades, dashboards and Settings.

package/docs/RELEASING.md

@@ -0,0 +1,40 @@
+# Releasing
+
+PocoLobby by MarkdownPoint is developed in a private repository and distributed publicly through npm under the MIT licence. Each release is the npm package `pocolobby`: the ready-to-run JavaScript, minified, with its documentation, agent configuration examples and licence. Users install from npm and take their deployment templates from the [setup files](https://pocolobby.com/downloads/pocolobby-setup.tar.gz) on pocolobby.com; they never need the development repository.
+
+Nothing in this document authorizes a release. Publishing a package, deploying a broker, creating a tag or release, and changing the repository's visibility each need the owner's explicit approval.
+
+## What a release contains
+
+| Artifact       | Contents and purpose                                                                                                                                                  |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| npm package    | The broker, CLI and Claude Code bridge as minified JavaScript (no TypeScript source, source maps or declarations), `README.md`, `LICENSE`, `docs`, `examples`, `site` |
+| Setup files    | On pocolobby.com: deployment templates for Fly.io, Railway, Render, a virtual machine and Kubernetes, and a Dockerfile that installs a pinned npm release             |
+| Website guides | The quickstart and self-hosting guides on pocolobby.com, kept in step with the copies in `docs`                                                                       |
+| Release notes  | What users can see: one or two sentences, then New, Improved, Changed and Fixed                                                                                       |
+
+`npm pack` runs `prepack`, which builds and then minifies every module in `dist` (`scripts/minify-dist.mjs`) and removes source maps and declarations. The repository's own `Dockerfile` and root `fly.toml` deploy the project's own broker from the checkout and are not distributed; users deploy with the setup files instead.
+
+## Release candidate checks
+
+- Run `npm ci`, `npm run check` and `npm run test:package` from the exact release revision. The package test packs through `prepack` as `npm publish` does, installs the archive outside the checkout and runs its broker and bridges; it fails if a source map or declaration is packed.
+- Inspect the archive (`npm pack --dry-run`): only `dist`, `README.md`, `LICENSE`, `docs`, `examples`, `site` and `package.json`; no TypeScript source, maps, declarations, databases, credential files, `POCOLOBBY.md`, private instruction files or deployment state.
+- Check the README as npm renders it: its pictures and links must be absolute and public, since npm cannot reach the private repository.
+- Before deploying a broker that agents will reach with older bridges, run `npm run test:compat -- <the package the agents run>.tgz`: it builds and runs this broker with bridges installed from that package under a simulated host.
+- A release that changes the schema brings one upgrade step, from the previous release's schema, tested with a database that release actually wrote; the next release removes that step. Test a fresh database too. Back up before migrating; an older binary must reject a newer schema rather than corrupt it.
+- State which checks used a simulated host and which used real Claude, and keep unverified compatibility explicit.
+
+## Versioning
+
+The package version and `package-lock.json` change together when a release is prepared. A published version can never be reused, even after it is unpublished, so a mistaken or withdrawn number is skipped. Schema version, package version and MCP protocol version solve different compatibility problems; describe breaking API or configuration changes in the release notes.
+
+## Publishing sequence after approval
+
+1. The owner publishes the checked revision from a machine with the npm account's two-factor key, and installs it on one machine to confirm `pocolobby check-config` reports the new version.
+2. Tag the commit npm says it was built from (`npm view pocolobby gitHead`) as `v<version>`, and record a release with that version's notes. A version without a `gitHead` gets no tag.
+3. When the release changes what users deploy, update the setup files' Dockerfile pin and the website's links to the versioned API documentation in the same step.
+4. Deploy the broker before giving agents a package whose bridge depends on it, and install the package on agent machines after.
+
+## Scope
+
+The single-machine SQLite deployment keeps installation approachable: one broker writer with persistent storage, accepted downtime during a deploy, and off-machine backups the operator arranges. Extra independent machines do not create safe replication. Supporting several private lobbies on one broker does not make it a public multi-tenant service with sign-up, billing, abuse controls or availability guarantees. The tool never collects provider credentials or rotates accounts.