botmancers 0.1.0 → 0.4.2

package/CHANGELOG.md

@@ -3,7 +3,156 @@
 All notable changes to the `botmancers` npm package. It uses
 [Semantic Versioning](https://semver.org): while the package is `0.x`, a
 minor version may change the CLI or configuration. The MCP tool contract is
-versioned separately, as `botmancers.mcp.v1`.
+versioned separately: `botmancers.mcp.v1` (frozen) and `botmancers.mcp.v2`.
+
+## [Unreleased]
+
+## [0.4.2] - 2026-10-17
+
+### Changed
+
+- Releases are published once, straight to `latest`, by the maintainer
+  (`npm run release:publish`). The `canary` dist-tag, the CI publish, npm
+  trusted publishing, and the bootstrap token are gone;
+  `release-botmancers.yml` now only runs the release check on the tag. The
+  package contents are unchanged from 0.4.1.
+- 0.4.1 was tagged but never published, so 0.4.2 carries its contents
+  (below) and the 0.4.0 contents.
+
+## [0.4.1] - 2026-10-17
+
+Not published; see 0.4.2.
+
+### Fixed
+
+- 0.4.0 was never published: its release check failed on the Linux release
+  runner. `npm test` passed a directory to `node --test`, which Node 24 treats
+  as a module path; it now passes a glob. The clean-install smoke signalled
+  `npx`, which on npm 11.19 does not forward `SIGTERM` to the bridge; it now
+  signals the process group and checks that the bridge port closes.
+- `release:check` shows the failing test and smoke output, drains stdout
+  before exiting, and writes its `--out` transcript as it goes.
+
+### Changed
+
+- A `ci-botmancers` workflow runs the same release check on pull requests that
+  touch the app or the package, so release failures show up before a tag.
+- 0.4.1 carries everything 0.4.0 would have shipped (below).
+
+## [0.4.0] - 2026-10-17
+
+Not published; see 0.4.1.
+
+### Added
+
+- The Botmancers app bundled in the package adds the durable Agent session
+  catalog and Sessions UI, session-targeted Ask and Continue exchanges with
+  inline exchange cards, and an Agent Exchanges ledger.
+- Service grants let the owner give another Agent narrow, audited access to
+  sessions, conversations, and exchanges (`docs/service-grants.md`). Grants
+  are re-checked at read time, and an unregistered Agent invalidates the
+  document.
+
+- `botmancers setup --client codex|cursor|claude [--remove]`: connects the
+  client to the local MCP bridge and installs the optional
+  `botmancers-collaboration` Agent Skill (shipped in `skills/`). An
+  ownership record in `config/clients/<client>.json` (versions and SHA-256
+  hashes, no token) lets re-runs, upgrades, and rollbacks refresh only
+  unmodified Botmancers files. Edited or foreign files are never overwritten
+  (exit 12), a missing client writes nothing (exit 11), and a failed write is
+  rolled back. Plain `botmancers setup` refreshes the clients already set up.
+  `botmancers doctor` reports each client as connected, missing, stale, or
+  conflicted, with the repair command.
+
+- MCP contract `botmancers.mcp.v2`: `botmancers_capabilities`,
+  `botmancers_list_agents`, `botmancers_list_sessions`,
+  `botmancers_list_conversations`, `botmancers_send_to_session`,
+  `botmancers_create_exchange`, `botmancers_get_exchange`, and
+  `botmancers_list_exchanges`, plus a v2 (`agent_id`) path of
+  `botmancers_get_conversation`, over the owner's service grants. The bundled
+  schema is `schemas/botmancers.mcp.v2.tools.json`; every v2 call is forwarded
+  unchanged. `GET /healthz` adds `contracts`. Library exports add
+  `MCP_CONTRACT_V1`, `MCP_CONTRACTS`, `TOOL_SCHEMA_V1_URL`, and
+  `toolContractOf`.
+
+### Changed
+
+- `MCP_CONTRACT` and `/healthz` `contract` are now `botmancers.mcp.v2`;
+  `tools/list` returns the v1 tools unchanged, then the v2 tools.
+- Startup preflight refuses (exit 4) a Botmancers that lacks any bundled v1 or
+  v2 tool, or the v2 path of `botmancers_get_conversation`, and names what is
+  missing. It still sends only `initialize` and `tools/list`.
+
+## [0.3.0] - 2026-10-16
+
+### Added
+
+- Managed install, following the Agent Deck / Agent Dealer contract:
+  `curl -fsSL https://raw.githubusercontent.com/not-so-fat/botmancers/main/scripts/install.sh | bash`
+  or `botmancers install [--to VERSION] [--migrate-cli] [--purge-global]`
+  installs the exact npm release into `~/.botmancers/versions/<version>`,
+  checks its sha512 integrity and contents, atomically points
+  `~/.botmancers/current` at it, and writes the stable launcher
+  `~/.local/bin/botmancers`. Existing data, configuration, logs, and workdirs
+  are not touched.
+- Safe automatic updates for managed installs, on by default: at most one
+  background npm `latest` check per 24 hours, a verified download next to the
+  running release, and activation only at the next `botmancers start` once no
+  Botmancers process from the home is live. `status`, `open`, `doctor`, the
+  bridge, and a running product never switch releases.
+  `BOTMANCERS_DISABLE_AUTOUPDATER=1` turns all of it off. Explicit installs,
+  upgrades, and rollbacks wait for a background download (`update.lock`), and
+  a start's stopped check, any release switch, and the supervisor's claim on
+  the home are serialized (`run/start.lock`). A release is made current only
+  when every module its CLI loads and this platform's better-sqlite3 binary
+  are present.
+- `botmancers upgrade [--check] [--to VERSION] [--yes]`: managed installs
+  download, verify, and activate (or stage while the product runs).
+  npm-global installs keep the prompted `npm install -g botmancers@<version>`.
+  npx, project-local, and source-checkout copies report how to upgrade and
+  never change themselves.
+- Rollback with `botmancers install --to <older>`. The newer version is then
+  not reinstated automatically. Activation keeps the active release and the
+  two newest other complete releases, and removes incomplete trees.
+- `status` and `doctor` report the install kind, launcher, `PATH` shadowing,
+  the CLI, current, and pending versions, the versions the live core and
+  bridge report, and the restart action.
+
+### Fixed
+
+- After a release switch beneath a running product, the newer CLI reports the
+  old core and bridge versions as degraded instead of treating the old bridge
+  as not running (NOT-279 class). It can still stop that product. The run
+  record now stores the CLI path the product was started from.
+
+## [0.2.0] - 2026-10-16
+
+### Added
+
+- The full Botmancers product in the package: the production Next.js UI, API
+  routes, and core engine (standalone server under `app/`, with every
+  platform's SQLite prebuild) next to the MCP bridge.
+- `botmancers setup`: creates `BOTMANCERS_HOME` (default `~/.botmancers`)
+  owner-only and generates the bridge-to-core service token (the engine
+  stores only its digest) and the inbound MCP token; prints the Hermes and
+  Agent Deck steps without writing their credentials.
+- `botmancers start [--daemon] [--open]`, `stop`, `status`, `doctor`, and
+  `open`: one supervisor runs the UI/core on `127.0.0.1:43123` and the bridge
+  on `127.0.0.1:43124`, with one health model (healthy / degraded /
+  stopped), idempotent start, stale run-metadata repair, and deterministic
+  exit codes.
+- `botmancers mcp`, the explicit bridge-only command.
+- Core `GET /api/health` reporting the running release version.
+
+### Changed
+
+- Installed-product state (database, files, skills, logs, configuration, run
+  metadata) lives under `BOTMANCERS_HOME` regardless of the launch directory.
+  Explicit `BOTMANCERS_DB_PATH`, `BOTMANCERS_FILES_ROOT`,
+  `BOTMANCERS_SKILLS_ROOT` (new), and `HERMES_WAIT_LOG_PATH` still win; a
+  source checkout without `BOTMANCERS_HOME` keeps its cwd-relative files.
+- Bare `botmancers` is unchanged (bridge only, same flags, environment, and
+  exit codes); `--help` now also points to the product commands.
 
 ## [0.1.0] - 2026-10-15
 

package/README.md

@@ -1,26 +1,272 @@
 # botmancers
 
-The Botmancers MCP bridge. It is a standalone [MCP](https://modelcontextprotocol.io)
-server, using Streamable HTTP, that lets an external agent hand a task to a
-Botmancers coordinator Agent and poll the result. Examples of such agents are
-Cursor's Grok Bot or any other MCP client.
-
-The bridge runs on your machine next to the Botmancers app. MCP clients
-authenticate to the bridge with their own token. The bridge forwards their
-tool calls to Botmancers with a service token, and clients never see that
-token. The tool contract is `botmancers.mcp.v1`, and its JSON schema ships in
-this package at `schemas/botmancers.mcp.v1.tools.json`.
+Botmancers in one npm package: the web UI, the API and durable core engine,
+and the authenticated [MCP](https://modelcontextprotocol.io) bridge that lets
+an external agent hand a task to a Botmancers coordinator Agent and poll the
+result. Examples of such agents are Cursor's Grok Bot or any other MCP client.
+No source checkout or separately started app is needed.
+
+- `botmancers setup` / `botmancers start` run the **full product**: the UI and
+  core engine on `http://127.0.0.1:43123` and the MCP bridge on
+  `http://127.0.0.1:43124/mcp`, under one supervisor.
+- Bare `botmancers` (or `botmancers mcp`) runs **only the bridge** in front of
+  a Botmancers app you run yourself, exactly as in 0.1.0, so existing MCP
+  configurations keep working.
+
+The tool contract is `botmancers.mcp.v2`, which serves every
+`botmancers.mcp.v1` tool unchanged and adds granted access to Agents,
+sessions, conversations, and exchanges. Its JSON schema ships in this
+package at `schemas/botmancers.mcp.v2.tools.json`, next to the frozen
+`schemas/botmancers.mcp.v1.tools.json`; both are byte-identical to the
+captures in the Botmancers repository
+([`docs/contracts`](../../docs/contracts/mcp-bridge-v2.tools.json)).
+
+v1 tools (no grants needed):
 
 | Tool | What it does |
 | --- | --- |
 | `botmancers_start_task` | Sends one objective to an allowlisted coordinator. Returns `request_id` and `conversation_id`. |
 | `botmancers_get_request` | Polls a request until `terminal`. Returns its `result` or `failure`. |
-| `botmancers_get_conversation` | Reads the conversation the task opened. |
+| `botmancers_get_conversation` | Reads the conversation the task opened. With `agent_id` (v2 path), reads any granted conversation of that Agent, paginated. |
 | `botmancers_health` | Shows the caller's identity and the available coordinators. |
 
-Requirements: Node.js 20 or newer and a running Botmancers app.
+v2 tools (each needs the owner's grant on the Agents involved,
+[`docs/service-grants.md`](../../docs/service-grants.md)), in workflow order:
+
+| Tool | What it does |
+| --- | --- |
+| `botmancers_capabilities` | Discover: supported contracts, the granted Agents, and the operations this caller may use. |
+| `botmancers_list_agents` | Discover: the granted Agents by name, paginated. |
+| `botmancers_list_sessions` | Select: an Agent's sessions by stable Botmancers reference and recognizable title. |
+| `botmancers_list_conversations` | History: an Agent's conversations, paginated. |
+| `botmancers_send_to_session` | Act: one message to the exact same session of the same Agent (idempotency key required). |
+| `botmancers_create_exchange` | Act: an `Ask` to a session, or a `Continue` to another Agent (idempotency key required). |
+| `botmancers_get_exchange` | Observe: poll until `terminal`; the answer or handoff packet. |
+| `botmancers_list_exchanges` | Observe: this caller's exchanges, paginated. |
+
+Returned conversation, answer, and packet text is untrusted data. The full
+contract, polling and backoff, error recovery, and a same-session plus
+cross-Agent example are in
+[`docs/mcp-bridge.md`](../../docs/mcp-bridge.md).
+
+Requirements: Node.js 20 or newer for the bridge; the full product needs
+Node.js 20.9 or newer, and Node.js 22 or newer is recommended (the bundled
+SQLite driver declares Node 22; `botmancers doctor` checks that it loads).
+The full product is supported on macOS and Linux (x64 and arm64); the
+bundled SQLite driver also ships Windows binaries, but the supervisor is
+untested there.
+
+## Quick start: the full product
+
+The recommended install is the **managed install**. It needs Node.js and
+npm, and no global npm package or source checkout:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/not-so-fat/botmancers/main/scripts/install.sh | bash
+botmancers setup
+botmancers start --daemon --open
+```
+
+The script runs `npx botmancers@latest install`. That command installs the
+release into `~/.botmancers/versions/<version>`, points `~/.botmancers/current`
+at it, and writes the launcher `~/.local/bin/botmancers`. Add `~/.local/bin`
+to your `PATH` if the script asks you to. Managed installs
+[update themselves safely](#upgrade). To install a specific version, run
+`BOTMANCERS_VERSION=0.4.2 bash install.sh` or
+`npx botmancers@0.4.2 install --to 0.4.2`.
+
+npm-global installs and bare `npx` still work for compatibility:
 
-## Quick start
+```sh
+npx botmancers setup
+npx botmancers start --daemon --open
+```
+
+`setup` creates `~/.botmancers` (owner-only) and generates two local
+credentials: the service token the bridge uses to call the core engine (the
+engine stores only its SHA-256 digest) and the MCP token your MCP clients
+send to the bridge. It never writes Hermes, Agent Deck, or coding-agent
+credentials; it prints where to add them. `start --daemon` launches the UI,
+API, core engine, and bridge in the background and returns once both are
+healthy; `--open` opens the UI in your browser.
+
+Then:
+
+1. **Open the UI** at `http://127.0.0.1:43123` (or run `botmancers open`).
+2. **Configure Hermes** for conversational turns: add
+   `HERMES_API_SERVER_KEY=<your gateway key>` (and `HERMES_BASE_URL` if the
+   gateway is not `http://127.0.0.1:8642`) to `~/.botmancers/config/core.env`,
+   then `botmancers stop && botmancers start --daemon`.
+3. **Configure Agent Deck** for coding-agent runs: install Agent Deck so
+   `agent-deck` is on `PATH` and its server runs on `http://127.0.0.1:1111`,
+   and add `AGENT_DECK_RUN_TOKEN=<token issued by Agent Deck>` to `core.env`.
+4. **Connect an MCP client** to `http://127.0.0.1:43124/mcp` with
+   `Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`, taking the token from
+   `~/.botmancers/config/bridge.env`. For Codex, Cursor, or Claude Code,
+   `botmancers setup --client codex|cursor|claude` does this for you and adds
+   the optional collaboration skill
+   ([Client setup and the collaboration skill](#client-setup-and-the-collaboration-skill)).
+   To let `botmancers_start_task` reach a coordinator, list its Agent name in
+   `core.env` as `BOTMANCERS_MCP_COORDINATORS=Tank` and restart.
+5. **Check everything** with `botmancers doctor`.
+
+For anything long-running, use the managed install, or a pinned global
+release rather than `npx`: `npm install -g botmancers@0.4.2`, then run
+`botmancers setup` and `botmancers start --daemon`.
+
+### Product commands
+
+| Command | What it does | Exit codes |
+| --- | --- | --- |
+| `botmancers setup` | Creates `BOTMANCERS_HOME` and its credentials; re-running keeps them and re-tightens permissions, and refreshes the clients set up with `--client`. | `0`; `9` home not writable |
+| `botmancers setup --client codex\|cursor\|claude [--remove]` | Connects that MCP client to the bridge and installs the optional collaboration skill, or removes both. Files you edited are never overwritten. See [Client setup](#client-setup-and-the-collaboration-skill). | `0`; `2` usage or unsupported client; `11` client not installed; `12` conflicting files (nothing written) |
+| `botmancers start [--daemon] [--open]` | Starts the UI/core and the bridge. Without `--daemon` it stays in the foreground until Ctrl-C. Starting a healthy product again changes nothing. | `0` running; `1` a previous start is degraded; `6` a port is in use; `7` the core or bridge failed (both are stopped); `8` packaged app incomplete; `9` home not writable; `10` not set up |
+| `botmancers stop` | Stops the supervisor, the core, and the bridge. Safe to repeat. | `0`; `1` a process would not stop |
+| `botmancers status` | Reports `healthy`, `degraded`, or `stopped`, with the install kind, launcher, the CLI, current, and pending versions, the versions the live core and bridge report, both endpoints, process ids, and the restart action. | `0` healthy; `1` degraded; `3` stopped |
+| `botmancers doctor` | Checks the install kind, the launcher and `PATH` shadowing, the updater, Node, the packaged app, the home and its permissions, the credentials, the SQLite driver, ports, Hermes, Agent Deck, and the MCP clients set up with `--client`. Hermes, Agent Deck, and clients are optional and only warn. | `0` ok; `1` a check failed |
+| `botmancers open` | Opens the UI in a browser (`BOTMANCERS_BROWSER` overrides the command). | `0`; `1` no browser; `3` not running |
+| `botmancers mcp [options]` | Runs only the bridge; identical to bare `botmancers`. | see [bridge exit codes](#startup-checks-and-exit-codes) |
+| `botmancers install [--to VERSION] [--migrate-cli] [--purge-global]` | Managed install or rollback: downloads the release into `~/.botmancers/versions/VERSION`, verifies it, makes it current, and writes the launcher. `--purge-global` also runs `npm uninstall -g botmancers`; nothing else uninstalls it. | `0`; `1` download or verification failed; `2` usage |
+| `botmancers upgrade [--check] [--to VERSION] [--yes]` | Updates this install. See [Upgrade](#upgrade). | `0`; `1` failed, or this kind of install cannot update itself; `2` usage |
+
+`healthy` means the supervisor and both processes are alive, the core's
+`GET /api/health` and the bridge's `GET /healthz` report the installed
+version, and an authenticated bridge call reaches the core. Anything else
+that is running is `degraded` and never reported healthy: one process down,
+a version mismatch, or a start that has not finished. Run metadata whose
+processes are gone is removed automatically. Each process is recorded with
+its start time, and a recorded process id is only signalled when both its
+start time and its command line still match, so a recycled PID (even another
+Next.js server) is never touched. When identity cannot be verified (no `ps`,
+or metadata from an older release) nothing is signalled and the metadata is
+kept; the same holds if a process survives `stop`, so `status` keeps
+reporting it and `stop` can be retried.
+
+### Where state lives
+
+Everything the product writes lives under `BOTMANCERS_HOME` (default
+`~/.botmancers`), whatever directory you start it from:
+
+| Path | Contents |
+| --- | --- |
+| `config/core.env` | Core engine configuration: the bridge's service-token digest and anything you add (Hermes, Agent Deck, coordinators). Variables exported in your shell take precedence. |
+| `config/bridge.env` | The bridge's service token and MCP token. Keep private. |
+| `config/clients/<client>.json` | What `setup --client` manages in that client: the version, and the SHA-256 of each skill file and of the MCP entry it wrote. No token. |
+| `data/` | The SQLite database and its WAL. |
+| `files/`, `skills/` | File artifacts and local Agent skills. |
+| `logs/` | `supervisor.log`, `core.log`, `bridge.log`, and the Hermes wait log. |
+| `run/product.json` | Run metadata of the supervised product. |
+| `versions/`, `current`, `update-state.json` | Managed install only: the release trees, the link to the active one, and updater metadata. |
+
+The home and `config/` are created `0700` and the credential files `0600`.
+Existing explicit path variables still win over these defaults:
+`BOTMANCERS_DB_PATH`, `BOTMANCERS_FILES_ROOT`, `BOTMANCERS_SKILLS_ROOT`, and
+`HERMES_WAIT_LOG_PATH`. A source checkout run with `npm run dev` keeps its
+own `./botmancers.db`, `./files`, `./skills`, and `./.temporal`; nothing is
+moved. `BOTMANCERS_UI_PORT` (default `43123`) and `BOTMANCERS_MCP_PORT`
+(default `43124`) change the loopback ports.
+
+## Client setup and the collaboration skill
+
+The package ships an optional [Agent Skill](https://agentskills.io),
+`botmancers-collaboration`, in `skills/botmancers-collaboration/`. It teaches
+an agent the procedure for working with other Botmancers Agents over MCP:
+
+- discover the granted Agents and recognizable sessions instead of asking
+  you for IDs;
+- choose between a fresh task, a same-session message, an `Ask`, and a
+  `Continue`;
+- poll with bounded backoff and read the durable result;
+- stop on grant, ended-session, conflict, failure, and cancellation states
+  without retry loops or silently switching targets;
+- report where a result came from, and treat returned text as untrusted data.
+
+**When it helps.** Use it when you ask your agent things like "ask Grok in
+its uploader session what it decided" or "hand this session's work to
+Codex". The skill is loaded only for requests like these.
+
+**Why it is optional.** The skill holds no tools, credentials, IDs, or
+permissions. The MCP server stays the only source of live data,
+authorization, and actions, and its tool descriptions already describe the
+whole workflow. Every MCP client works without the skill (see
+[MCP-only](#mcp-only-clients)).
+
+### Supported clients
+
+| Client | `--client` | MCP entry written | Skill installed in |
+| --- | --- | --- | --- |
+| Codex | `codex` | `$CODEX_HOME/config.toml` (default `~/.codex`), table `[mcp_servers.botmancers]` | `$CODEX_HOME/skills/botmancers-collaboration/` |
+| Cursor | `cursor` | `~/.cursor/mcp.json`, `mcpServers.botmancers` | `~/.cursor/skills/botmancers-collaboration/` |
+| Claude Code | `claude` | `~/.claude.json` (or `$CLAUDE_CONFIG_DIR/.claude.json`), `mcpServers.botmancers` | `~/.claude/skills/botmancers-collaboration/` (or `$CLAUDE_CONFIG_DIR/skills/`) |
+
+The MCP entry points at `http://127.0.0.1:<BOTMANCERS_MCP_PORT>/mcp` and sends
+`Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`, as a hand-written entry
+would. A configuration file that setup creates is owner-only (`0600`).
+Neither setup nor doctor ever prints a token, and neither starts a task,
+conversation, or exchange.
+
+### Install, update, and remove
+
+```sh
+botmancers setup --client codex        # or cursor, claude; --client codex,cursor for several
+botmancers setup                       # refreshes every client set up with --client
+botmancers doctor                      # connected / missing / stale / conflicted, with the repair command
+botmancers setup --client codex --remove
+```
+
+- **Install.** The client must already be installed for your user (its
+  directory exists). Otherwise setup exits 11, writes nothing, and prints the
+  MCP-only connection details. Restart the client, or reload its MCP
+  servers, afterwards.
+- **Update.** Re-running is idempotent: unchanged files are not rewritten. A
+  new release ships the new skill version in the managed install. After
+  `botmancers upgrade`, or an automatic update, `botmancers doctor` reports the
+  client skill as `stale`, and `botmancers setup` refreshes it. After a
+  rotated MCP token or a changed `BOTMANCERS_MCP_PORT`, doctor reports the
+  MCP entry `stale` for the same repair. A rollback (`botmancers install
+  --to VERSION`) followed by `botmancers setup` puts that release's skill
+  back.
+- **Remove.** `--remove` deletes the skill files and the MCP entry that are
+  still exactly as Botmancers wrote them, and the ownership record. Anything
+  you edited is kept and listed.
+
+### Managed-file ownership
+
+Setup records each file and MCP entry it writes, with its SHA-256, in
+`config/clients/<client>.json` under `BOTMANCERS_HOME`. It replaces only a file
+or entry that still has the recorded hash, or that already has the wanted
+content. Your own MCP servers, other keys in the configuration file, and
+other skills are never touched. If the skill directory holds a file you
+edited, or the configuration already has a `botmancers` server that setup
+did not write, setup changes nothing for that client, exits 12, and lists
+what conflicts. To hand it back to Botmancers, keep a copy of your
+version, remove the listed files or entry, and re-run setup. If a write
+fails part way, setup restores every file it had already changed for that
+client. Credentials in `config/` are never rewritten by `--client`.
+
+### MCP-only clients
+
+Any other MCP client needs no setup and no skill. Connect it to the URL and
+header that `botmancers setup` prints:
+
+```text
+URL     http://127.0.0.1:43124/mcp
+Header  Authorization: Bearer <BOTMANCERS_MCP_TOKEN from ~/.botmancers/config/bridge.env>
+```
+
+Then follow the tool descriptions in workflow order: `botmancers_capabilities`,
+`botmancers_list_agents`, `botmancers_list_sessions`, an action, and
+`botmancers_get_exchange` until `terminal`
+([`docs/mcp-bridge.md`](../../docs/mcp-bridge.md)). A client that supports
+Agent Skills but is not listed above can also load the skill directly: copy
+`skills/botmancers-collaboration/` from this package into that client's skills
+directory. Setup does not manage that copy.
+
+## Bridge only
+
+Use bare `botmancers` (or `botmancers mcp`) when you run the Botmancers app
+yourself, for example from a source checkout. Requirements: Node.js 20 or
+newer and a running Botmancers app.
 
 1. **Create two tokens.** The service token authenticates the bridge to
    Botmancers. The MCP token authenticates MCP clients to the bridge.
@@ -58,10 +304,10 @@ Requirements: Node.js 20 or newer and a running Botmancers app.
 To pin an exact release, which is recommended for anything long-running:
 
 ```sh
-BOTMANCERS_URL=http://127.0.0.1:43123 npx botmancers@0.1.0
+BOTMANCERS_URL=http://127.0.0.1:43123 npx botmancers@0.4.2
 ```
 
-## Configuration
+## Bridge configuration
 
 | Variable | Flag | Required | Default | Meaning |
 | --- | --- | --- | --- | --- |
@@ -85,23 +331,33 @@ installed version.
   `2025-03-26`. Every request needs `Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`.
   `GET` and `DELETE` return 405 because the bridge opens no SSE stream and
   issues no session. Bodies over 256 KiB are refused with 413.
-- `GET /healthz` returns `{"status":"ok","contract":"botmancers.mcp.v1","version":"<version>"}`.
+- `GET /healthz` returns `{"status":"ok","contract":"botmancers.mcp.v2","contracts":["botmancers.mcp.v1","botmancers.mcp.v2"],"version":"<version>"}`.
   It needs no authentication and does not call Botmancers. Use the
   `botmancers_health` tool to check the end-to-end path.
 
 ### Startup checks and exit codes
 
-Before listening, the bridge validates its configuration. It then sends
-Botmancers an MCP `initialize` with the service token. That call writes
-nothing and does not count against the rate limit. No error message contains
-a token.
+Before listening, the bridge validates its configuration. It then runs a
+compatibility preflight: an MCP `initialize` and a `tools/list` with the
+service token, never a tool call, so it writes nothing and does not count
+against the rate limit. Botmancers must offer every bundled tool: all of
+`botmancers.mcp.v1`, all of `botmancers.mcp.v2`, and the v2 `agent_id` path of
+`botmancers_get_conversation`. Otherwise the bridge exits 4 naming exactly
+what is missing, for example `it serves only botmancers.mcp.v1; this bridge
+needs botmancers.mcp.v2 (missing botmancers_capabilities, ...)` or `missing
+botmancers.mcp.v2 tools: botmancers_send_to_session`. Upgrade that Botmancers,
+or pin a bridge release that predates v2. No error message contains a token.
+
+Every v1 and v2 `tools/call` is forwarded to Botmancers unchanged, and its
+result returned unchanged; Botmancers validates the arguments and applies
+the grants.
 
 | Exit | Meaning | What to do |
 | --- | --- | --- |
 | `0` | Stopped by SIGINT or SIGTERM. | Nothing. |
 | `2` | Configuration error: a missing or invalid variable or flag. Every problem is listed. | Fix the listed settings. |
 | `3` | Cannot listen, for example because the port is already in use. | Stop the other process, or choose another `--port`. |
-| `4` | Botmancers is unreachable, or `BOTMANCERS_URL` is not a Botmancers MCP endpoint (the server is not named `botmancers` or lacks a `botmancers.mcp.v1` tool). | Start the app, or fix the URL. |
+| `4` | Botmancers is unreachable, or `BOTMANCERS_URL` is not a compatible Botmancers MCP endpoint (the server is not named `botmancers`, or lacks a `botmancers.mcp.v1` or `botmancers.mcp.v2` tool). | Start or upgrade the app, or fix the URL. |
 | `5` | Botmancers rejected the service token, or the app has no service tokens configured. | Check `BOTMANCERS_SERVICE_TOKEN` against the app's `BOTMANCERS_SERVICE_TOKENS`. |
 
 If Botmancers becomes unavailable after startup, tool calls return a JSON-RPC
@@ -124,7 +380,8 @@ Botmancers rate-limits a tool call, the bridge answers 429 and passes on
   non-loopback address (`--host 0.0.0.0`), the bridge prints a warning. Keep
   the proxy or network in front of it.
 - **Botmancers itself** should stay on loopback, with the bridge on the same
-  machine. If `BOTMANCERS_URL` points to another host over plain `http://`,
+  machine. `botmancers start` binds both the UI/core and the bridge to
+  `127.0.0.1` only. If `BOTMANCERS_URL` points to another host over plain `http://`,
   the bridge warns that the service token is sent unencrypted. Use `https://`
   in that case.
 - Rotate a token by changing it and restarting the bridge. For the service
@@ -132,12 +389,81 @@ Botmancers rate-limits a tool call, the bridge answers 429 and passes on
 
 ## Upgrade
 
+### Managed install (automatic)
+
+A managed install checks npm's `latest` tag at most once every 24 hours, in a
+background process, so no command waits on the network. A newer release is
+downloaded next to the running one under a temporary name, checked against
+the registry's sha512 integrity and for a complete package, and then
+recorded as **pending**. The running product is not stopped or changed.
+`botmancers status` shows the versions the live core and bridge report, the
+pending version, and the restart command:
+
+```
+  versions    cli 0.3.0, current 0.3.0, pending 0.3.1 (staged, not running)
+  running     core 0.3.0, bridge 0.3.0 (started by 0.3.0)
+  restart     botmancers stop && botmancers start --daemon   (activates 0.3.1)
+```
+
+The pending release becomes current only when `botmancers start` has checked
+that no Botmancers process from this home is still running. `status`,
+`open`, `doctor`, the bridge, and a running product never switch it. If the
+product is still running, `start` leaves it alone and prints the restart
+command. Restart once to activate the pending release:
+
+```sh
+botmancers stop && botmancers start --daemon
+```
+
+Set `BOTMANCERS_DISABLE_AUTOUPDATER=1` to turn off the automatic checks,
+downloads, and activation completely. `botmancers upgrade` still works when
+it is set.
+
+Explicit commands:
+
+```sh
+botmancers upgrade --check          # installed, latest, and pending versions; changes nothing
+botmancers upgrade                  # download, verify, and activate latest
+botmancers upgrade --to 0.3.0       # a specific version
+botmancers install --to 0.3.0       # roll back (no download if it is still installed)
+```
+
+If the product is running, `upgrade` downloads the release and marks it
+pending. It does not switch versions underneath the running product. After a
+rollback, the newer version is not reinstalled automatically. A later
+`botmancers upgrade` moves forward again. The active release and the two most
+recent other complete releases are kept, and older or incomplete release
+trees are removed when a release is activated. Install, upgrade, rollback,
+and pruning change only `versions/`, `current`, `update-state.json`, and the
+launcher. They never touch your data, configuration, logs, or workdirs.
+
+If `botmancers doctor` reports that another `botmancers` (for example an
+npm-global copy) shadows `~/.local/bin/botmancers` on `PATH`, put
+`~/.local/bin` first, or run `botmancers install --purge-global` to remove
+the global copy.
+
+### npm-global, npx, and project-local installs
+
+These never update themselves automatically. `botmancers upgrade` on an
+npm-global install asks before it runs `npm install -g botmancers@<version>`
+(`--yes` skips the question). On any other kind of install, it explains how
+to upgrade and changes nothing.
+
 `npx botmancers` resolves the newest release on the `latest` tag the first
 time. After that, npx may reuse its cached copy. To move deliberately, name
 the version:
 
 ```sh
-npx botmancers@0.1.0 --version
+npx botmancers@0.4.2 --version
+```
+
+For a global full product, stop it, upgrade, and start it again. Your state
+in `BOTMANCERS_HOME` is kept:
+
+```sh
+botmancers stop
+npm install -g botmancers@latest
+botmancers start --daemon
 ```
 
 To upgrade a project-local or global install:
@@ -148,21 +474,31 @@ npm install -g botmancers@latest    # global
 ```
 
 Check the [changelog](CHANGELOG.md) before upgrading across a minor version
-while the package is `0.x`. The tool contract version, `botmancers.mcp.v1`,
-changes only with a major contract revision.
+while the package is `0.x`. The tool contract is versioned separately: the
+bundled `botmancers.mcp.v2` keeps `botmancers.mcp.v1` frozen, changes within v2
+are additive, and a breaking change is a new contract version.
 
 ## Uninstall
 
-Stop the bridge with Ctrl-C or SIGTERM, then remove the package:
+Stop the product with `botmancers stop` (or the bridge with Ctrl-C or
+SIGTERM), then remove the package:
 
 ```sh
 npm uninstall botmancers        # project-local
 npm uninstall -g botmancers     # global
 npm cache clean --force         # optional: drops npx's cached copy
+rm -rf ~/.botmancers/versions ~/.botmancers/current ~/.botmancers/update-state.json ~/.local/bin/botmancers   # managed install
 ```
 
-Finally, remove the bridge's entry from the app's `BOTMANCERS_SERVICE_TOKENS`
-so its token stops working. The bridge stores no files of its own.
+Before deleting the home, remove the client connections:
+`botmancers setup --client codex --remove` (and `cursor`, `claude`).
+
+For the full product, delete `~/.botmancers` (or your `BOTMANCERS_HOME`)
+only if you also want to delete its database, files, and credentials.
+
+For the bridge only, remove its entry from the app's
+`BOTMANCERS_SERVICE_TOKENS` so its token stops working. The bridge stores no
+files of its own.
 
 ## Library use
 

package/app/.next/BUILD_ID

@@ -0,0 +1 @@
+ewp56HqU5-d9bpFog3bli