@cotal-ai/connector-opencode 0.11.1 → 0.11.2

package/dist/plugin.bundle.js

@@ -24576,6 +24576,8 @@ var CotalEndpoint = class _CotalEndpoint extends EventEmitter {
   heartbeatTimer;
   sweepTimer;
   roster = /* @__PURE__ */ new Map();
+  /** Resolves when the current presence watch has consumed its complete initial KV snapshot. */
+  presenceSnapshot = Promise.resolve();
   status = "idle";
   activity;
   /** Mirror of the connector's authoritative attention state, published in presence (advisory). The
@@ -25215,6 +25217,22 @@ var CotalEndpoint = class _CotalEndpoint extends EventEmitter {
   getRoster() {
     return [...this.roster.values()].sort((a, b) => a.card.name.localeCompare(b.card.name));
   }
+  /** Wait until the current presence watch has consumed its initial KV snapshot. An empty bucket
+   * emits no watch entry, so the timeout keeps a genuinely empty mesh bounded. */
+  async waitForPresenceSnapshot(timeoutMs = 1e3) {
+    let timer;
+    try {
+      await Promise.race([
+        this.presenceSnapshot,
+        new Promise((resolve) => {
+          timer = setTimeout(resolve, timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
   async setActivity(activity) {
     this.activity = activity;
     await this.publishPresence();
@@ -26792,10 +26810,21 @@ var CotalEndpoint = class _CotalEndpoint extends EventEmitter {
   async startPresenceWatch() {
     if (!this.kv)
       return;
+    let hydrated;
+    this.presenceSnapshot = new Promise((resolve) => {
+      hydrated = resolve;
+    });
     const iter = await this.kv.watch();
     void (async () => {
-      for await (const e of iter)
+      let ready = false;
+      for await (const e of iter) {
         this.handleKvEntry(e);
+        if (!ready && e.isUpdate) {
+          ready = true;
+          hydrated();
+        }
+      }
+      hydrated();
     })().catch((e) => this.emit("error", e));
   }
   /** Watch the channel registry: replay existing keys, then stream updates, into the local
@@ -27010,9 +27039,9 @@ var Registry = class {
       throw new Error(`no ${kind} registered for "${name}"`);
     return ext;
   }
-  /** Every registered extension of a kind (e.g. all commands, for CLI dispatch). */
   all(kind) {
-    return [...this.#byKey.values()].filter((e) => e.kind === kind);
+    const values = [...this.#byKey.values()];
+    return kind === void 0 ? values : values.filter((e) => e.kind === kind);
   }
 };
 var registry = new Registry();
@@ -42222,7 +42251,7 @@ config(en_default());
 
 // ../connector-core/dist/docs-bundle.generated.js
 var DOCS_BUNDLE = {
-  "version": "0.11.1",
+  "version": "0.11.2",
   "generatedFrom": "docs/*.md + SPEC.md + spec/cotal.schema.json",
   "pages": [
     {
@@ -42244,7 +42273,7 @@ var DOCS_BUNDLE = {
       "title": "Architecture",
       "kind": "Concept (informative)",
       "summary": "Cotal is built as a thin waist: the normative wire contract (subjects, message schemas, presence/discovery, delivery semantics, the auth grammar) is the standard (SPEC), and everything else is a pl\u2026",
-      "body": "# Architecture\n\n> **Concept** (informative) \xB7 **For:** anyone who wants to know how Cotal is built, and why \xB7 **Normative:** [SPEC](../SPEC.md)\n\nCotal is built as a thin waist: the normative wire contract (subjects, message schemas,\npresence/discovery, delivery semantics, the auth grammar) is the standard\n([SPEC](../SPEC.md)), and everything else is a pluggable edge over existing building\nblocks. Identity, transport, storage, and discovery compose from proven pieces (NATS,\nJetStream, JWT/nkeys) rather than being reinvented. Adapters stay thin and swappable, and\nnothing adapter-specific leaks into the core.\n\n## Influences: A2A\n\nCotal reuses A2A's vocabulary and shapes so it stays interoperable rather than siloed, and\nimplements them over NATS/JetStream.\n\n**From A2A** come the *data shapes*: `AgentCard` (identity / role / tags / skills),\n`Message` / `Part` (text and data), and correlation ids (`contextId`). We do not adopt\nA2A's HTTP/JSON-RPC transport, `Task` RPCs, or its request/response server model, none of\nwhich fit lateral pub/sub.\n\nThe *addressing model* is Cotal's own: the hierarchical address `space / service / instance`\nand three delivery modes, multicast, unicast, anycast\n([presence & delivery](presence-and-delivery.md)). **Mentions** are a priority hint on a\nmulticast, not a routing target. NATS/JetStream is the data plane, adding the durability and\npresence a bare pub/sub layer leaves to the app.\n\nIdentity is an A2A `AgentCard` whose instance id is shaped to later become a **DID**\n(`did:key`) so authenticity can survive an untrusted relay ([roadmap](roadmap.md)).\n\n## One wire, mapped onto NATS\n\nThe whole protocol rides four subject kinds, with the sender encoded in the subject\nitself, where the server can police it, rather than in a self-asserted payload field\n([SPEC \xA73](../SPEC.md#3-subject-layout)):\n\n| Delivery | Subject |\n|---|---|\n| multicast | `cotal.<space>.chat.<owner>.<actor>.<channel\u2026>` |\n| unicast | `cotal.<space>.inst.<toOwner>.<toActor>.<owner>.<actor>` |\n| anycast | `cotal.<space>.svc.<role>.<owner>.<actor>` |\n| control | `cotal.<space>.ctl.<service>.<owner>.<actor>` |\n\nThe sender is a **principal**, an `owner.actor` pair: the account the agent acts on behalf\nof, then the agent's own handle under it ([identity & auth](identity-and-auth.md)). Two\ntokens instead of one means the broker can deny cross-owner *and* same-owner cross-actor\nforgery in the subject grammar itself.\n\nBehind the subjects, each space gets three **JetStream streams** (chat / DM / task, for\nstorage, per-reader bookmarks, and history), **KV buckets** for presence and the channel\nregistry, and the control plane as request/reply. Rather than re-implementing delivery\nguarantees, Cotal uses the native NATS mechanisms: streams for at-least-once and late\njoin, queue groups for anycast load-balancing, KV TTL for liveness ([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding);\nthe reasoning: [presence & delivery](presence-and-delivery.md)). Isolation is one NATS\n**account per space** ([spaces & channels](spaces.md)); authorization is per-agent JWT\nACLs ([identity & auth](identity-and-auth.md)). Large artifacts are reserved for a\nper-space Object Store ([roadmap](roadmap.md)).\n\nWhether any of this *requires* NATS is answered in\n[transport vs protocol](transport.md): the contract is transport-agnostic; NATS/JetStream\nis the reference binding.\n\n## Package layout: one-way tiers\n\n```\nexamples \u2500\u2500\u2192 implementations \u2500\u2500\u2192 workspace \u2500\u2500\u2192 core \u2190(peer)\u2500\u2500 extensions\n                (interoperate at runtime over NATS, not via imports)\n```\n\n- **`@cotal-ai/core`**, the protocol: subjects, schemas, the NATS client layer, and the\n  extension contracts (`Connector`, `Command`, `Runtime`) with the `Registry` they\n  self-register into. Depends on nothing else in the repo.\n- **`@cotal-ai/workspace`**, the machine-local operator layer over `~/.cotal`: mesh\n  registry, target resolution, auth-path helpers. Not part of the wire standard, so a\n  third party can embed core without inheriting workstation plumbing.\n- **`extensions/*`**: pluggable adapters (connectors, runtimes). Each **peer-depends** on\n  core (binding to the host's single core instance) and self-registers on import; an\n  unknown agent type **throws**, no silent fallback.\n- **`implementations/*`**, opinionated surfaces over core: the CLI, the manager, the\n  delivery daemon, the web dashboard. Implementations never import each other; they meet\n  at runtime, in a shared space over NATS. A composition root (the `cotal` binary, or an\n  example) wires the pieces it wants.\n- **`examples/*`**: use-cases and composition roots, never published\n  ([examples](examples.md)). An example only configures and orchestrates; new message\n  kinds or subjects go into core, generalized, never into an example.\n\nThe published binary also loads **operator-installed CLI extensions**: `cotal ext add\n<npm-package>` installs into a cotal-owned prefix, imports once so the package\nself-registers, then caches its command metadata for `--help`/completion; running a\ncommand imports lazily and parses live. Version skew or a stranded link fails loudly\nwith instructions to re-add, rather than leaving a silently missing command. The repo's\nown `@cotal-ai/web` dashboard is installed through this same mechanism.\n\n## Connectors: four surfaces, one runtime\n\nEvery coding-agent integration exposes the same four surfaces:\n\n| Surface | Carries |\n|---|---|\n| Outbound, ambient | lifecycle \u2192 presence and activity, automatically |\n| Outbound, deliberate | the messaging tools (`cotal_send` / `cotal_dm` / `cotal_anycast`) |\n| Inbound, pull | `cotal_inbox` |\n| Inbound, push | wake-and-inject into the live session |\n\nThe shared runtime lives in [`@cotal-ai/connector-core`](../extensions/connector-core):\nthe mesh agent, the [`cotal_*` tool surface](mcp-tools.md) (defined once in its tool\nspecs, so it cannot drift across hosts), and the delivery buffer with its attention\npolicy. Each adapter is a thin client\nover it that binds to its host's native mechanism: an installed plugin + MCP server for\n[Claude Code](connect-claude.md), an in-process plugin for\n[OpenCode](connect-opencode.md) (beta), a Python sidecar for\n[Hermes](connect-hermes.md) (alpha).\n\nThe endpoint underneath self-heals: when the transport connection dies terminally, a\nsupervisor rebuilds it (rebuilds are serialized and coalesced), and unacked in-flight\nmessages redeliver on the rebound durables, so nothing is lost across the gap. A manual\n`/reconnect` is the human-invoked counterpart.\n\n## Manager: a supervisor, not an orchestrator\n\nThe CLI does not spawn agents itself; a long-lived **manager** owns their lifecycle,\nasked over the mesh (it is the control plane's first real consumer). It owns process\nlifecycle and config binding (start / stop / restart, binding env and policy) and has\nno say in what work the agents do. Agents coordinate laterally; the manager only births\nand configures them.\n\n- **Off the message hot path.** Each agent self-connects to the mesh through its own\n  connector. The manager owns processes in order to control them, but observes everything\n  through presence, so a bring-your-own-terminal agent it never spawned still shows up in\n  `ps`.\n- **Pluggable runtimes.** Spawning is abstracted behind a `Runtime` contract (like pm2 or\n  docker for agent TUIs): **`pty`** ships built-in (the manager owns a pseudo-terminal;\n  watch or type via `cotal attach`); **`tmux`** and **`cmux`** are extensions that put\n  each teammate in its own window/tab (explicit opt-ins that throw when the extension\n  isn't loaded, never a silent fallback); **byo** is the floor (a human's own terminal,\n  tracked via presence); **host** (Agent SDK, true mid-turn interrupt) is the documented\n  upgrade path ([roadmap](roadmap.md)).\n- **Control schema:** `start {role, name, agent, model?, variant?}` \xB7 `models {agent?,\n  refresh?}` \xB7 `stop {name, graceful?}` \xB7 `definePersona {name, persona, model?}` \xB7 `ps` \xB7\n  `status` \xB7 `attach` \xB7 `bind`, request/reply messages any authorized node can send,\n  policy-gated ([identity & auth](identity-and-auth.md)).\n- **Bounded spawn.** A synchronous gate caps concurrent + in-flight agents and a\n  minimum-lifetime floor bounds spawn\u2194despawn churn, so a capability-holding but\n  compromised peer cannot fork-bomb the host.\n- **Declared env, not inherited.** Runtimes pass spawned children an explicit allow-list\n  (PATH / HOME / locale / TERM + the model key + opted-in shared-server vars, forwarded by\n  name), never `process.env`, so the operator's unrelated secrets stop bleeding into every\n  agent. This closes env-var bleed; it does not prevent filesystem reads or exfiltration\n  of the model key itself.\n- **Watching is two channels.** The console/dashboard discovers agents over the **mesh**\n  (presence, `ps`) but streams terminal pixels over a **direct attach connection** to the\n  PTY owner; high-bandwidth terminal I/O never rides NATS. On attach, the manager replays\n  a serialized snapshot of a headless terminal mirror, so a late attach repaints the full\n  screen (including alternate-screen TUIs).\n\nThe result is that an agent can grow and shape its own team: ask for a teammate\n(`cotal_spawn`), mint a persona on the fly (`cotal_persona`), or tear one down\n(`cotal_despawn`). Every newcomer joins as a peer, not as a child of whoever requested\nit. Destructive space-wide operations (history purge) stay operator-only.\n\n## Observers\n\nA watch surface is a read-only observer: an endpoint that consumes without registering\npresence (invisible to peers) while watching everyone else's. All three surfaces\n(terminal console, plain stream, web dashboard) derive from that one observer through a\nshared render-agnostic model, so no surface re-implements wire semantics. The guide is\n[watch a mesh](watch-a-mesh.md); the model is [MeshView](mesh-view.md).\n\n## Names, roles, instances\n\nThree identity layers, in increasing permanence\n([SPEC \xA72](../SPEC.md#2-identity), [\xA76](../SPEC.md#6-presence-and-discovery)):\n\n- **`name`** is a cosmetic, reusable human handle. Addressing by name is best-effort\n  convenience, with deterministic and fail-loud resolution: a unique live name resolves,\n  and a collision among live peers throws with the candidate ids rather than silently\n  picking one. The manager auto-numbers its own spawns (`reviewer` \u2192 `reviewer-2`).\n- **`role`** is the addressable service, which makes it the anycast address:\n  `svc.reviewer` reaches \"whoever is a reviewer\", so the label carries routing meaning.\n- **The instance id** is the authoritative address: the presence key, the unicast target,\n  the credential subject.\n\n**Instance continuity:** the id tracks *context* continuity, not the label. A resumed\nsession (same context window) keeps its id; presence, thread correlation, and in-flight\nDMs stay continuous. A fresh context, even reusing the name, is a **new** instance with a\nnew id: reusing an id across a discontinuous context would tell peers \"same agent, same\nmemory\" when the new session has none. One deliberate exception: OpenCode's `/new` inside\nthe same managed process keeps the mesh identity and advances only the thread correlation\nid: process continuity, not credential reuse.\n\n## Deferred\n\nSessions/moderator, signed envelopes + DID identity, instant offline, artifact delivery,\nauth-callout, and federation are designed for but not built yet; each is tracked, with\nits direction, in the [roadmap](roadmap.md).\n"
+      "body": "# Architecture\n\n> **Concept** (informative) \xB7 **For:** anyone who wants to know how Cotal is built, and why \xB7 **Normative:** [SPEC](../SPEC.md)\n\nCotal is built as a thin waist: the normative wire contract (subjects, message schemas,\npresence/discovery, delivery semantics, the auth grammar) is the standard\n([SPEC](../SPEC.md)), and everything else is a pluggable edge over existing building\nblocks. Identity, transport, storage, and discovery compose from proven pieces (NATS,\nJetStream, JWT/nkeys) rather than being reinvented. Adapters stay thin and swappable, and\nnothing adapter-specific leaks into the core.\n\n## Influences: A2A\n\nCotal reuses A2A's vocabulary and shapes so it stays interoperable rather than siloed, and\nimplements them over NATS/JetStream.\n\n**From A2A** come the *data shapes*: `AgentCard` (identity / role / tags / skills),\n`Message` / `Part` (text and data), and correlation ids (`contextId`). We do not adopt\nA2A's HTTP/JSON-RPC transport, `Task` RPCs, or its request/response server model, none of\nwhich fit lateral pub/sub.\n\nThe *addressing model* is Cotal's own: the hierarchical address `space / service / instance`\nand three delivery modes, multicast, unicast, anycast\n([presence & delivery](presence-and-delivery.md)). **Mentions** are a priority hint on a\nmulticast, not a routing target. NATS/JetStream is the data plane, adding the durability and\npresence a bare pub/sub layer leaves to the app.\n\nIdentity is an A2A `AgentCard` whose instance id is shaped to later become a **DID**\n(`did:key`) so authenticity can survive an untrusted relay ([roadmap](roadmap.md)).\n\n## One wire, mapped onto NATS\n\nThe whole protocol rides four subject kinds, with the sender encoded in the subject\nitself, where the server can police it, rather than in a self-asserted payload field\n([SPEC \xA73](../SPEC.md#3-subject-layout)):\n\n| Delivery | Subject |\n|---|---|\n| multicast | `cotal.<space>.chat.<owner>.<actor>.<channel\u2026>` |\n| unicast | `cotal.<space>.inst.<toOwner>.<toActor>.<owner>.<actor>` |\n| anycast | `cotal.<space>.svc.<role>.<owner>.<actor>` |\n| control | `cotal.<space>.ctl.<service>.<owner>.<actor>` |\n\nThe sender is a **principal**, an `owner.actor` pair: the account the agent acts on behalf\nof, then the agent's own handle under it ([identity & auth](identity-and-auth.md)). Two\ntokens instead of one means the broker can deny cross-owner *and* same-owner cross-actor\nforgery in the subject grammar itself.\n\nBehind the subjects, each space gets three **JetStream streams** (chat / DM / task, for\nstorage, per-reader bookmarks, and history), **KV buckets** for presence and the channel\nregistry, and the control plane as request/reply. Rather than re-implementing delivery\nguarantees, Cotal uses the native NATS mechanisms: streams for at-least-once and late\njoin, queue groups for anycast load-balancing, KV TTL for liveness ([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding);\nthe reasoning: [presence & delivery](presence-and-delivery.md)). Isolation is one NATS\n**account per space** ([spaces & channels](spaces.md)); authorization is per-agent JWT\nACLs ([identity & auth](identity-and-auth.md)). Large artifacts are reserved for a\nper-space Object Store ([roadmap](roadmap.md)).\n\nWhether any of this *requires* NATS is answered in\n[transport vs protocol](transport.md): the contract is transport-agnostic; NATS/JetStream\nis the reference binding.\n\n## Package layout: one-way tiers\n\n```\nexamples \u2500\u2500\u2192 implementations \u2500\u2500\u2192 workspace \u2500\u2500\u2192 core \u2190(peer)\u2500\u2500 extensions\n                (interoperate at runtime over NATS, not via imports)\n```\n\n- **`@cotal-ai/core`**, the protocol: subjects, schemas, the NATS client layer, and the\n  extension contracts (`Connector`, `Command`, `Runtime`) with the `Registry` they\n  self-register into. Depends on nothing else in the repo.\n- **`@cotal-ai/workspace`**, the machine-local operator layer over `~/.cotal`: mesh\n  registry, target resolution, auth-path helpers. Not part of the wire standard, so a\n  third party can embed core without inheriting workstation plumbing.\n- **`extensions/*`**: pluggable adapters (connectors, runtimes). Each **peer-depends** on\n  core (binding to the host's single core instance) and self-registers on import; an\n  unknown agent type **throws**, no silent fallback.\n- **`implementations/*`**, opinionated surfaces over core: the CLI, the manager, the\n  delivery daemon, the web dashboard. Implementations never import each other; they meet\n  at runtime, in a shared space over NATS. A composition root (the `cotal` binary, or an\n  example) wires the pieces it wants.\n- **`examples/*`**: use-cases and composition roots, never published\n  ([examples](examples.md)). An example only configures and orchestrates; new message\n  kinds or subjects go into core, generalized, never into an example.\n\nThe published binary also loads **operator-installed extensions**: `cotal ext add\n<npm-package>` installs into a cotal-owned prefix, imports once so the package\nself-registers, then caches every contributed `kind:name`. Command metadata is cached for\n`--help`/completion; running a command or requesting a provider imports its owner lazily and\nuses the live object. Version skew or a stranded link fails loudly with instructions to re-add.\nThe repo's `@cotal-ai/web` dashboard and optional tmux/cmux/Orca runtimes use this mechanism; the\npublished binary does not hardcode those packages.\n\nMachine-local processes use the same registry. The base CLI contributes broker/control-plane\n`local-process` descriptors, while an installed package contributes its own (for example `web`).\nThat keeps `cotal down <component>` and `cotal status` extensible without teaching the base CLI\npackage-specific pidfiles. A provider process claims its declared pidfile with exclusive create;\nextension removal reserves that same path so startup cannot cross uninstall.\n\n## Connectors: four surfaces, one runtime\n\nEvery coding-agent integration exposes the same four surfaces:\n\n| Surface | Carries |\n|---|---|\n| Outbound, ambient | lifecycle \u2192 presence and activity, automatically |\n| Outbound, deliberate | the messaging tools (`cotal_send` / `cotal_dm` / `cotal_anycast`) |\n| Inbound, pull | `cotal_inbox` |\n| Inbound, push | wake-and-inject into the live session |\n\nThe shared runtime lives in [`@cotal-ai/connector-core`](../extensions/connector-core):\nthe mesh agent, the [`cotal_*` tool surface](mcp-tools.md) (defined once in its tool\nspecs, so it cannot drift across hosts), and the delivery buffer with its attention\npolicy. Each adapter is a thin client\nover it that binds to its host's native mechanism: an installed plugin + MCP server for\n[Claude Code](connect-claude.md), an in-process plugin for\n[OpenCode](connect-opencode.md) (beta), a Python sidecar for\n[Hermes](connect-hermes.md) (alpha).\n\nThe endpoint underneath self-heals: when the transport connection dies terminally, a\nsupervisor rebuilds it (rebuilds are serialized and coalesced), and unacked in-flight\nmessages redeliver on the rebound durables, so nothing is lost across the gap. A manual\n`/reconnect` is the human-invoked counterpart.\n\n## Manager: a supervisor, not an orchestrator\n\nThe CLI does not spawn agents itself; a long-lived **manager** owns their lifecycle,\nasked over the mesh (it is the control plane's first real consumer). It owns process\nlifecycle and config binding (start / stop / restart, binding env and policy) and has\nno say in what work the agents do. Agents coordinate laterally; the manager only births\nand configures them.\n\n- **Off the message hot path.** Each agent self-connects to the mesh through its own\n  connector. The manager owns processes in order to control them, but observes everything\n  through presence, so a bring-your-own-terminal agent it never spawned still shows up in\n  `ps`.\n- **Pluggable runtimes.** Spawning is abstracted behind a `Runtime` contract (like pm2 or\n  docker for agent TUIs): **`pty`** ships built-in (the manager owns a pseudo-terminal;\n  watch or type via `cotal attach`); **`tmux`**, **`cmux`**, and **`orca`** are extensions\n  that put each teammate in its own native terminal surface (explicit opt-ins that throw when the extension\n  isn't loaded, never a silent fallback); **byo** is the floor (a human's own terminal,\n  tracked via presence); **host** (Agent SDK, true mid-turn interrupt) is the documented\n  upgrade path ([roadmap](roadmap.md)).\n- **Control schema:** `start {role, name, agent, model?, variant?}` \xB7 `models {agent?,\n  refresh?}` \xB7 `stop {name, graceful?}` \xB7 `definePersona {name, persona, model?}` \xB7 `ps` \xB7\n  `status` \xB7 `attach` \xB7 `bind`, request/reply messages any authorized node can send,\n  policy-gated ([identity & auth](identity-and-auth.md)).\n- **Bounded spawn.** A synchronous gate caps concurrent + in-flight agents and a\n  minimum-lifetime floor bounds spawn\u2194despawn churn, so a capability-holding but\n  compromised peer cannot fork-bomb the host.\n- **Declared env, not inherited.** Runtimes pass spawned children an explicit allow-list\n  (PATH / HOME / locale / TERM + the model key + opted-in shared-server vars, forwarded by\n  name), never `process.env`, so the operator's unrelated secrets stop bleeding into every\n  agent. This closes env-var bleed; it does not prevent filesystem reads or exfiltration\n  of the model key itself.\n- **Watching is two channels.** The console/dashboard discovers agents over the **mesh**\n  (presence, `ps`) but streams terminal pixels over a **direct attach connection** to the\n  PTY owner; high-bandwidth terminal I/O never rides NATS. On attach, the manager replays\n  a serialized snapshot of a headless terminal mirror, so a late attach repaints the full\n  screen (including alternate-screen TUIs).\n\nThe result is that an agent can grow and shape its own team: ask for a teammate\n(`cotal_spawn`), mint a persona on the fly (`cotal_persona`), or tear one down\n(`cotal_despawn`). Every newcomer joins as a peer, not as a child of whoever requested\nit. Destructive space-wide operations (history purge) stay operator-only.\n\n## Observers\n\nA watch surface is a read-only observer: an endpoint that consumes without registering\npresence (invisible to peers) while watching everyone else's. All three surfaces\n(terminal console, plain stream, web dashboard) derive from that one observer through a\nshared render-agnostic model, so no surface re-implements wire semantics. The guide is\n[watch a mesh](watch-a-mesh.md); the model is [MeshView](mesh-view.md).\n\n## Names, roles, instances\n\nThree identity layers, in increasing permanence\n([SPEC \xA72](../SPEC.md#2-identity), [\xA76](../SPEC.md#6-presence-and-discovery)):\n\n- **`name`** is a cosmetic, reusable human handle. Addressing by name is best-effort\n  convenience, with deterministic and fail-loud resolution: a unique live name resolves,\n  and a collision among live peers throws with the candidate ids rather than silently\n  picking one. The manager auto-numbers its own spawns (`reviewer` \u2192 `reviewer-2`).\n- **`role`** is the addressable service, which makes it the anycast address:\n  `svc.reviewer` reaches \"whoever is a reviewer\", so the label carries routing meaning.\n- **The instance id** is the authoritative address: the presence key, the unicast target,\n  the credential subject.\n\n**Instance continuity:** the id tracks *context* continuity, not the label. A resumed\nsession (same context window) keeps its id; presence, thread correlation, and in-flight\nDMs stay continuous. A fresh context, even reusing the name, is a **new** instance with a\nnew id: reusing an id across a discontinuous context would tell peers \"same agent, same\nmemory\" when the new session has none. One deliberate exception: OpenCode's `/new` inside\nthe same managed process keeps the mesh identity and advances only the thread correlation\nid: process continuity, not credential reuse.\n\n## Deferred\n\nSessions/moderator, signed envelopes + DID identity, instant offline, artifact delivery,\nauth-callout, and federation are designed for but not built yet; each is tracked, with\nits direction, in the [roadmap](roadmap.md).\n"
     },
     {
       "slug": "mcp-tools",
@@ -42286,14 +42315,14 @@ var DOCS_BUNDLE = {
       "title": "`cotal` CLI reference",
       "kind": "Reference: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract.",
       "summary": "cotal is the operator command line for the reference implementation: bring a mesh up, mint identities, launch agents, watch what they do, and tear it all down.",
-      "body": "# `cotal` CLI reference\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\n`cotal` is the operator command line for the reference implementation: bring a mesh up, mint\nidentities, launch agents, watch what they do, and tear it all down. It is a thin client over the\nwire contract: the normative subjects and schemas live in the [SPEC](../SPEC.md); this page is\nlookup material for the commands, not a walkthrough; if you are new, start with\n[Getting started](getting-started.md).\n\n## Running it\n\n```bash\nnpm install -g cotal-ai   # puts `cotal` on your PATH (needs Node 20+)\ncotal --help              # every command, grouped\ncotal <command> --help    # one command's flags and usage\n```\n\n`npx cotal-ai <command>` runs it without a global install; in a dev clone, `pnpm cotal <command>`\nruns it through `tsx` with no build step. Bare `cotal` prints help. Every command generates its own\n`--help`, usage, and shell completion from its declared flags.\n\nCommands come from the surfaces the binary composes: the base mesh CLI, the manager\n(`supervise`), and the delivery daemon (`deliver`), plus any operator-installed extensions.\n`cotal ext add <npm-package>` adds a package's commands to this same surface (the `web` dashboard\nships this way; see [`web`](#web)).\n\n## Commands\n\n| Area | Command | Purpose |\n|---|---|---|\n| Set up & lifecycle | [`setup`](#setup) | Guided, configure-only setup (installs, seeds personas; launches nothing) |\n| Set up & lifecycle | [`up`](#up) | Start a local mesh (nats-server + JetStream), or boot a whole manifest with `-f` |\n| Set up & lifecycle | [`down`](#down) | Stop a background mesh, or tear down a manifest / `spawn -f` deploy |\n| Set up & lifecycle | [`clean`](#clean) | Configurable cleanup: purge history (live), or wipe the local store / identity (stopped) |\n| Set up & lifecycle | [`meshes`](#meshes-use-status) | List the running meshes on this machine |\n| Set up & lifecycle | [`use`](#meshes-use-status) | Set the default mesh a bare `cotal spawn` joins |\n| Set up & lifecycle | [`status`](#meshes-use-status) | Read-only diagnostics for setup, processes, and the selected mesh |\n| Agents & personas | [`spawn`](#spawn) | Launch an agent from a persona (foreground, or `--detach` via the manager) |\n| Agents & personas | [`models`](#models) | List connector model catalogs and variants from the manager |\n| Agents & personas | [`ps`](#ps-stop-attach) | List managed agents and their mesh status |\n| Agents & personas | [`stop`](#ps-stop-attach) | Ask the manager to stop a managed agent |\n| Agents & personas | [`attach`](#ps-stop-attach) | Stream and drive a managed agent's terminal (pty runtime) |\n| Agents & personas | [`personas`](#personas) | List, show, edit, create, or remove local personas |\n| Agents & personas | [`supervise`](#supervise) | Run a manager daemon (the agent supervisor / control plane) |\n| Messaging & watching | [`send`](#send) | Send one message, then exit: DM a peer, post a channel, or ask a role |\n| Messaging & watching | [`channels`](#channels) | Inspect or set the channel registry (replay, description, instructions) |\n| Messaging & watching | [`history`](#history) | Clear retained message history |\n| Messaging & watching | [`console`](#console) | Live protocol view for a space (TUI, or `--plain` line stream) |\n| Messaging & watching | [`web`](#web) | Browser dashboard (installed as the `@cotal-ai/web` extension) |\n| Auth & meshes | [`mint`](#mint) | Mint a creds file for a space (static auth mode) |\n| Auth & meshes | [`login`](#login-logout) | Sign in to a per-user-auth mesh's IdP (once per machine) |\n| Auth & meshes | [`logout`](#login-logout) | Revoke the IdP session and clear the cached login |\n| Auth & meshes | [`actor`](#actor) | Manage a user-auth space's actor ledger (grant / revoke / list) |\n| Auth & meshes | [`doctor`](#doctor) | Credential-health diagnosis and repair (`doctor auth`) |\n| Auth & meshes | [`join`](#join) | Join a space as your own presence (interactive) |\n| Manifest | [`topology`](#manifest-deploys) | Validate and view a mesh manifest's access graph (read-only) |\n| Extensions & misc | [`ext`](#ext) | Install / remove operator CLI extensions |\n| Extensions & misc | [`completion`](#completion) | Print or install shell completion |\n| Extensions & misc | [`feedback`](#feedback) | Send feedback to the Cotal developers |\n| Extensions & misc | [`deliver`](#server-daemons) | Run the server-side Plane-3 delivery daemon |\n| Extensions & misc | [`feedback-intake`](#server-daemons) | Run a self-hosted feedback intake server |\n\nThe manifest modes of `up`, `spawn`, and `down` (`-f <cotal.yaml>`) plus `topology` are covered\ntogether under [Manifest deploys](#manifest-deploys).\n\n## setup\n\n```bash\ncotal setup [--full] [--demo] [--yes]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--full` | off | Redo the full guided flow (implies `--demo`) |\n| `--demo` | off | Also seed the guided expert team (`david`, `sven`, `me`) |\n| `--yes`, `-y` | off | Non-interactive accept-all (for agents / CI) |\n\nGuided setup is **configure-only**: it checks prerequisites, installs the Claude Code plugin, and\nseeds persona files, and it launches nothing (no mesh, no web, no manager). First run gets the\nnarrated flow; later runs print a status card. By default it seeds one `default` persona; the\n`david`/`sven`/`me` team is opt-in via `--demo`. See [Getting started](getting-started.md) and, for\nmaintainers, [setup internals](setup-internals.md).\n\n## up\n\n```bash\ncotal up [--detach] [--open] [--space <s>] [--server <url>] [--channels <path>]\ncotal up -f <cotal.yaml> [--dry-run] [--runtime <pty|tmux|cmux>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--server <url>` | auto (free local port) | Listen URL override |\n| `--host <host>` | \u2014 | Bind host override |\n| `--space <s>` | the folder's name | Space name |\n| `--store-dir <dir>` | \u2014 | JetStream store directory |\n| `--channels <path>` | `.cotal/channels.json` if present | Channel-registry seed file (JSON). An explicit path that is missing is an error |\n| `--open` | off (auth) | Unauthenticated dev mesh: no JWT, no ACLs |\n| `--user-auth` | off | Per-user auth: people `cotal login`; connects are authorized against the actor ledger |\n| `--idp <url>` | \u2014 | With `--user-auth`: the IdP auth base URL to pin on first enable |\n| `--detach` | off | Run in the background (stop with `cotal down`) |\n| `--file <cotal.yaml>`, `-f` | \u2014 | Launch a whole mesh from a manifest |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--runtime <pty\\|tmux\\|cmux>` | manifest's | With `-f`: override the manifest's runtime |\n\n`cotal up` boots a local nats-server with JetStream and, in auth mode (the default), JWT auth and\nper-agent ACLs; `--detach` records the mesh so `cotal spawn` from any directory can find it. With no\n`--server`, it auto-selects a free port if the default address is taken; an explicit `--server`\nstays fail-loud on collision. `--detach` also brings up the control plane (delivery daemon in auth\nmode, then the manager). The `-f` form is a [manifest deploy](#manifest-deploys); see\n[Run a mesh](run-a-mesh.md).\n\n`--user-auth --idp <url>` starts the space's auth service alongside the broker (the NATS\nauth callout plus the loopback token exchange); it is torn down with `cotal down`, and a\nre-run of `cotal up` heals a dead service on a running broker. `--user-auth` and `--open`\ncontradict each other and are refused loudly; a running broker cannot change auth mode\nwithout a `cotal down` first. See [identity & auth](identity-and-auth.md).\n\n## down\n\n```bash\ncotal down\ncotal down -f <cotal.yaml> | --run <id> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--file <cotal.yaml>`, `-f` | \u2014 | Tear down this manifest's deploy |\n| `--run <id>` | \u2014 | Tear down one `spawn -f` run by id |\n| `--dry-run` | off | Print the plan, mutate nothing |\n\nBare `cotal down` stops a background mesh started with `cotal up --detach`. The `-f` / `--run` forms\ntear down a [manifest deploy](#manifest-deploys) without stopping the whole mesh. `down` never\ndeletes on-disk state; that is [`clean`](#clean).\n\n## clean\n\n```bash\ncotal clean <history|store|all> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | `history`: target mesh |\n| `--dms` | off | `history`: also clear DM history |\n| `--store-dir <dir>` | `.cotal/nats` | `store`/`all`: JetStream store directory |\n| `--force` | \u2014 | Required: destructive, no prompting |\n\nOne configurable cleanup verb; every target requires `--force`.\n\n- `history` purges the retained message backlog on the **running** broker (channels, plus DMs\n  with `--dms`). The same operation as [`history clear`](#history), which stays as an alias.\n- `store` deletes the **stopped** mesh's JetStream store (`.cotal/nats`): streams, durable\n  consumers, and messages. This is the reset for stale on-disk broker state, e.g. durables\n  minted by an older, incompatible Cotal generation surviving a `down`/`up` cycle.\n- `all` is `store` plus the space identity (`.cotal/auth`), the local creds and markers tied to\n  it, any crash residue a normal `down` would have swept (stale pidfiles, `run/`), and the mesh's\n  registry entry; the next `cotal up` mints a fresh identity.\n\n`history` needs the mesh up; `store` and `all` refuse while any recorded mesh process is still\nalive (run `cotal down` first). Personas (`.cotal/agents`) and logs are never touched. A custom\nstore location is not recorded anywhere, so `--store-dir` must repeat whatever the mesh was\nlaunched with.\n\n## meshes, use, status\n\n```bash\ncotal meshes\ncotal use <space>\ncotal status [--space <s>] [--server <url>]\n```\n\n`meshes` lists the running meshes on this machine; a `*` marks the `current` default a bare\n`cotal spawn` joins. `use <space>` sets that default when several are running. `status` is a\nread-only report across four sections: machine prerequisites, this folder's `.cotal/`, the\nrecorded meshes, and a live snapshot of the selected mesh (roster, channels, membership feed).\n`status` takes only `--space` / `--server` to pick the mesh to inspect; it starts nothing.\n\n## spawn\n\n```bash\ncotal spawn [<persona>] [--detach] [--name <n>] [--agent <a>] [--model <m>] [--variant <v>] [--prompt <text>] [--cwd <dir>]\ncotal spawn -f <cotal.yaml> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | resolved mesh | Target space |\n| `--server <url>` | registry entry | Broker URL override |\n| `--creds <path>` | \u2014 | Control-caller creds for an off-registry manager (`--detach` only) |\n| `--name <n>` | persona's `name:` | Presence-name override (does not choose the persona) |\n| `--config <persona-or-path>` | \u2014 | Persona catalog name or file path; wins over the positional |\n| `--agent <a>` | `COTAL_DEFAULT_AGENT`, else `claude` | Connector type (`claude`, `opencode`, `hermes`, \u2026) |\n| `--role <r>` | persona's `role:` | Role override |\n| `--model <m>` | persona's `model:` | Model override |\n| `--variant <v>` | persona's `variant:` | Model variant override (connector-defined; e.g. OpenCode reasoning tiers) |\n| `--cwd <dir>` | this cwd | Working directory to root the agent at |\n| `--prompt <text>` | \u2014 | Initial prompt auto-submitted at start |\n| `--resume <id>` | \u2014 | Fork an existing session id into the mesh (claude only) |\n| `--transcript` / `--no-transcript` | off | Mirror the session transcript to `tr-<name>` |\n| `--share-tools <sel>` | none | Share named operator MCP servers with the agent |\n| `--subscribe <a,b>` | persona's | Channel read-set override |\n| `--allow-subscribe <a,b>` | = subscribe | Read-ACL override |\n| `--allow-publish <a,b>` | deny | Post-ACL override |\n| `--detach`, `-d` | off | Launch via the manager into a detached PTY (reattach with `cotal attach`) |\n| `--file <cotal.yaml>`, `-f` | \u2014 | Deploy a manifest onto the running mesh |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--allow-stale <a,b>` | \u2014 | With `-f`: waive named stale agents (apply-only) |\n| `--runtime <pty\\|tmux\\|cmux>` | manifest's | With `-f`: override the manifest's runtime |\n\nThe persona (`--config` > positional > `COTAL_DEFAULT_PERSONA` > `default`) is loaded from the\ntarget mesh's `.cotal/agents/`; the launch flags override the file. Foreground runs the agent\nattached to your terminal; `--detach` hands the launch to the running manager. `--detach` is the\nonly mode that registers a durable delivery membership; a foreground spawn reads live only. See\n[Connect Claude Code](connect-claude.md) and [Agent files](agent-files.md); `-f` is a\n[manifest deploy](#manifest-deploys). (`cotal start` was merged into `cotal spawn --detach`.)\n\n## models\n\n```bash\ncotal models [--agent <connector>] [--refresh]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--agent <connector>` | all registered connectors | Connector whose catalog to list |\n| `--refresh` | off | Ask the connector to refresh its provider cache |\n\nAsks the running manager for each connector's model catalog (model ids plus their variants)\nfor connectors that expose one (OpenCode today; a connector without a catalog says so). Pick a\nresult with `cotal spawn --model <provider/model> --variant <v>`.\n\n## ps, stop, attach\n\n```bash\ncotal ps [--space <s>]\ncotal stop --name <n> [--space <s>]\ncotal attach --name <n> [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | \u2014 | Managed agent to stop / attach (required) |\n\nThese are operator clients over the running manager's control plane. `ps` lists managed agents with\ntheir mesh status (`starting\u2026` / `working` / `waiting` / `offline`); on a user-auth mesh it also\nrenders each managed agent's last credential-refresh outcome, fail-closed. `attach` streams and\ndrives an agent's terminal on the `pty` runtime; detach with the escape key (Ctrl-] by default; see\n[`COTAL_DETACH_KEY`](config.md)). `stop` and `attach` need a running manager to talk to. On a\nstatic mesh they are cross-agent admin operations. On a user-auth mesh, your own agents (any agent\nunder your owner) need only the `spawn` scope; another owner's agent needs `admin` on your ledger\nrow ([identity & auth](identity-and-auth.md)). Launch detached agents with\n[`spawn --detach`](#spawn).\n\n## personas\n\n```bash\ncotal personas list [-v] [--running]\ncotal personas show <name>\ncotal personas edit <name>\ncotal personas new <name> (--prompt <t> | --from <f>) [--role <r>] [--model <m>]\ncotal personas rm <name> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh's persona catalog |\n| `--role <r>` | \u2014 | `new`: the persona's role |\n| `--model <m>` | \u2014 | `new`: the persona's model |\n| `--prompt <t>` | \u2014 | `new`: the persona's prompt text |\n| `--from <f>` | \u2014 | `new`: seed the prompt from a file |\n| `--verbose`, `-v` | off | `list`: include role / model / description |\n| `--running` | off | `list`: mark personas live on the mesh |\n| `--force` | \u2014 | `rm`: required, delete without prompting |\n\nPersonas are the local agent files under `.cotal/agents/` that `cotal spawn` launches. See\n[Agent files](agent-files.md) for the file format.\n\n## supervise\n\n```bash\ncotal supervise [--runtime <pty|tmux|cmux>] [--space <s>] [--server <url>] [--spawn <names>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space to supervise |\n| `--server <url>` | the local mesh | Broker URL |\n| `--runtime <pty\\|tmux\\|cmux>` | `pty` | Agent runtime (`tmux`/`cmux` are explicit-only) |\n| `--console-port <n>` | \u2014 | Protocol-console port |\n| `--roster <file>` | \u2014 | Declarative roster to boot at startup |\n| `--launch <spec>` | \u2014 | Resolved manifest launch spec (from `up -f` / `spawn -f`) |\n| `--spawn <names>` | \u2014 | Comma-separated personas to pre-spawn at startup |\n\nThe manager is the agent supervisor and control plane: it answers `spawn --detach`, `stop`, `ps`,\n`attach`, and the `cotal_*` manager tools. `cotal up --detach` starts one for you; run `supervise`\ndirectly to recover a dead manager or drive a custom runtime. Default runtime is `pty`; `tmux`/`cmux`\nrequire their extensions and are never selected implicitly. See [Deploy](deploy.md).\n\n## send\n\n```bash\ncotal send dm <agent> \"<text>\"   [--space <s>] [--server <url>] [--creds <path>]\ncotal send msg <channel> \"<text>\"\ncotal send ask <role> \"<text>\"\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and (off-registry) which credential |\n\nOne-shot messaging: connect, send a single direct message (`dm`), channel post (`msg`), or role\nask/anycast (`ask`), then exit. For a running conversation, agents use the mesh tools instead\n([MCP tools](mcp-tools.md)).\n\n## channels\n\n```bash\ncotal channels list\ncotal channels set <name> [--replay | --no-replay] [--window <n>] [--desc <s>] [--instructions <s>]\ncotal channels default --replay | --no-replay\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--replay` / `--no-replay` | \u2014 | `set`/`default`: replay history to new joiners, or not |\n| `--window <n>` | \u2014 | `set`: replay window size |\n| `--desc <s>` | \u2014 | `set`: one-line channel description |\n| `--instructions <s>` | \u2014 | `set`: instructions shown to joiners |\n\nInspects and edits the channel registry: replay policy, description, and joiner instructions. ACL\nsemantics (who may read or post) are set at mint / provision time, not here; see\n[Channels and permissions](channels-and-permissions.md). On a user-auth mesh, `list` rides your\nown login as is; `set` and `default` edit the registry over a short-lived channel-writer view,\nwhich needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n## history\n\n```bash\ncotal history clear --force [--dms] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--dms` | off | Also clear DM history |\n| `--force` | \u2014 | Required: clear without prompting |\n\nPurges retained channel history; `--dms` extends it to direct-message history. An alias of\n[`clean history`](#clean). On a user-auth mesh the purge rides a short-lived purger view over\nyour login, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n## console\n\n```bash\ncotal console [--plain] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to watch |\n| `--plain` | off | Line stream instead of the TUI |\n\nA live protocol view for a space: a lazygit-style TUI, or a plain line stream on `--plain`. On a\nuser-auth mesh it rides the read-only admin view over your login, which needs ledger scope\n`admin`. See [Watch a mesh](watch-a-mesh.md).\n\n## web\n\n```bash\ncotal ext add @cotal-ai/web   # install once\ncotal web [--port <n>] [--no-open] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to serve |\n| `--port <n>` | `7799` | HTTP port |\n| `--no-open` | off | Don't open the browser |\n\nThe browser observability dashboard: presence, channels, and a live feed. It is **not** part of\n`cotal up`: it ships as the `@cotal-ai/web` extension (`cotal setup` installs it automatically; otherwise\n`cotal ext add @cotal-ai/web`). It self-registers `cotal web` into this surface and serves\n`http://cotal.localhost:7799` (loopback; `*.localhost` resolves in Chrome/Firefox/Edge; Safari may\nneed `http://127.0.0.1:7799`). On a user-auth mesh the dashboard rides the read-only admin view\nover your login, and a channel purge asks for its own channel-purger view per click; both need\nledger scope `admin`. See [Watch a mesh](watch-a-mesh.md).\n\n## mint\n\n```bash\ncotal mint <name> [--profile <agent|observer|admin>] [--out <path>] [--signer]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--profile <agent\\|observer\\|admin>` | `agent` | Credential profile |\n| `--out <path>` | `.cotal/auth/creds/<name>.creds` | Output path |\n| `--signer` | off | Emit a stripped account-signing file instead |\n| `--force` | off | With `--signer`: overwrite an existing file |\n| `--allow-subscribe <a,b>` | profile default | Read-ACL override |\n| `--allow-publish <a,b>` | profile default | Post-ACL override |\n\nMints a NATS creds file for a space in **static** auth mode, scoped to a profile and (optionally)\nexplicit read/post ACLs. `--signer` emits an account-signing file for delegating minting to another\nhost. A per-user-auth space refuses `mint`: agents there join under a logged-in user\n([`login`](#login-logout) + [`actor grant`](#actor)), never via a handed-out creds file. See\n[Identity and auth](identity-and-auth.md).\n\n## login, logout\n\n```bash\ncotal login --idp <auth base URL> [--client-id <id>]\ncotal logout --idp <auth base URL>\n```\n\nSigns you in to a per-user-auth mesh's IdP (device code flow) and caches the session; run it\nonce per machine. It prints your IdP subject, the id the operator grants against. After a\nlogin, every command on that mesh works under your identity: each connect takes a fresh IdP\nproof, exchanges it locally for a short-lived bearer, and is authorized against the actor\nledger at connect time. `logout` revokes the IdP session and clears the cache. See\n[identity & auth](identity-and-auth.md).\n\n## actor\n\n```bash\ncotal actor grant <actor> --sub <IdP subject> [--scope a,b] [--allow-subscribe a,b] [--allow-publish a,b] [--role <r>] [--label <l>]\ncotal actor revoke <actor> (--sub <IdP subject> | --owner <u_\u2026>)\ncotal actor list\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | the folder's | Space whose ledger to manage |\n| `--sub <subject>` | \u2014 | The IdP subject (shown by `cotal login`) the actor belongs to |\n| `--owner <u_\u2026>` | \u2014 | The derived owner token (alternative to `--sub`) |\n| `--scope <a,b>` | `spawn,role:default` | Capability scope (`''` = none; `spawn` = may run agents, `role:<r>` = may delegate role r, `admin` = cross-agent control) |\n| `--allow-subscribe <a,b>` | `>` (all channels) | Channel read ACL; the user's envelope, their agents can never read beyond it |\n| `--allow-publish <a,b>` | `>` (all channels) | Channel post ACL; also the envelope for their agents' posting |\n| `--role <r>` | \u2014 | Role (scopes the task-queue consumer) |\n| `--label <l>` | \u2014 | Display label for `actor list` (never the IdP subject) |\n\nThe actor ledger is the single authorization source of a user-auth space: no row, no access.\nA bare `grant` is the **full** envelope (all channels, may spawn); the flags narrow it. A\nre-grant **replaces** the row, so to add a capability, re-grant with it added to the current\nscope (`cotal actor list` shows what a row holds). `revoke` denies the next exchange and the\nnext connect with no restart, and evicts the principal's live connections. Managed-agent rows\n(written by the spawn path) live in a disjoint row space this command never touches. See\n[identity & auth](identity-and-auth.md).\n\n## doctor\n\n```bash\ncotal doctor auth [--fix]\n```\n\nCredential-health diagnosis and repair for this folder's mesh: renders every managed\ncredential as healthy / near-expiry / expired and ends in `healthy` or the exact next\ncommand; `--fix` applies the repairs it can. The one surface every stale-credential error\npoints at.\n\n## join\n\n```bash\ncotal join --space <s> --name <n> [--role <r>] [--channel <c>]\ncotal join --link <url> | --token <t>\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and which credential |\n| `--name <n>` | \u2014 | Your presence name |\n| `--role <r>` | \u2014 | Your role |\n| `--channel <c>` | \u2014 | Channel to join |\n| `--kind <k>` | `agent` | Endpoint kind |\n| `--link <url>` | \u2014 | Join link (`cotal://\u2026`) |\n| `--token <t>` | \u2014 | Join token |\n| `--tls` | off | Connect over TLS |\n\nAn interactive presence: join a space under your own name and role, without launching an agent\nharness. A `--link` or `--token` supplies the where and the auth in one value. See\n[Spaces](spaces.md) and [Identity and auth](identity-and-auth.md).\n\n## Manifest deploys\n\nA `cotal.yaml` manifest declares a whole mesh (channels, personas, roles, and ACLs) in one file.\nThree commands consume it, plus a read-only validator:\n\n```bash\ncotal up -f cotal.yaml         # boot a fresh mesh from the manifest\ncotal spawn -f cotal.yaml      # deploy the manifest additively onto a running mesh\ncotal down -f cotal.yaml       # tear that deploy down (or --run <id> for one run)\ncotal topology view -f cotal.yaml   # validate + view the access graph, change nothing\n```\n\n`up -f` and `spawn -f` differ in target: `up -f` brings up a new broker and applies the manifest;\n`spawn -f` requires an already-reachable mesh and applies additively (ownership-scoped). On a\nuser-auth mesh, `spawn -f` deploys over your own login (the deployer view, gated on ledger scope\n`spawn`): the manifest's agents land under your owner, a manifest claiming another owner is\nrefused, and seeding new channels additionally needs scope `admin`. Both take\n`--dry-run` to print the plan without mutating anything. `topology` validates the manifest and\nrenders its channel / role / ACL graph. See [Define a team](define-a-team.md) and the\n[manifest reference](manifest.md).\n\n## ext\n\n```bash\ncotal ext add <npm-package>\ncotal ext remove <name>\ncotal ext list\n```\n\nOperator-installed CLI extensions: `add` installs an npm package into a cotal-owned prefix and makes\nits commands appear in help, completion, and dispatch; `remove` and `list` manage them. The\n`@cotal-ai/web` dashboard is the canonical example. Installed packages and their location are described\nin [config](config.md).\n\n## completion\n\n```bash\ncotal completion <bash|zsh|fish|powershell>   # print a stub to eval / source\ncotal completion install [shell]              # install it persistently\n```\n\nPrints or installs shell completion. Completion candidates come from each command's declared flags\nand, where useful, live mesh state (spaces, personas, managed agents) resolved offline.\n\n## feedback\n\n```bash\ncotal feedback \"<summary>\" [--type <t>] [--email <e>] [--details <text>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--type <t>` | \u2014 | `bug` \\| `idea` \\| `friction` \\| `praise` \\| `other` |\n| `--details <text>` | \u2014 | Longer free-form details |\n| `--severity <s>` | \u2014 | `low` \\| `medium` \\| `high` |\n| `--area <a>` | \u2014 | The part of Cotal this concerns |\n| `--email <e>` | git email | Contact email (required on the keyless public path) |\n| `--name <n>` | \u2014 | Your name (optional) |\n| `--url <url>` | keyed / public intake | Intake URL override |\n| `--key <k>` | `COTAL_FEEDBACK_KEY` | Feedback key |\n\nSends feedback to the Cotal developers. With a key (`--key` / `COTAL_FEEDBACK_KEY`) it routes to the\nkeyed beta intake; without one it goes to the public `cotal.ai` intake and requires a contact email\n(`--email` / `COTAL_FEEDBACK_EMAIL`, else your git email). Run a self-hosted intake with\n[`feedback-intake`](#server-daemons).\n\n## Server daemons\n\nTwo long-lived infra roles ship with the CLI. They are not part of everyday operation; the delivery\ndaemon comes up automatically with `cotal up --detach` in auth mode.\n\n```bash\ncotal deliver --space <s> [--server <url>] [--creds <file>]\ncotal auth-service --space <s> --server <url> [--port <n>]\ncotal feedback-intake --keys <keys.json> [--port <n>] [--creds <file>]\n```\n\n`auth-service` runs a user-auth space's identity plane (the NATS auth callout plus the\nloopback token exchange and JWKS); `cotal up --user-auth` starts and supervises it for you,\nso you run it directly only to recover one by hand.\n\n`deliver` runs the server-side Plane-3 delivery daemon: the durable backstop and membership/ACL\nauthority. It is auth-mode-only and single-instance (`--shard`/`--shards` accept only `N=1`);\n`--dev-mint` mints a scoped cred from the local signer for standalone dev. See the\n[delivery daemon](delivery-daemon.md). `feedback-intake` runs a self-hosted feedback server\n(requires `--keys` and a scoped `--creds`), announcing submissions into a space channel; flags\ninclude `--host`/`--port`, `--store`, `--space`/`--channel`, `--max-bytes`, and `--rate-limit`.\n\n## Plumbing\n\n`cotal __complete <words\u2026>` is the internal entry the shell-completion stubs call to emit candidates\nfor the current command line; you never run it directly. `cotal agent-bearer` is machine-facing\nplumbing on user-auth meshes: spawned agents exec it to print a fresh short-lived bearer from their\nspawn-time secret; you never run it directly either. (`cotal start` is a removed tombstone: it\nerrors and points you to `cotal spawn --detach`.)\n"
+      "body": "# `cotal` CLI reference\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\n`cotal` is the operator command line for the reference implementation: bring a mesh up, mint\nidentities, launch agents, watch what they do, and tear it all down. It is a thin client over the\nwire contract: the normative subjects and schemas live in the [SPEC](../SPEC.md); this page is\nlookup material for the commands, not a walkthrough; if you are new, start with\n[Getting started](getting-started.md).\n\n## Running it\n\n```bash\nnpm install -g cotal-ai   # puts `cotal` on your PATH (needs Node 20+)\ncotal --help              # every command, grouped\ncotal <command> --help    # one command's flags and usage\n```\n\n`npx cotal-ai <command>` runs it without a global install; in a dev clone, `pnpm cotal <command>`\nruns it through `tsx` with no build step. Bare `cotal` prints help. Every command generates its own\n`--help`, usage, and shell completion from its declared flags.\n\nCommands come from the surfaces the binary composes: the base mesh CLI, the manager\n(`supervise`), and the delivery daemon (`deliver`), plus any operator-installed extensions.\n`cotal ext add <npm-package>` installs any registry providers a package contributes: commands,\nruntimes, and local process lifecycle descriptors. The `web` dashboard and optional manager\nruntimes ship this way.\n\n## Commands\n\n| Area | Command | Purpose |\n|---|---|---|\n| Set up & lifecycle | [`setup`](#setup) | Guided, configure-only setup (installs, seeds personas; launches nothing) |\n| Set up & lifecycle | [`up`](#up) | Start a local mesh (nats-server + JetStream), or boot a whole manifest with `-f` |\n| Set up & lifecycle | [`down`](#down) | Stop the whole stack, selected registered components, or a manifest deploy |\n| Set up & lifecycle | [`clean`](#clean) | Configurable cleanup: purge history (live), or wipe the local store / identity (stopped) |\n| Set up & lifecycle | [`meshes`](#meshes-use-status) | List the running meshes on this machine |\n| Set up & lifecycle | [`use`](#meshes-use-status) | Set the default mesh a bare `cotal spawn` joins |\n| Set up & lifecycle | [`status`](#meshes-use-status) | Read-only diagnostics for setup, processes, and the selected mesh |\n| Agents & personas | [`spawn`](#spawn) | Launch an agent from a persona (foreground, or `--detach` via the manager) |\n| Agents & personas | [`models`](#models) | List connector model catalogs and variants from the manager |\n| Agents & personas | [`ps`](#ps-stop-attach) | List managed agents and their mesh status |\n| Agents & personas | [`stop`](#ps-stop-attach) | Ask the manager to stop a managed agent |\n| Agents & personas | [`attach`](#ps-stop-attach) | Stream and drive a managed agent's terminal (pty runtime) |\n| Agents & personas | [`personas`](#personas) | List, show, edit, create, or remove local personas |\n| Agents & personas | [`supervise`](#supervise) | Run a manager daemon (the agent supervisor / control plane) |\n| Messaging & watching | [`endpoints`](#endpoints) | List every endpoint in the live presence roster, including infrastructure |\n| Messaging & watching | [`send`](#send) | Send one message, then exit: DM a peer, post a channel, or ask a role |\n| Messaging & watching | [`channels`](#channels) | Inspect or set the channel registry (replay, description, instructions) |\n| Messaging & watching | [`history`](#history) | Clear retained message history |\n| Messaging & watching | [`console`](#console) | Live protocol view for a space (TUI, or `--plain` line stream) |\n| Messaging & watching | [`web`](#web) | Browser dashboard (installed as the `@cotal-ai/web` extension) |\n| Auth & meshes | [`mint`](#mint) | Mint a creds file for a space (static auth mode) |\n| Auth & meshes | [`login`](#login-logout) | Sign in to a per-user-auth mesh's IdP (once per machine) |\n| Auth & meshes | [`logout`](#login-logout) | Revoke the IdP session and clear the cached login |\n| Auth & meshes | [`actor`](#actor) | Manage a user-auth space's actor ledger (grant / revoke / list) |\n| Auth & meshes | [`doctor`](#doctor) | Credential-health diagnosis and repair (`doctor auth`) |\n| Auth & meshes | [`join`](#join) | Join a space as your own presence (interactive) |\n| Manifest | [`topology`](#manifest-deploys) | Validate and view a mesh manifest's access graph (read-only) |\n| Extensions & misc | [`ext`](#ext) | Install / remove operator CLI extensions |\n| Extensions & misc | [`completion`](#completion) | Print or install shell completion |\n| Extensions & misc | [`feedback`](#feedback) | Send feedback to the Cotal developers |\n| Extensions & misc | [`deliver`](#server-daemons) | Run the server-side Plane-3 delivery daemon |\n| Extensions & misc | [`feedback-intake`](#server-daemons) | Run a self-hosted feedback intake server |\n\nThe manifest modes of `up`, `spawn`, and `down` (`-f <cotal.yaml>`) plus `topology` are covered\ntogether under [Manifest deploys](#manifest-deploys).\n\n## setup\n\n```bash\ncotal setup [--full] [--demo] [--yes]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--full` | off | Redo the full guided flow (implies `--demo`) |\n| `--demo` | off | Also seed the guided expert team (`david`, `sven`, `me`) |\n| `--yes`, `-y` | off | Non-interactive accept-all (for agents / CI) |\n\nGuided setup is **configure-only**: it checks prerequisites, installs the Claude Code plugin, and\nseeds persona files, and it launches nothing (no mesh, no web, no manager). First run gets the\nnarrated flow; later runs print a status card. By default it seeds one `default` persona; the\n`david`/`sven`/`me` team is opt-in via `--demo`. See [Getting started](getting-started.md) and, for\nmaintainers, [setup internals](setup-internals.md).\n\n## up\n\n```bash\ncotal up [--detach] [--open] [--space <s>] [--server <url>] [--channels <path>]\ncotal up -f <cotal.yaml> [--dry-run] [--runtime <name>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--server <url>` | auto (free local port) | Listen URL override |\n| `--host <host>` | \u2014 | Bind host override |\n| `--space <s>` | the folder's name | Space name |\n| `--store-dir <dir>` | \u2014 | JetStream store directory |\n| `--channels <path>` | `.cotal/channels.json` if present | Channel-registry seed file (JSON). An explicit path that is missing is an error |\n| `--open` | off (auth) | Unauthenticated dev mesh: no JWT, no ACLs |\n| `--user-auth` | off | Per-user auth: people `cotal login`; connects are authorized against the actor ledger |\n| `--idp <url>` | \u2014 | With `--user-auth`: the IdP auth base URL to pin on first enable |\n| `--detach` | off | Run in the background (stop with `cotal down`) |\n| `--file <cotal.yaml>`, `-f` | \u2014 | Launch a whole mesh from a manifest |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--runtime <name>` | manifest's | With `-f`: override the manifest's runtime (`pty` built in; others installed extensions) |\n\n`cotal up` boots a local nats-server with JetStream and, in auth mode (the default), JWT auth and\nper-agent ACLs; `--detach` records the mesh so `cotal spawn` from any directory can find it. With no\n`--server`, it auto-selects a free port if the default address is taken; an explicit `--server`\nstays fail-loud on collision. `--detach` also brings up the control plane (delivery daemon in auth\nmode, then the manager). The `-f` form is a [manifest deploy](#manifest-deploys); see\n[Run a mesh](run-a-mesh.md).\n\n`--user-auth --idp <url>` starts the space's auth service alongside the broker (the NATS\nauth callout plus the loopback token exchange); it is torn down with `cotal down`, and a\nre-run of `cotal up` heals a dead service on a running broker. `--user-auth` and `--open`\ncontradict each other and are refused loudly; a running broker cannot change auth mode\nwithout a `cotal down` first. See [identity & auth](identity-and-auth.md).\n\n## down\n\n```bash\ncotal down\ncotal down manager [delivery auth web nats ...]\ncotal down -f <cotal.yaml> | --run <id> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--file <cotal.yaml>`, `-f` | \u2014 | Tear down this manifest's deploy |\n| `--run <id>` | \u2014 | Tear down one `spawn -f` run by id |\n| `--dry-run` | off | Print the manifest teardown or selected components, mutate nothing |\n\nBare `cotal down` stops the whole local stack in dependency order. Positional component names stop\nonly those self-registered local processes; for example, `cotal down manager` leaves delivery and\nthe broker running, and `cotal down web` is available when the web extension is installed. The\n`-f` / `--run` forms tear down a [manifest deploy](#manifest-deploys) without stopping the whole mesh\nand cannot be combined with component names. Stopping `nats` alone is refused while an unselected\nregistered daemon is still live; include those components or use bare `cotal down`.\n\n`down` never deletes on-disk state; that is [`clean`](#clean).\n\n## clean\n\n```bash\ncotal clean <history|store|all> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | `history`: target mesh |\n| `--dms` | off | `history`: also clear DM history |\n| `--store-dir <dir>` | `.cotal/nats` | `store`/`all`: JetStream store directory |\n| `--force` | \u2014 | Required: destructive, no prompting |\n\nOne configurable cleanup verb; every target requires `--force`.\n\n- `history` purges the retained message backlog on the **running** broker (channels, plus DMs\n  with `--dms`). The same operation as [`history clear`](#history), which stays as an alias.\n- `store` deletes the **stopped** mesh's JetStream store (`.cotal/nats`): streams, durable\n  consumers, and messages. This is the reset for stale on-disk broker state, e.g. durables\n  minted by an older, incompatible Cotal generation surviving a `down`/`up` cycle.\n- `all` is `store` plus the space identity (`.cotal/auth`), the local creds and markers tied to\n  it, any crash residue a normal `down` would have swept (stale pidfiles, `run/`), and the mesh's\n  registry entry; the next `cotal up` mints a fresh identity.\n\n`history` needs the mesh up; `store` and `all` refuse while any recorded mesh process is still\nalive (run `cotal down` first). Personas (`.cotal/agents`) and logs are never touched. A custom\nstore location is not recorded anywhere, so `--store-dir` must repeat whatever the mesh was\nlaunched with.\n\n## meshes, use, status\n\n```bash\ncotal meshes\ncotal use <space>\ncotal status [--space <s>] [--server <url>]\n```\n\n`meshes` lists the running meshes on this machine; a `*` marks the `current` default a bare\n`cotal spawn` joins. `use <space>` sets that default when several are running. `status` is a\nread-only report across four sections: machine prerequisites, this folder's `.cotal/`, the\nrecorded meshes, and a live snapshot of the selected mesh (roster, channels, membership feed).\n`status` takes only `--space` / `--server` to pick the mesh to inspect; it starts nothing.\n\n## spawn\n\n```bash\ncotal spawn [<persona>] [--detach] [--name <n>] [--agent <a>] [--model <m>] [--variant <v>] [--prompt <text>] [--cwd <dir>]\ncotal spawn -f <cotal.yaml> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | resolved mesh | Target space |\n| `--server <url>` | registry entry | Broker URL override |\n| `--creds <path>` | \u2014 | Control-caller creds for an off-registry manager (`--detach` only) |\n| `--name <n>` | persona's `name:` | Presence-name override (does not choose the persona) |\n| `--config <persona-or-path>` | \u2014 | Persona catalog name or file path; wins over the positional |\n| `--agent <a>` | `COTAL_DEFAULT_AGENT`, else `claude` | Connector type (`claude`, `opencode`, `hermes`, \u2026) |\n| `--role <r>` | persona's `role:` | Role override |\n| `--model <m>` | persona's `model:` | Model override |\n| `--variant <v>` | persona's `variant:` | Model variant override (connector-defined; e.g. OpenCode reasoning tiers) |\n| `--cwd <dir>` | this cwd | Working directory to root the agent at |\n| `--prompt <text>` | \u2014 | Initial prompt auto-submitted at start |\n| `--resume <id>` | \u2014 | Fork an existing session id into the mesh (claude only) |\n| `--transcript` / `--no-transcript` | off | Mirror the session transcript to `tr-<name>` |\n| `--share-tools <sel>` | none | Share named operator MCP servers with the agent |\n| `--subscribe <a,b>` | persona's | Channel read-set override |\n| `--allow-subscribe <a,b>` | = subscribe | Read-ACL override |\n| `--allow-publish <a,b>` | deny | Post-ACL override |\n| `--detach`, `-d` | off | Launch via the manager into a detached PTY (reattach with `cotal attach`) |\n| `--file <cotal.yaml>`, `-f` | \u2014 | Deploy a manifest onto the running mesh |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--allow-stale <a,b>` | \u2014 | With `-f`: waive named stale agents (apply-only) |\n| `--runtime <name>` | manifest's | With `-f`: override the manifest's runtime |\n\nThe persona (`--config` > positional > `COTAL_DEFAULT_PERSONA` > `default`) is loaded from the\ntarget mesh's `.cotal/agents/`; the launch flags override the file. Foreground runs the agent\nattached to your terminal; `--detach` hands the launch to the running manager. `--detach` is the\nonly mode that registers a durable delivery membership; a foreground spawn reads live only. See\n[Connect Claude Code](connect-claude.md) and [Agent files](agent-files.md); `-f` is a\n[manifest deploy](#manifest-deploys). (`cotal start` was merged into `cotal spawn --detach`.)\n\n## models\n\n```bash\ncotal models [--agent <connector>] [--refresh]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--agent <connector>` | all registered connectors | Connector whose catalog to list |\n| `--refresh` | off | Ask the connector to refresh its provider cache |\n\nAsks the running manager for each connector's model catalog (model ids plus their variants)\nfor connectors that expose one (OpenCode today; a connector without a catalog says so). Pick a\nresult with `cotal spawn --model <provider/model> --variant <v>`.\n\n## endpoints\n\n```bash\ncotal endpoints [--space <s>] [--server <url>] [--creds <path>]\n```\n\nLists the mesh presence roster: agents, the manager, and any other protocol endpoint, with each\nendpoint's role, kind, status, and current activity. Unlike `ps`, this is a read-only presence view;\nit is not limited to child processes owned by the manager.\n\n## ps, stop, attach\n\n```bash\ncotal ps [--space <s>]\ncotal stop --name <n> [--space <s>]\ncotal attach --name <n> [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | \u2014 | Managed agent to stop / attach (required) |\n\nThese are operator clients over the running manager's control plane. `ps` lists managed agents with\ntheir mesh status (`starting\u2026` / `working` / `waiting` / `offline`); on a user-auth mesh it also\nrenders each managed agent's last credential-refresh outcome, fail-closed. `attach` streams and\ndrives an agent's terminal on the `pty` runtime; detach with the escape key (Ctrl-] by default; see\n[`COTAL_DETACH_KEY`](config.md)). `stop` and `attach` need a running manager to talk to. On a\nstatic mesh they are cross-agent admin operations. On a user-auth mesh, your own agents (any agent\nunder your owner) need only the `spawn` scope; another owner's agent needs `admin` on your ledger\nrow ([identity & auth](identity-and-auth.md)). Launch detached agents with\n[`spawn --detach`](#spawn).\n\n## personas\n\n```bash\ncotal personas list [-v] [--running]\ncotal personas show <name>\ncotal personas edit <name>\ncotal personas new <name> (--prompt <t> | --from <f>) [--role <r>] [--model <m>]\ncotal personas rm <name> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh's persona catalog |\n| `--role <r>` | \u2014 | `new`: the persona's role |\n| `--model <m>` | \u2014 | `new`: the persona's model |\n| `--prompt <t>` | \u2014 | `new`: the persona's prompt text |\n| `--from <f>` | \u2014 | `new`: seed the prompt from a file |\n| `--verbose`, `-v` | off | `list`: include role / model / description |\n| `--running` | off | `list`: mark personas live on the mesh |\n| `--force` | \u2014 | `rm`: required, delete without prompting |\n\nPersonas are the local agent files under `.cotal/agents/` that `cotal spawn` launches. See\n[Agent files](agent-files.md) for the file format.\n\n## supervise\n\n```bash\ncotal supervise [--runtime <name>] [--space <s>] [--server <url>] [--spawn <names>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space to supervise |\n| `--server <url>` | the local mesh | Broker URL |\n| `--runtime <name>` | `pty` | Agent runtime (`pty` built in; extension runtimes are explicit-only) |\n| `--console-port <n>` | \u2014 | Protocol-console port |\n| `--roster <file>` | \u2014 | Declarative roster to boot at startup |\n| `--launch <spec>` | \u2014 | Resolved manifest launch spec (from `up -f` / `spawn -f`) |\n| `--spawn <names>` | \u2014 | Comma-separated personas to pre-spawn at startup |\n\nThe manager is the agent supervisor and control plane: it answers `spawn --detach`, `stop`, `ps`,\n`attach`, and the `cotal_*` manager tools. `cotal up --detach` starts one for you; run `supervise`\ndirectly to recover a dead manager or drive a custom runtime. Default runtime is `pty`; install an\noptional provider first (`cotal ext add @cotal-ai/orca`, `@cotal-ai/tmux`, or `@cotal-ai/cmux`) and\nselect it explicitly. A missing provider or app fails loudly; there is no fallback. See [Deploy](deploy.md).\n\n## send\n\n```bash\ncotal send dm <agent> \"<text>\"   [--space <s>] [--server <url>] [--creds <path>]\ncotal send msg <channel> \"<text>\"\ncotal send ask <role> \"<text>\"\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and (off-registry) which credential |\n\nOne-shot messaging: connect, send a single direct message (`dm`), channel post (`msg`), or role\nask/anycast (`ask`), then exit. For a running conversation, agents use the mesh tools instead\n([MCP tools](mcp-tools.md)).\n\n## channels\n\n```bash\ncotal channels list\ncotal channels set <name> [--replay | --no-replay] [--window <n>] [--desc <s>] [--instructions <s>]\ncotal channels default --replay | --no-replay\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--replay` / `--no-replay` | \u2014 | `set`/`default`: replay history to new joiners, or not |\n| `--window <n>` | \u2014 | `set`: replay window size |\n| `--desc <s>` | \u2014 | `set`: one-line channel description |\n| `--instructions <s>` | \u2014 | `set`: instructions shown to joiners |\n\nInspects and edits the channel registry: replay policy, description, and joiner instructions. ACL\nsemantics (who may read or post) are set at mint / provision time, not here; see\n[Channels and permissions](channels-and-permissions.md). On a user-auth mesh, `list` rides your\nown login as is; `set` and `default` edit the registry over a short-lived channel-writer view,\nwhich needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n## history\n\n```bash\ncotal history clear --force [--dms] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--dms` | off | Also clear DM history |\n| `--force` | \u2014 | Required: clear without prompting |\n\nPurges retained channel history; `--dms` extends it to direct-message history. An alias of\n[`clean history`](#clean). On a user-auth mesh the purge rides a short-lived purger view over\nyour login, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n## console\n\n```bash\ncotal console [--plain] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to watch |\n| `--plain` | off | Line stream instead of the TUI |\n\nA live protocol view for a space: a lazygit-style TUI, or a plain line stream on `--plain`. On a\nuser-auth mesh it rides the read-only admin view over your login, which needs ledger scope\n`admin`. See [Watch a mesh](watch-a-mesh.md).\n\n## web\n\n```bash\ncotal ext add @cotal-ai/web   # install once\ncotal web [--port <n>] [--no-open] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to serve |\n| `--port <n>` | `7799` | HTTP port |\n| `--no-open` | off | Don't open the browser |\n\nThe browser observability dashboard: presence, channels, and a live feed. It is **not** part of\n`cotal up`: it ships as the `@cotal-ai/web` extension (`cotal setup` installs it automatically; otherwise\n`cotal ext add @cotal-ai/web`). It self-registers `cotal web` into this surface and serves\n`http://cotal.localhost:7799` (loopback; `*.localhost` resolves in Chrome/Firefox/Edge; Safari may\nneed `http://127.0.0.1:7799`). On a user-auth mesh the dashboard rides the read-only admin view\nover your login, and a channel purge asks for its own channel-purger view per click; both need\nledger scope `admin`. See [Watch a mesh](watch-a-mesh.md).\n\n## mint\n\n```bash\ncotal mint <name> [--profile <agent|observer|admin>] [--out <path>] [--signer]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--profile <agent\\|observer\\|admin>` | `agent` | Credential profile |\n| `--out <path>` | `.cotal/auth/creds/<name>.creds` | Output path |\n| `--signer` | off | Emit a stripped account-signing file instead |\n| `--force` | off | With `--signer`: overwrite an existing file |\n| `--allow-subscribe <a,b>` | profile default | Read-ACL override |\n| `--allow-publish <a,b>` | profile default | Post-ACL override |\n\nMints a NATS creds file for a space in **static** auth mode, scoped to a profile and (optionally)\nexplicit read/post ACLs. `--signer` emits an account-signing file for delegating minting to another\nhost. A per-user-auth space refuses `mint`: agents there join under a logged-in user\n([`login`](#login-logout) + [`actor grant`](#actor)), never via a handed-out creds file. See\n[Identity and auth](identity-and-auth.md).\n\n## login, logout\n\n```bash\ncotal login --idp <auth base URL> [--client-id <id>]\ncotal logout --idp <auth base URL>\n```\n\nSigns you in to a per-user-auth mesh's IdP (device code flow) and caches the session; run it\nonce per machine. It prints your IdP subject, the id the operator grants against. After a\nlogin, every command on that mesh works under your identity: each connect takes a fresh IdP\nproof, exchanges it locally for a short-lived bearer, and is authorized against the actor\nledger at connect time. `logout` revokes the IdP session and clears the cache. See\n[identity & auth](identity-and-auth.md).\n\n## actor\n\n```bash\ncotal actor grant <actor> --sub <IdP subject> [--scope a,b] [--allow-subscribe a,b] [--allow-publish a,b] [--role <r>] [--label <l>]\ncotal actor revoke <actor> (--sub <IdP subject> | --owner <u_\u2026>)\ncotal actor list\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | the folder's | Space whose ledger to manage |\n| `--sub <subject>` | \u2014 | The IdP subject (shown by `cotal login`) the actor belongs to |\n| `--owner <u_\u2026>` | \u2014 | The derived owner token (alternative to `--sub`) |\n| `--scope <a,b>` | `spawn,role:default` | Capability scope (`''` = none; `spawn` = may run agents, `role:<r>` = may delegate role r, `admin` = cross-agent control) |\n| `--allow-subscribe <a,b>` | `>` (all channels) | Channel read ACL; the user's envelope, their agents can never read beyond it |\n| `--allow-publish <a,b>` | `>` (all channels) | Channel post ACL; also the envelope for their agents' posting |\n| `--role <r>` | \u2014 | Role (scopes the task-queue consumer) |\n| `--label <l>` | \u2014 | Display label for `actor list` (never the IdP subject) |\n\nThe actor ledger is the single authorization source of a user-auth space: no row, no access.\nA bare `grant` is the **full** envelope (all channels, may spawn); the flags narrow it. A\nre-grant **replaces** the row, so to add a capability, re-grant with it added to the current\nscope (`cotal actor list` shows what a row holds). `revoke` denies the next exchange and the\nnext connect with no restart, and evicts the principal's live connections. Managed-agent rows\n(written by the spawn path) live in a disjoint row space this command never touches. See\n[identity & auth](identity-and-auth.md).\n\n## doctor\n\n```bash\ncotal doctor auth [--fix]\n```\n\nCredential-health diagnosis and repair for this folder's mesh: renders every managed\ncredential as healthy / near-expiry / expired and ends in `healthy` or the exact next\ncommand; `--fix` applies the repairs it can. The one surface every stale-credential error\npoints at.\n\n## join\n\n```bash\ncotal join --space <s> --name <n> [--role <r>] [--channel <c>]\ncotal join --link <url> | --token <t>\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and which credential |\n| `--name <n>` | \u2014 | Your presence name |\n| `--role <r>` | \u2014 | Your role |\n| `--channel <c>` | \u2014 | Channel to join |\n| `--kind <k>` | `agent` | Endpoint kind |\n| `--link <url>` | \u2014 | Join link (`cotal://\u2026`) |\n| `--token <t>` | \u2014 | Join token |\n| `--tls` | off | Connect over TLS |\n\nAn interactive presence: join a space under your own name and role, without launching an agent\nharness. A `--link` or `--token` supplies the where and the auth in one value. See\n[Spaces](spaces.md) and [Identity and auth](identity-and-auth.md).\n\n## Manifest deploys\n\nA `cotal.yaml` manifest declares a whole mesh (channels, personas, roles, and ACLs) in one file.\nThree commands consume it, plus a read-only validator:\n\n```bash\ncotal up -f cotal.yaml         # boot a fresh mesh from the manifest\ncotal spawn -f cotal.yaml      # deploy the manifest additively onto a running mesh\ncotal down -f cotal.yaml       # tear that deploy down (or --run <id> for one run)\ncotal topology view -f cotal.yaml   # validate + view the access graph, change nothing\n```\n\n`up -f` and `spawn -f` differ in target: `up -f` brings up a new broker and applies the manifest;\n`spawn -f` requires an already-reachable mesh and applies additively (ownership-scoped). On a\nuser-auth mesh, `spawn -f` deploys over your own login (the deployer view, gated on ledger scope\n`spawn`): the manifest's agents land under your owner, a manifest claiming another owner is\nrefused, and seeding new channels additionally needs scope `admin`. Both take\n`--dry-run` to print the plan without mutating anything. `topology` validates the manifest and\nrenders its channel / role / ACL graph. See [Define a team](define-a-team.md) and the\n[manifest reference](manifest.md).\n\n## ext\n\n```bash\ncotal ext add <npm-package>\ncotal ext remove <name>\ncotal ext list\n```\n\nOperator-installed extensions: `add` installs an npm package into a cotal-owned prefix and records\nevery registry provider it contributes. Commands appear in help, completion, and dispatch; runtime\nproviders are lazy-loaded by commands such as `supervise`; local process providers participate in\n`status` and selective `down`. `remove` and `list` manage them. The `@cotal-ai/web` dashboard is the\ncanonical command/process example. Installed packages and their location are described in\n[config](config.md).\n\nRemoving an extension that owns a running local process is refused with the mesh root and its\n`cotal down <component>` command; stop it first so uninstalling the package never strands a process\nwhose lifecycle provider is gone.\n\n## completion\n\n```bash\ncotal completion <bash|zsh|fish|powershell>   # print a stub to eval / source\ncotal completion install [shell]              # install it persistently\n```\n\nPrints or installs shell completion. Completion candidates come from each command's declared flags\nand, where useful, live mesh state (spaces, personas, managed agents) resolved offline.\n\n## feedback\n\n```bash\ncotal feedback \"<summary>\" [--type <t>] [--email <e>] [--details <text>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--type <t>` | \u2014 | `bug` \\| `idea` \\| `friction` \\| `praise` \\| `other` |\n| `--details <text>` | \u2014 | Longer free-form details |\n| `--severity <s>` | \u2014 | `low` \\| `medium` \\| `high` |\n| `--area <a>` | \u2014 | The part of Cotal this concerns |\n| `--email <e>` | git email | Contact email (required on the keyless public path) |\n| `--name <n>` | \u2014 | Your name (optional) |\n| `--url <url>` | keyed / public intake | Intake URL override |\n| `--key <k>` | `COTAL_FEEDBACK_KEY` | Feedback key |\n\nSends feedback to the Cotal developers. With a key (`--key` / `COTAL_FEEDBACK_KEY`) it routes to the\nkeyed beta intake; without one it goes to the public `cotal.ai` intake and requires a contact email\n(`--email` / `COTAL_FEEDBACK_EMAIL`, else your git email). Run a self-hosted intake with\n[`feedback-intake`](#server-daemons).\n\n## Server daemons\n\nTwo long-lived infra roles ship with the CLI. They are not part of everyday operation; the delivery\ndaemon comes up automatically with `cotal up --detach` in auth mode.\n\n```bash\ncotal deliver --space <s> [--server <url>] [--creds <file>]\ncotal auth-service --space <s> --server <url> [--port <n>]\ncotal feedback-intake --keys <keys.json> [--port <n>] [--creds <file>]\n```\n\n`auth-service` runs a user-auth space's identity plane (the NATS auth callout plus the\nloopback token exchange and JWKS); `cotal up --user-auth` starts and supervises it for you,\nso you run it directly only to recover one by hand.\n\n`deliver` runs the server-side Plane-3 delivery daemon: the durable backstop and membership/ACL\nauthority. It is auth-mode-only and single-instance (`--shard`/`--shards` accept only `N=1`);\n`--dev-mint` mints a scoped cred from the local signer for standalone dev. See the\n[delivery daemon](delivery-daemon.md). `feedback-intake` runs a self-hosted feedback server\n(requires `--keys` and a scoped `--creds`), announcing submissions into a space channel; flags\ninclude `--host`/`--port`, `--store`, `--space`/`--channel`, `--max-bytes`, and `--rate-limit`.\n\n## Plumbing\n\n`cotal __complete <words\u2026>` is the internal entry the shell-completion stubs call to emit candidates\nfor the current command line; you never run it directly. `cotal agent-bearer` is machine-facing\nplumbing on user-auth meshes: spawned agents exec it to print a fresh short-lived bearer from their\nspawn-time secret; you never run it directly either. (`cotal start` is a removed tombstone: it\nerrors and points you to `cotal spawn --detach`.)\n"
     },
     {
       "slug": "config",
       "title": "Configuration & environment",
       "kind": "Reference: describes the TypeScript reference implementation (the `cotal` CLI and connectors), not the wire contract.",
       "summary": "Three things configure a Cotal workstation: the config file (per-connector settings, notably which of your MCP servers get shared with spawned agents), a set of COTAL environment variables, and the\u2026",
-      "body": '# Configuration & environment\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI and connectors), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\nThree things configure a Cotal workstation: the **config file** (per-connector settings, notably\nwhich of your MCP servers get shared with spawned agents), a set of **`COTAL_*` environment\nvariables**, and the **on-disk layout** under a project\'s `.cotal/` and your machine\'s `~/.cotal`.\nNone of these are part of the wire contract; they configure the reference implementation only.\n\n## The config file\n\nThe cotal config file carries per-connector launch settings. It is layered from two locations,\nmost-specific-wins:\n\n| Layer | Path | Scope |\n|---|---|---|\n| Base | `$XDG_CONFIG_HOME/cotal/config.json` (else `~/.config/cotal/config.json`; `%APPDATA%\\Cotal\\config.json` on Windows) | Operator-level, every space |\n| Override | `<project-root>/.cotal/config.json` | Space-local |\n\nThey merge per connector and per server name: a server in the space-local file replaces the\nsame-named server in the operator-level file; connectors or servers present in only one side are\nkept. A missing file is empty (valid); malformed JSON or a non-object top level is a loud error.\n\nToday it carries one thing: which of your personal MCP servers a connector should **share** with the\nagents it spawns. By default a spawned agent gets none: the Claude connector launches with\n`--strict-mcp-config`, dropping every ambient MCP server (they are heavy and useless to a meshed\nteammate). This file is the explicit opt-in.\n\n```json\n{\n  "connectors": {\n    "claude": {\n      "mcpServers": {\n        "github": {\n          "command": "npx",\n          "args": ["-y", "@modelcontextprotocol/server-github"],\n          "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }\n        }\n      }\n    }\n  }\n}\n```\n\nEach server is written in the de-facto `.mcp.json` shape, so you can copy an entry straight out of\nyour own Claude / VS Code / Cursor config. Secrets ride as **`${VAR}` references** (also\n`${VAR:-default}`), resolved from your environment at launch and forwarded to the child **by name**\n(never as literals) so the file stays safe to keep in `~/.config` or a gitignored `.cotal/`. Only\n`command`, `args`, `env`, `url`, and `headers` are expanded; any other key passes through verbatim.\n\n**`--share-tools` interplay**. The per-spawn selection narrows what this config declares:\n\n| `--share-tools` | Result |\n|---|---|\n| (flag absent) | Every server declared for the connector |\n| `none` or empty | Nothing |\n| `a,b` | Only those named: each **must** be declared, or the spawn fails (no silent drop) |\n\nToday only the `claude` connector consumes shared MCP servers; OpenCode inherits config through its\nown merge layer and Hermes has no MCP. See [Connect Claude Code](connect-claude.md) for the full\nsharing model.\n\n## Environment variables\n\nThese are the operator-facing variables. Most of the connector-session ones (space, name, role, \u2026)\nare set **for you** by `cotal spawn` / the manager when they launch an agent; you set them by hand\nonly when you drive a connector session yourself (e.g. your own `claude` with the plugin) or a custom\nlauncher. Comma-separated lists are trimmed.\n\n| Variable | Consumed by | Meaning | Default |\n|---|---|---|---|\n| `COTAL_SPACE` | connector session | Space to join | `demo` (or the join link\'s) |\n| `COTAL_NAME` | connector session | Presence name / identity | required (or via `COTAL_AGENT_FILE` / `COTAL_LINK`) |\n| `COTAL_ROLE` | connector session | Role | agent file\'s `role:`, else none |\n| `COTAL_SERVERS` | connector session | Broker URL(s) | the default local broker (or the link\'s) |\n| `COTAL_CREDS` | connector session | Path to a NATS creds file (auth mode) | none (open mode) |\n| `COTAL_LINK` | connector session | `cotal://token@host/space` join link: supplies server, auth, space | none |\n| `COTAL_AGENT_FILE` | connector session | Path to a persona file: supplies name, role, kind, channels | none |\n| `COTAL_SUBSCRIBE` | connector session | Active channel read set | agent file / link, else `general` |\n| `COTAL_ALLOW_SUBSCRIBE` | connector session | Read ACL (channels the agent *may* read) | = `COTAL_SUBSCRIBE` |\n| `COTAL_ALLOW_PUBLISH` | connector session | Post ACL (channels the agent *may* post to) | deny (empty) |\n| `COTAL_MODEL` | connector session | Model label (display metadata) | agent file\'s `model:`, else none |\n| `COTAL_KIND` | connector session | Endpoint kind | `agent` |\n| `COTAL_TLS` | connector session | Connect over TLS (`1`) | off |\n| `COTAL_TOKEN` | connector session | Auth token (token / open modes) | none |\n| `COTAL_CAPABILITIES` | connector session | Control-plane capabilities (e.g. `spawn`) that gate manager tools | agent file\'s `capabilities:` |\n| `COTAL_QUIET` / `COTAL_MUTED` | connector session | Per-channel attention defaults (never-wake / drop-on-receive) | agent file\'s, else none |\n| `COTAL_CHANNEL` | Claude connector | Force channel wake-nudges on (`1`) / off; set to `1` by the Claude launcher | auto-detect |\n| `COTAL_TRANSCRIPT` | connector session | Mirror this session\'s transcript to `tr-<name>` (`1`) | off |\n| `COTAL_TRANSCRIPT_DEFAULT` | manager | Default transcript-mirror for managed spawns (`1`) | off |\n| `COTAL_DEFAULT_AGENT` | `cotal spawn` | Default connector type for a bare spawn | `claude` |\n| `COTAL_DEFAULT_PERSONA` | `cotal spawn` | Default persona for a bare spawn | `default` |\n| `COTAL_DETACH_KEY` | `cotal attach` | Detach escape key (`ctrl-<char>` / `^<char>`) | `ctrl-]` |\n| `COTAL_FEEDBACK_KEY` | `feedback`, connector | Beta feedback key \u2192 keyed intake | none (public intake) |\n| `COTAL_FEEDBACK_EMAIL` | `feedback`, connector | Contact email for the keyless public intake | your git email |\n| `COTAL_FEEDBACK_URL` | `feedback`, connector | Intake URL override (self-hosted) | keyed / public intake |\n| `COTAL_SKIP_ASSIST` | `setup` | Disable the interactive Claude handoff on a failed step (`1`; for CI) | off |\n| `COTAL_COMPLETE_DEBUG` | `completion` | Print completion-resolution errors to stderr | off |\n| `COTAL_SERVE_HEADLESS` | OpenCode runtime | Run the OpenCode server without a foreground TUI (`1`) | off |\n| `COTAL_HOME` | workspace | Override the machine-home dir (`~/.cotal`), mainly for test sandboxing | `~/.cotal` |\n\n> `--console-port` is a `cotal supervise` flag, not an environment variable; there is no\n> `COTAL_CONSOLE_PORT`.\n\n### Set by the launcher, not by you\n\nThese are wired into a spawned child\'s environment by the connector / launcher and read back inside\nthe session. They are not operator knobs; listed so you recognize them in a process listing.\n\n| Variable | Purpose |\n|---|---|\n| `COTAL_ID` | Stable agent id chosen by the launcher (static meshes) |\n| `COTAL_OWNER` / `COTAL_ACTOR` / `COTAL_SENTINEL_CREDS` / `COTAL_BEARER_CMD` | User-auth launch identity: the agent\'s principal, its sentinel creds path, and the exec-able bearer command; all four together, mutually exclusive with `COTAL_CREDS` |\n| `COTAL_CONTROL_SOCKET` / `COTAL_CONTROL_TOKEN` | The session\'s local control endpoint (path + token) the MCP server listens on and the lifecycle hooks connect to; token is env-only, never argv or logs |\n| `COTAL_BRIDGE_SOCKET` / `COTAL_TOOLS_FILE` / `COTAL_PARENT_PID` | Hermes sidecar plumbing (bridge socket, generated tool descriptors, launcher pid to watch) |\n| `OPENCODE_CONFIG_CONTENT` | Inline OpenCode config (the injected cotal plugin, highest merge layer) |\n| `OPENCODE_DB` / `OPENCODE_HOME` / `OPENCODE_PORT` / `OPENCODE_SERVER_URL` / `COTAL_OPENCODE_*` | OpenCode server plumbing (home, port, DB, server URL) |\n\nThe launcher forwards only a fixed OS allow-list (PATH, HOME, TERM, locale, XDG/Windows config dirs,\n\u2026) plus the named model-provider key and any `${VAR}` secrets a shared MCP server references, never\nyour whole environment, so unrelated secrets don\'t bleed into spawned agents. There are also a few\ninternal timing knobs (e.g. `COTAL_MEMBERSHIP_INTERVAL_MS`, `COTAL_DELIVERY_BROKER_GONE_MS`) that you\nshould not set in normal operation.\n\n## On-disk layout\n\n### Project: `.cotal/`\n\nA project\'s state lives in `.cotal/` at the mesh root (found by walking up from the cwd, like `.git`).\n**It is gitignored**; it holds secrets and machine-local process state.\n\n| Path | What it is |\n|---|---|\n| `auth/auth.json` | Space trust material: the data-account signing seed (secret; the system-account seed is stripped before writing) |\n| `auth/creds/<name>.creds` | Per-agent minted NATS credentials |\n| `auth/server.conf` | Generated nats-server config for this space |\n| `agents/<name>.md` | Persona / agent files ([Agent files](agent-files.md)) |\n| `manifests/<hash>.json` | Manifest-deploy ledger (records of `up -f` / `spawn -f` runs) |\n| `config.json` | Space-local connector config (the override layer above) |\n| `nats.pid` \xB7 `nats.log` | Background nats-server pid + log |\n| `manager.pid` \xB7 `manager.log` | Manager (supervisor) pid + log; `manager.delivery-aware` marks a delivery-aware build |\n| `delivery.pid` \xB7 `delivery.log` \xB7 `delivery.creds` | Delivery daemon pid, log, and scoped cred (auth mode) |\n| `web.pid` \xB7 `web.log` | Web dashboard pid + log |\n| `membership.json` \xB7 `membership-*.creds` | Membership feed state + its scoped creds |\n| `setup.log` | Last `cotal setup` run |\n\n### Machine: `~/.cotal`\n\nCross-project machine state, so a `cotal spawn` from any directory can find a running mesh. Location:\n`~/.cotal` on POSIX, `%LOCALAPPDATA%\\Cotal` on Windows; overridable with `COTAL_HOME`.\n\n| Path | What it is |\n|---|---|\n| `meshes/<space>.json` | Registry of running meshes: one file per broker `cotal up` started (server URL, root path, mode) |\n| `current-mesh` | Default space a bare `cotal spawn` joins (set by `cotal use`) |\n| `onboarded.json` | First-run marker (with `ONBOARD_VERSION`) that flips setup between first-run and status-card |\n| the Claude plugin marketplace | The installed `cotal-mesh` plugin assets |\n\n### Config dir: `$XDG_CONFIG_HOME/cotal`\n\nDistinct from `~/.cotal`. Location: `$XDG_CONFIG_HOME/cotal`, else `~/.config/cotal` on POSIX, or\n`%APPDATA%\\Cotal` on Windows.\n\n| Path | What it is |\n|---|---|\n| `config.json` | Operator-level connector config (the base layer above) |\n| `extensions/` | `cotal ext` install prefix: its own npm root (`node_modules`) plus an `extensions.json` display/completion cache |\n\nFor how `cotal setup` populates the machine state and the plugin, see\n[setup internals](setup-internals.md).\n'
+      "body": '# Configuration & environment\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI and connectors), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\nThree things configure a Cotal workstation: the **config file** (per-connector settings, notably\nwhich of your MCP servers get shared with spawned agents), a set of **`COTAL_*` environment\nvariables**, and the **on-disk layout** under a project\'s `.cotal/` and your machine\'s `~/.cotal`.\nNone of these are part of the wire contract; they configure the reference implementation only.\n\n## The config file\n\nThe cotal config file carries per-connector launch settings. It is layered from two locations,\nmost-specific-wins:\n\n| Layer | Path | Scope |\n|---|---|---|\n| Base | `$XDG_CONFIG_HOME/cotal/config.json` (else `~/.config/cotal/config.json`; `%APPDATA%\\Cotal\\config.json` on Windows) | Operator-level, every space |\n| Override | `<project-root>/.cotal/config.json` | Space-local |\n\nThey merge per connector and per server name: a server in the space-local file replaces the\nsame-named server in the operator-level file; connectors or servers present in only one side are\nkept. A missing file is empty (valid); malformed JSON or a non-object top level is a loud error.\n\nToday it carries one thing: which of your personal MCP servers a connector should **share** with the\nagents it spawns. By default a spawned agent gets none: the Claude connector launches with\n`--strict-mcp-config`, dropping every ambient MCP server (they are heavy and useless to a meshed\nteammate). This file is the explicit opt-in.\n\n```json\n{\n  "connectors": {\n    "claude": {\n      "mcpServers": {\n        "github": {\n          "command": "npx",\n          "args": ["-y", "@modelcontextprotocol/server-github"],\n          "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }\n        }\n      }\n    }\n  }\n}\n```\n\nEach server is written in the de-facto `.mcp.json` shape, so you can copy an entry straight out of\nyour own Claude / VS Code / Cursor config. Secrets ride as **`${VAR}` references** (also\n`${VAR:-default}`), resolved from your environment at launch and forwarded to the child **by name**\n(never as literals) so the file stays safe to keep in `~/.config` or a gitignored `.cotal/`. Only\n`command`, `args`, `env`, `url`, and `headers` are expanded; any other key passes through verbatim.\n\n**`--share-tools` interplay**. The per-spawn selection narrows what this config declares:\n\n| `--share-tools` | Result |\n|---|---|\n| (flag absent) | Every server declared for the connector |\n| `none` or empty | Nothing |\n| `a,b` | Only those named: each **must** be declared, or the spawn fails (no silent drop) |\n\nToday only the `claude` connector consumes shared MCP servers; OpenCode inherits config through its\nown merge layer and Hermes has no MCP. See [Connect Claude Code](connect-claude.md) for the full\nsharing model.\n\n## Environment variables\n\nThese are the operator-facing variables. Most of the connector-session ones (space, name, role, \u2026)\nare set **for you** by `cotal spawn` / the manager when they launch an agent; you set them by hand\nonly when you drive a connector session yourself (e.g. your own `claude` with the plugin) or a custom\nlauncher. Comma-separated lists are trimmed.\n\n| Variable | Consumed by | Meaning | Default |\n|---|---|---|---|\n| `COTAL_SPACE` | connector session | Space to join | `demo` (or the join link\'s) |\n| `COTAL_NAME` | connector session | Presence name / identity | required (or via `COTAL_AGENT_FILE` / `COTAL_LINK`) |\n| `COTAL_ROLE` | connector session | Role | agent file\'s `role:`, else none |\n| `COTAL_SERVERS` | connector session | Broker URL(s) | the default local broker (or the link\'s) |\n| `COTAL_CREDS` | connector session | Path to a NATS creds file (auth mode) | none (open mode) |\n| `COTAL_LINK` | connector session | `cotal://token@host/space` join link: supplies server, auth, space | none |\n| `COTAL_AGENT_FILE` | connector session | Path to a persona file: supplies name, role, kind, channels | none |\n| `COTAL_SUBSCRIBE` | connector session | Active channel read set | agent file / link, else `general` |\n| `COTAL_ALLOW_SUBSCRIBE` | connector session | Read ACL (channels the agent *may* read) | = `COTAL_SUBSCRIBE` |\n| `COTAL_ALLOW_PUBLISH` | connector session | Post ACL (channels the agent *may* post to) | deny (empty) |\n| `COTAL_MODEL` | connector session | Model label (display metadata) | agent file\'s `model:`, else none |\n| `COTAL_KIND` | connector session | Endpoint kind | `agent` |\n| `COTAL_TLS` | connector session | Connect over TLS (`1`) | off |\n| `COTAL_TOKEN` | connector session | Auth token (token / open modes) | none |\n| `COTAL_CAPABILITIES` | connector session | Control-plane capabilities (e.g. `spawn`) that gate manager tools | agent file\'s `capabilities:` |\n| `COTAL_QUIET` / `COTAL_MUTED` | connector session | Per-channel attention defaults (never-wake / drop-on-receive) | agent file\'s, else none |\n| `COTAL_CHANNEL` | Claude connector | Force channel wake-nudges on (`1`) / off; set to `1` by the Claude launcher | auto-detect |\n| `COTAL_TRANSCRIPT` | connector session | Mirror this session\'s transcript to `tr-<name>` (`1`) | off |\n| `COTAL_TRANSCRIPT_DEFAULT` | manager | Default transcript-mirror for managed spawns (`1`) | off |\n| `COTAL_DEFAULT_AGENT` | `cotal spawn` | Default connector type for a bare spawn | `claude` |\n| `COTAL_DEFAULT_PERSONA` | `cotal spawn` | Default persona for a bare spawn | `default` |\n| `COTAL_DETACH_KEY` | `cotal attach` | Detach escape key (`ctrl-<char>` / `^<char>`) | `ctrl-]` |\n| `COTAL_FEEDBACK_KEY` | `feedback`, connector | Beta feedback key \u2192 keyed intake | none (public intake) |\n| `COTAL_FEEDBACK_EMAIL` | `feedback`, connector | Contact email for the keyless public intake | your git email |\n| `COTAL_FEEDBACK_URL` | `feedback`, connector | Intake URL override (self-hosted) | keyed / public intake |\n| `COTAL_SKIP_ASSIST` | `setup` | Disable the interactive Claude handoff on a failed step (`1`; for CI) | off |\n| `COTAL_COMPLETE_DEBUG` | `completion` | Print completion-resolution errors to stderr | off |\n| `COTAL_SERVE_HEADLESS` | OpenCode runtime | Run the OpenCode server without a foreground TUI (`1`) | off |\n| `COTAL_HOME` | workspace | Override the machine-home dir (`~/.cotal`), mainly for test sandboxing | `~/.cotal` |\n\n> `--console-port` is a `cotal supervise` flag, not an environment variable; there is no\n> `COTAL_CONSOLE_PORT`.\n\n### Set by the launcher, not by you\n\nThese are wired into a spawned child\'s environment by the connector / launcher and read back inside\nthe session. They are not operator knobs; listed so you recognize them in a process listing.\n\n| Variable | Purpose |\n|---|---|\n| `COTAL_ID` | Stable agent id chosen by the launcher (static meshes) |\n| `COTAL_OWNER` / `COTAL_ACTOR` / `COTAL_SENTINEL_CREDS` / `COTAL_BEARER_CMD` | User-auth launch identity: the agent\'s principal, its sentinel creds path, and the exec-able bearer command; all four together, mutually exclusive with `COTAL_CREDS` |\n| `COTAL_CONTROL_SOCKET` / `COTAL_CONTROL_TOKEN` | The session\'s local control endpoint (path + token) the MCP server listens on and the lifecycle hooks connect to; token is env-only, never argv or logs |\n| `COTAL_BRIDGE_SOCKET` / `COTAL_TOOLS_FILE` / `COTAL_PARENT_PID` | Hermes sidecar plumbing (bridge socket, generated tool descriptors, launcher pid to watch) |\n| `OPENCODE_CONFIG_CONTENT` | Inline OpenCode config (the injected cotal plugin, highest merge layer) |\n| `OPENCODE_DB` / `OPENCODE_HOME` / `OPENCODE_PORT` / `OPENCODE_SERVER_URL` / `COTAL_OPENCODE_*` | OpenCode server plumbing (home, port, DB, server URL) |\n\nThe launcher forwards only a fixed OS allow-list (PATH, HOME, TERM, locale, XDG/Windows config dirs,\n\u2026) plus the named model-provider key and any `${VAR}` secrets a shared MCP server references, never\nyour whole environment, so unrelated secrets don\'t bleed into spawned agents. There are also a few\ninternal timing knobs (e.g. `COTAL_MEMBERSHIP_INTERVAL_MS`, `COTAL_DELIVERY_BROKER_GONE_MS`) that you\nshould not set in normal operation.\n\n## On-disk layout\n\n### Project: `.cotal/`\n\nA project\'s state lives in `.cotal/` at the mesh root (found by walking up from the cwd, like `.git`).\n**It is gitignored**; it holds secrets and machine-local process state.\n\n| Path | What it is |\n|---|---|\n| `auth/auth.json` | Space trust material: the data-account signing seed (secret; the system-account seed is stripped before writing) |\n| `auth/creds/<name>.creds` | Per-agent minted NATS credentials |\n| `auth/server.conf` | Generated nats-server config for this space |\n| `agents/<name>.md` | Persona / agent files ([Agent files](agent-files.md)) |\n| `manifests/<hash>.json` | Manifest-deploy ledger (records of `up -f` / `spawn -f` runs) |\n| `config.json` | Space-local connector config (the override layer above) |\n| `nats.pid` \xB7 `nats.log` | Background nats-server pid + log |\n| `manager.pid` \xB7 `manager.log` | Manager (supervisor) pid + log; `manager.delivery-aware` marks a delivery-aware build |\n| `delivery.pid` \xB7 `delivery.log` \xB7 `delivery.creds` | Delivery daemon pid, log, and scoped cred (auth mode) |\n| `web.pid` \xB7 `web.log` | Web dashboard pid + log |\n| `membership.json` \xB7 `membership-*.creds` | Membership feed state + its scoped creds |\n| `setup.log` | Last `cotal setup` run |\n\n### Machine: `~/.cotal`\n\nCross-project machine state, so a `cotal spawn` from any directory can find a running mesh. Location:\n`~/.cotal` on POSIX, `%LOCALAPPDATA%\\Cotal` on Windows; overridable with `COTAL_HOME`.\n\n| Path | What it is |\n|---|---|\n| `meshes/<space>.json` | Registry of running meshes: one file per broker `cotal up` started (server URL, root path, mode) |\n| `current-mesh` | Default space a bare `cotal spawn` joins (set by `cotal use`) |\n| `onboarded.json` | First-run marker (with `ONBOARD_VERSION`) that flips setup between first-run and status-card |\n| the Claude plugin marketplace | The installed `cotal-mesh` plugin assets |\n\n### Config dir: `$XDG_CONFIG_HOME/cotal`\n\nDistinct from `~/.cotal`. Location: `$XDG_CONFIG_HOME/cotal`, else `~/.config/cotal` on POSIX, or\n`%APPDATA%\\Cotal` on Windows.\n\n| Path | What it is |\n|---|---|\n| `config.json` | Operator-level connector config (the base layer above) |\n| `extensions/` | `cotal ext` install prefix: its own npm root (`node_modules`) plus an `extensions.json` provider/command-display cache |\n\nFor how `cotal setup` populates the machine state and the plugin, see\n[setup internals](setup-internals.md).\n'
     },
     {
       "slug": "connect-claude",
@@ -42349,14 +42378,14 @@ var DOCS_BUNDLE = {
       "title": "Glossary",
       "kind": "Reference (informative)",
       "summary": "One-line definitions of the terms used across these docs and the spec.",
-      "body": "# Glossary\n\n> **Reference** (informative) \xB7 **For:** everyone\n\nOne-line definitions of the terms used across these docs and the spec. The base terminology is\n[SPEC \xA71](../SPEC.md#1-scope-and-terminology); each entry links to its home.\n\n- **Agent file / persona**, a `.cotal/agents/<name>.md` file: AgentCard-shaped identity and\n  channel grants in the frontmatter, with the Markdown body as the agent's persona (appended\n  system prompt). [agent-files.md](agent-files.md)\n\n- **Agent node**: an instance whose `kind` is `agent`, as opposed to a plain `endpoint` such as\n  an observer or dashboard. [SPEC \xA71](../SPEC.md#1-scope-and-terminology)\n\n- **Anycast**: a delivery mode addressed to a service **role**, delivered to one of its\n  consumers (load-balanced). [SPEC \xA74](../SPEC.md#4-delivery-modes)\n\n- **Attention**, an advisory per-instance receive preference in presence: a global mode\n  (`open` / `dnd` / `focus`) and per-channel overrides (`quiet` / `muted`). It shapes what wakes\n  an agent, not what the broker delivers or authorizes. [SPEC \xA76](../SPEC.md#6-presence-and-discovery)\n\n- **Broker**: the message router for a space; v0 assumes a single trusted broker.\n  [SPEC \xA71](../SPEC.md#1-scope-and-terminology)\n\n- **Channel**: a named, dotted, hierarchical multicast topic within a space.\n  [SPEC \xA77](../SPEC.md#7-channels)\n\n- **Channel registry**: the per-space store of channel config (`replay`, `replayWindow`,\n  `deliveryClass`, `description`, `instructions`), keyed by channel name.\n  [SPEC \xA77](../SPEC.md#7-channels)\n\n- **Connector**: an adapter that bridges an agent harness (Claude Code, OpenCode, Hermes, \u2026) to\n  the mesh, exposing the `cotal_*` tools. [connect-claude.md](connect-claude.md)\n\n- **Control plane**: the request/reply layer on `ctl` subjects plus the infra roles behind it\n  (the manager and the delivery daemon) that provision and supervise a mesh.\n  [architecture.md](architecture.md)\n\n- **Delivery class (`live` / `durable`)**, a channel's per-channel delivery guarantee: `live`\n  is at-most-once; `durable` adds a per-member backstop (at-least-once within retention). Distinct\n  from delivery *mode*. [SPEC \xA74](../SPEC.md#4-delivery-modes), [channels-and-permissions.md](channels-and-permissions.md)\n\n- **Delivery daemon (Plane-3)**, the server-side component providing the durable backstop:\n  fan-out writer, trusted reader, and membership registry. [delivery-daemon.md](delivery-daemon.md)\n\n- **Delivery modes**, the three addressing axes: multicast (channel), unicast (instance), and\n  anycast (role). Exactly one per message. [SPEC \xA74](../SPEC.md#4-delivery-modes)\n\n- **Direct message / unicast**: a message addressed to one named instance's inbox.\n  [SPEC \xA74](../SPEC.md#4-delivery-modes)\n\n- **Durable backstop**: the per-subscriber store that retains `durable`-channel posts (and\n  authorized `live`-channel `@mention` copies) until the member has seen them.\n  [SPEC \xA74](../SPEC.md#4-delivery-modes), [delivery-daemon.md](delivery-daemon.md)\n\n- **Endpoint**: a connected participant, identified by a stable instance id; the general term\n  for any instance, agent or not. [SPEC \xA71](../SPEC.md#1-scope-and-terminology)\n\n- **History / replay**: retained channel messages backfilled to a joiner when a channel's\n  `replay` is on, bounded to the reader's ACL and optionally to `replayWindow`.\n  [SPEC \xA77](../SPEC.md#7-channels)\n\n- **Instance (id)**: a connected participant; its **id** is its principal (below), used\n  identically as sender, presence key, and durable name. [SPEC \xA72](../SPEC.md#2-identity)\n\n- **Join link**: a `cotal://` / `cotals://` URL encoding broker host, space, optional credential,\n  and optional channels, the onboarding half of the contract.\n  [SPEC \xA710](../SPEC.md#10-connection-and-onboarding)\n\n- **Manager**, the agent supervisor and provisioner host: spawns and manages agent nodes over a\n  pluggable runtime, and pre-creates the durables and membership records agents can't create\n  themselves. [run-a-mesh.md](run-a-mesh.md)\n\n- **Manifest**, `cotal.yaml` (`kind: Mesh`): the declarative, channel-centric description of a\n  team's channels, agents, and access, launched with one command. [manifest.md](manifest.md)\n\n- **Mention**: a lowercased peer name in a message's `mentions`; a wake hint that, on a `live`\n  channel, also routes a durable copy to each mentioned target authorized to read the channel.\n  [SPEC \xA74](../SPEC.md#4-delivery-modes), [\xA75](../SPEC.md#5-envelopes)\n\n- **Mesh**, a running Cotal deployment: a broker, a space, and the peers coordinating in it.\n  [what-is-cotal.md](what-is-cotal.md)\n\n- **Multicast**: a delivery mode delivered to every subscriber of a channel.\n  [SPEC \xA74](../SPEC.md#4-delivery-modes)\n\n- **Observer**: a read-only profile that reads chat, history, presence, and the channel\n  registry, but cannot publish and cannot see DMs. [SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization)\n\n- **Principal (`owner.actor`)**: an instance's wire identity, two routing tokens: the\n  **owner** (the account the agent acts on behalf of; a derived `u_\u2026` token under per-user\n  auth, the literal `local` in open mode) and the **actor** (the agent's handle under that\n  owner). The connection's nkey is only the transport credential.\n  [SPEC \xA72](../SPEC.md#2-identity), [identity & auth](identity-and-auth.md)\n\n- **Presence**, the per-space directory keyed by instance id: each peer's card, status,\n  activity, attention, and heartbeat timestamp. [SPEC \xA76](../SPEC.md#6-presence-and-discovery)\n\n- **Profile (`agent` / `observer` / `admin`)**: a default-deny credential class defining what\n  subjects, streams, durables, and KV keys a credential may touch. [SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization),\n  [Appendix B](../SPEC.md#appendix-b-profile-acls)\n\n- **Provisioner**: the privileged, signing-capable role that mints scoped credentials and writes\n  the durables and membership records agents cannot write themselves.\n  [SPEC \xA77](../SPEC.md#7-channels), [Appendix B](../SPEC.md#appendix-b-profile-acls)\n\n- **Role / service**: a named anycast target a group of agents share; a message to the role\n  reaches one of them. [SPEC \xA71](../SPEC.md#1-scope-and-terminology), [\xA74](../SPEC.md#4-delivery-modes)\n\n- **Runtime (`pty` / `tmux` / `cmux`)**, how the manager runs each agent process: the built-in\n  pty, or tmux/cmux via extensions. [run-a-mesh.md](run-a-mesh.md)\n\n- **Space**: an isolated coordination context and tenant boundary; one space maps to one NATS\n  account. [SPEC \xA71](../SPEC.md#1-scope-and-terminology), [spaces.md](spaces.md)\n\n- **Spawn capability**, the `spawn` control-plane capability in an agent file: grants publish to\n  the privileged control subject so the agent may start or despawn peers. [agent-files.md](agent-files.md)\n\n- **Trusted reader**: the privileged component that reads the mixed durable backstop on an\n  agent's behalf and re-authorizes each entry (current ACL and membership) before delivering it.\n  [delivery-daemon.md](delivery-daemon.md), [SPEC \xA78](../SPEC.md#8-nats--jetstream-binding)\n"
+      "body": "# Glossary\n\n> **Reference** (informative) \xB7 **For:** everyone\n\nOne-line definitions of the terms used across these docs and the spec. The base terminology is\n[SPEC \xA71](../SPEC.md#1-scope-and-terminology); each entry links to its home.\n\n- **Agent file / persona**, a `.cotal/agents/<name>.md` file: AgentCard-shaped identity and\n  channel grants in the frontmatter, with the Markdown body as the agent's persona (appended\n  system prompt). [agent-files.md](agent-files.md)\n\n- **Agent node**: an instance whose `kind` is `agent`, as opposed to a plain `endpoint` such as\n  an observer or dashboard. [SPEC \xA71](../SPEC.md#1-scope-and-terminology)\n\n- **Anycast**: a delivery mode addressed to a service **role**, delivered to one of its\n  consumers (load-balanced). [SPEC \xA74](../SPEC.md#4-delivery-modes)\n\n- **Attention**, an advisory per-instance receive preference in presence: a global mode\n  (`open` / `dnd` / `focus`) and per-channel overrides (`quiet` / `muted`). It shapes what wakes\n  an agent, not what the broker delivers or authorizes. [SPEC \xA76](../SPEC.md#6-presence-and-discovery)\n\n- **Broker**: the message router for a space; v0 assumes a single trusted broker.\n  [SPEC \xA71](../SPEC.md#1-scope-and-terminology)\n\n- **Channel**: a named, dotted, hierarchical multicast topic within a space.\n  [SPEC \xA77](../SPEC.md#7-channels)\n\n- **Channel registry**: the per-space store of channel config (`replay`, `replayWindow`,\n  `deliveryClass`, `description`, `instructions`), keyed by channel name.\n  [SPEC \xA77](../SPEC.md#7-channels)\n\n- **Connector**: an adapter that bridges an agent harness (Claude Code, OpenCode, Hermes, \u2026) to\n  the mesh, exposing the `cotal_*` tools. [connect-claude.md](connect-claude.md)\n\n- **Control plane**: the request/reply layer on `ctl` subjects plus the infra roles behind it\n  (the manager and the delivery daemon) that provision and supervise a mesh.\n  [architecture.md](architecture.md)\n\n- **Delivery class (`live` / `durable`)**, a channel's per-channel delivery guarantee: `live`\n  is at-most-once; `durable` adds a per-member backstop (at-least-once within retention). Distinct\n  from delivery *mode*. [SPEC \xA74](../SPEC.md#4-delivery-modes), [channels-and-permissions.md](channels-and-permissions.md)\n\n- **Delivery daemon (Plane-3)**, the server-side component providing the durable backstop:\n  fan-out writer, trusted reader, and membership registry. [delivery-daemon.md](delivery-daemon.md)\n\n- **Delivery modes**, the three addressing axes: multicast (channel), unicast (instance), and\n  anycast (role). Exactly one per message. [SPEC \xA74](../SPEC.md#4-delivery-modes)\n\n- **Direct message / unicast**: a message addressed to one named instance's inbox.\n  [SPEC \xA74](../SPEC.md#4-delivery-modes)\n\n- **Durable backstop**: the per-subscriber store that retains `durable`-channel posts (and\n  authorized `live`-channel `@mention` copies) until the member has seen them.\n  [SPEC \xA74](../SPEC.md#4-delivery-modes), [delivery-daemon.md](delivery-daemon.md)\n\n- **Endpoint**: a connected participant, identified by a stable instance id; the general term\n  for any instance, agent or not. [SPEC \xA71](../SPEC.md#1-scope-and-terminology)\n\n- **History / replay**: retained channel messages backfilled to a joiner when a channel's\n  `replay` is on, bounded to the reader's ACL and optionally to `replayWindow`.\n  [SPEC \xA77](../SPEC.md#7-channels)\n\n- **Instance (id)**: a connected participant; its **id** is its principal (below), used\n  identically as sender, presence key, and durable name. [SPEC \xA72](../SPEC.md#2-identity)\n\n- **Join link**: a `cotal://` / `cotals://` URL encoding broker host, space, optional credential,\n  and optional channels, the onboarding half of the contract.\n  [SPEC \xA710](../SPEC.md#10-connection-and-onboarding)\n\n- **Manager**, the agent supervisor and provisioner host: spawns and manages agent nodes over a\n  pluggable runtime, and pre-creates the durables and membership records agents can't create\n  themselves. [run-a-mesh.md](run-a-mesh.md)\n\n- **Manifest**, `cotal.yaml` (`kind: Mesh`): the declarative, channel-centric description of a\n  team's channels, agents, and access, launched with one command. [manifest.md](manifest.md)\n\n- **Mention**: a lowercased peer name in a message's `mentions`; a wake hint that, on a `live`\n  channel, also routes a durable copy to each mentioned target authorized to read the channel.\n  [SPEC \xA74](../SPEC.md#4-delivery-modes), [\xA75](../SPEC.md#5-envelopes)\n\n- **Mesh**, a running Cotal deployment: a broker, a space, and the peers coordinating in it.\n  [what-is-cotal.md](what-is-cotal.md)\n\n- **Multicast**: a delivery mode delivered to every subscriber of a channel.\n  [SPEC \xA74](../SPEC.md#4-delivery-modes)\n\n- **Observer**: a read-only profile that reads chat, history, presence, and the channel\n  registry, but cannot publish and cannot see DMs. [SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization)\n\n- **Principal (`owner.actor`)**: an instance's wire identity, two routing tokens: the\n  **owner** (the account the agent acts on behalf of; a derived `u_\u2026` token under per-user\n  auth, the literal `local` in open mode) and the **actor** (the agent's handle under that\n  owner). The connection's nkey is only the transport credential.\n  [SPEC \xA72](../SPEC.md#2-identity), [identity & auth](identity-and-auth.md)\n\n- **Presence**, the per-space directory keyed by instance id: each peer's card, status,\n  activity, attention, and heartbeat timestamp. [SPEC \xA76](../SPEC.md#6-presence-and-discovery)\n\n- **Profile (`agent` / `observer` / `admin`)**: a default-deny credential class defining what\n  subjects, streams, durables, and KV keys a credential may touch. [SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization),\n  [Appendix B](../SPEC.md#appendix-b-profile-acls)\n\n- **Provisioner**: the privileged, signing-capable role that mints scoped credentials and writes\n  the durables and membership records agents cannot write themselves.\n  [SPEC \xA77](../SPEC.md#7-channels), [Appendix B](../SPEC.md#appendix-b-profile-acls)\n\n- **Role / service**: a named anycast target a group of agents share; a message to the role\n  reaches one of them. [SPEC \xA71](../SPEC.md#1-scope-and-terminology), [\xA74](../SPEC.md#4-delivery-modes)\n\n- **Runtime (`pty` / `tmux` / `cmux` / `orca`)**, how the manager runs each agent process: the\n  built-in pty, or a native terminal surface via an extension. [run-a-mesh.md](run-a-mesh.md)\n\n- **Space**: an isolated coordination context and tenant boundary; one space maps to one NATS\n  account. [SPEC \xA71](../SPEC.md#1-scope-and-terminology), [spaces.md](spaces.md)\n\n- **Spawn capability**, the `spawn` control-plane capability in an agent file: grants publish to\n  the privileged control subject so the agent may start or despawn peers. [agent-files.md](agent-files.md)\n\n- **Trusted reader**: the privileged component that reads the mixed durable backstop on an\n  agent's behalf and re-authorizes each entry (current ACL and membership) before delivering it.\n  [delivery-daemon.md](delivery-daemon.md), [SPEC \xA78](../SPEC.md#8-nats--jetstream-binding)\n"
     },
     {
       "slug": "manifest",
       "title": "Mesh manifest (`cotal.yaml`)",
       "kind": "Reference: every field of the mesh manifest.",
       "summary": "A manifest (cotal.yaml, kind: Mesh) describes a whole team (its channels, its agents, and who may read and post where) in one file.",
-      "body": "# Mesh manifest (`cotal.yaml`)\n\n> **Reference**: every field of the mesh manifest. \xB7 **For:** operators \xB7 **Walkthrough:** [Define a team](define-a-team.md) \xB7 **ACL semantics:** [SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization)\n\nA manifest (`cotal.yaml`, `kind: Mesh`) describes a whole team (its channels, its agents,\nand who may read and post where) in one file. It is **channel-centric**: you list the\nchannels, and under each one name the agents that may read and post; Cotal inverts that\ninto one least-privilege credential per agent. The manifest is a convenience over the CLI;\nit adds no wire concepts. Today it is **single-space** (one `space:` per file).\n\nThe lifecycle (`cotal topology view -f` / `up -f` / `spawn -f` / `down -f`), ownership,\nand teardown behavior are in the guide: [Define a team](define-a-team.md).\n\n## Top level\n\n| Key | Required | Meaning |\n|---|---|---|\n| `apiVersion` | yes | Must be `cotal/v1`. |\n| `kind` | yes | Must be `Mesh`. |\n| `space` | yes | The space name (one per file; `spaces:` is not supported in v1). A space's auth is bound to one root; to run a non-default space in a checkout that already ran `cotal up` (which sets up `main`), use a fresh directory. |\n| `broker` | no | `servers` (comma-separated broker URLs: this sets the address/port; default `nats://127.0.0.1:4222`; **no embedded creds**), `host` (bind interface only, no scheme; does *not* set the port), `auth` (the auth mode: unset/`true`/`\"static\"` = per-agent JWT creds, the default; `false` = an open dev mesh; `\"user\"` = per-user auth, where people `cotal login` and every connect is authorized against the actor ledger; pair with `idp`), `idp` (with `auth: \"user\"`: the IdP auth base URL to pin on first enable). The port comes from `servers`/`--server`, never `host`/`--host`. |\n| `runtime` | no | How the manager runs each agent: `pty` (default) \xB7 `tmux` \xB7 `cmux`. |\n| `agent` | no | Default harness (`claude` / `opencode` / `hermes`) for agents that don't set their own. There is **no silent default**; an agent needs this or its own `agent:`. |\n| `personaPermissions` | no | `reject` (default): the manifest is the whole truth. `include`: a persona's own channel grants are inherited for channels the manifest doesn't declare. |\n| `defaults` | no | Channel defaults applied unless a channel overrides: `replay`, `replayWindow`, `deliveryClass` (`live` / `durable`). Semantics in [SPEC \xA77](../SPEC.md#7-channels). |\n| `agents` | no | name \u2192 persona (a channels-first manifest can seed rooms now and add agents later). |\n| `channels` | yes | name \u2192 channel (below). |\n\nUnknown keys are rejected (no silent ignore), and every error is reported with its file and line.\n\n## `agents:` (three forms)\n\n```yaml\nagents:\n  planner: ./agents/planner.md          # 1) bare path: reuse a persona file as-is\n  builder:                              # 2) a persona file + overrides (manifest wins)\n    persona: ./agents/builder.md\n    model: sonnet\n    role: implementer\n    instructions: Prefer the smallest change that works.\n  lead:                                 # 3) inline (no file): needs at least model or instructions\n    model: opus\n    role: lead\n    capabilities: [spawn]               # may spawn helpers\n    instructions: Coordinate the team.\n```\n\nPer-agent keys: `persona`, `agent` (harness override), `model`, `variant`, `role`,\n`description`, `instructions`, `capabilities` (`spawn`,\n[what it grants](identity-and-auth.md); on a per-user-auth mesh also `role:<r>`, so the\nagent may delegate that role when spawning; `admin` is never accepted from a manifest),\n`personaPermissions` (override the top-level policy). Model strings and variants pass to\nthe harness as-is: for Claude use the short form (`opus`, `sonnet`) or the full id; for\nOpenCode use `provider/model` plus an optional variant (`cotal models --agent opencode`\nlists both). Persona file format: [agent files](agent-files.md).\n\n## `channels:` (the three access verbs)\n\nA channel carries its registry card (`description`, `instructions`, `replay`, \u2026;\n[SPEC \xA77](../SPEC.md#7-channels)) plus three lists of agent names, the same verbs Cotal\nuses everywhere ([channels & permissions](channels-and-permissions.md)):\n\n| Verb | ACL | Meaning |\n|---|---|---|\n| `subscribe` | \u2014 | Auto-listen at boot. A subscriber is implicitly allowed to read. |\n| `allowSubscribe` | **read** | May read the channel. Omitted \u21D2 defaults to `subscribe`. Must be a superset of `subscribe`. |\n| `allowPublish` | **post** | May post. **Default-deny**: an empty or omitted list means nobody posts. |\n\nA read-only channel (no agent posts, e.g. an operator writes the record by hand with\n`cotal send`, which is a CLI action outside agent ACLs):\n\n```yaml\nchannels:\n  decisions:\n    description: The durable record of what we decided.\n    subscribe:    [lead]\n    allowPublish: []                    # read-only for agents\n```\n\nEvery name under a channel must be declared in `agents:`. Channel names must be concrete\n(no wildcards in v1).\n\n## How access is resolved\n\nYou declare membership per channel; Cotal inverts it into each agent's minted creds:\n\n- **Read** comes from `allowSubscribe` (or `subscribe` when `allowSubscribe` is omitted).\n- **Post** comes from `allowPublish`, and is default-deny: an agent you don't list cannot\n  post, even to a channel it reads.\n- `subscribe` only sets what an agent *auto-listens to* at boot; it never widens read.\n\nWith `personaPermissions: reject` (the default) the manifest is the complete picture; a\npersona file's own channel grants are ignored, so the file you read is exactly what each\nagent can do. Set `include` (top level or per agent) to *also* inherit a persona's own\ngrants for channels the manifest doesn't mention. `cotal topology view -f` always prints\nthe resolved graph, inherited scopes included.\n\n---\n\nFor implementers: the channel-centric \u2192 per-agent inversion lives in\n[`resolve.ts`](../implementations/cli/src/lib/manifest/resolve.ts); the `spawn -f`\nclassification and teardown in\n[`spawn-plan.ts`](../implementations/cli/src/lib/manifest/spawn-plan.ts) and\n[`down-manifest.ts`](../implementations/cli/src/commands/down-manifest.ts).\n"
+      "body": "# Mesh manifest (`cotal.yaml`)\n\n> **Reference**: every field of the mesh manifest. \xB7 **For:** operators \xB7 **Walkthrough:** [Define a team](define-a-team.md) \xB7 **ACL semantics:** [SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization)\n\nA manifest (`cotal.yaml`, `kind: Mesh`) describes a whole team (its channels, its agents,\nand who may read and post where) in one file. It is **channel-centric**: you list the\nchannels, and under each one name the agents that may read and post; Cotal inverts that\ninto one least-privilege credential per agent. The manifest is a convenience over the CLI;\nit adds no wire concepts. Today it is **single-space** (one `space:` per file).\n\nThe lifecycle (`cotal topology view -f` / `up -f` / `spawn -f` / `down -f`), ownership,\nand teardown behavior are in the guide: [Define a team](define-a-team.md).\n\n## Top level\n\n| Key | Required | Meaning |\n|---|---|---|\n| `apiVersion` | yes | Must be `cotal/v1`. |\n| `kind` | yes | Must be `Mesh`. |\n| `space` | yes | The space name (one per file; `spaces:` is not supported in v1). A space's auth is bound to one root; to run a non-default space in a checkout that already ran `cotal up` (which sets up `main`), use a fresh directory. |\n| `broker` | no | `servers` (comma-separated broker URLs: this sets the address/port; default `nats://127.0.0.1:4222`; **no embedded creds**), `host` (bind interface only, no scheme; does *not* set the port), `auth` (the auth mode: unset/`true`/`\"static\"` = per-agent JWT creds, the default; `false` = an open dev mesh; `\"user\"` = per-user auth, where people `cotal login` and every connect is authorized against the actor ledger; pair with `idp`), `idp` (with `auth: \"user\"`: the IdP auth base URL to pin on first enable). The port comes from `servers`/`--server`, never `host`/`--host`. |\n| `runtime` | no | Registered manager runtime name. `pty` is built in; optional providers such as `tmux`, `cmux`, and `orca` are installed with `cotal ext add`. |\n| `agent` | no | Default harness (`claude` / `opencode` / `hermes`) for agents that don't set their own. There is **no silent default**; an agent needs this or its own `agent:`. |\n| `personaPermissions` | no | `reject` (default): the manifest is the whole truth. `include`: a persona's own channel grants are inherited for channels the manifest doesn't declare. |\n| `defaults` | no | Channel defaults applied unless a channel overrides: `replay`, `replayWindow`, `deliveryClass` (`live` / `durable`). Semantics in [SPEC \xA77](../SPEC.md#7-channels). |\n| `agents` | no | name \u2192 persona (a channels-first manifest can seed rooms now and add agents later). |\n| `channels` | yes | name \u2192 channel (below). |\n\nUnknown keys are rejected (no silent ignore), and every error is reported with its file and line.\n\n## `agents:` (three forms)\n\n```yaml\nagents:\n  planner: ./agents/planner.md          # 1) bare path: reuse a persona file as-is\n  builder:                              # 2) a persona file + overrides (manifest wins)\n    persona: ./agents/builder.md\n    model: sonnet\n    role: implementer\n    instructions: Prefer the smallest change that works.\n  lead:                                 # 3) inline (no file): needs at least model or instructions\n    model: opus\n    role: lead\n    capabilities: [spawn]               # may spawn helpers\n    instructions: Coordinate the team.\n```\n\nPer-agent keys: `persona`, `agent` (harness override), `model`, `variant`, `role`,\n`description`, `instructions`, `capabilities` (`spawn`,\n[what it grants](identity-and-auth.md); on a per-user-auth mesh also `role:<r>`, so the\nagent may delegate that role when spawning; `admin` is never accepted from a manifest),\n`personaPermissions` (override the top-level policy). Model strings and variants pass to\nthe harness as-is: for Claude use the short form (`opus`, `sonnet`) or the full id; for\nOpenCode use `provider/model` plus an optional variant (`cotal models --agent opencode`\nlists both). Persona file format: [agent files](agent-files.md).\n\n## `channels:` (the three access verbs)\n\nA channel carries its registry card (`description`, `instructions`, `replay`, \u2026;\n[SPEC \xA77](../SPEC.md#7-channels)) plus three lists of agent names, the same verbs Cotal\nuses everywhere ([channels & permissions](channels-and-permissions.md)):\n\n| Verb | ACL | Meaning |\n|---|---|---|\n| `subscribe` | \u2014 | Auto-listen at boot. A subscriber is implicitly allowed to read. |\n| `allowSubscribe` | **read** | May read the channel. Omitted \u21D2 defaults to `subscribe`. Must be a superset of `subscribe`. |\n| `allowPublish` | **post** | May post. **Default-deny**: an empty or omitted list means nobody posts. |\n\nA read-only channel (no agent posts, e.g. an operator writes the record by hand with\n`cotal send`, which is a CLI action outside agent ACLs):\n\n```yaml\nchannels:\n  decisions:\n    description: The durable record of what we decided.\n    subscribe:    [lead]\n    allowPublish: []                    # read-only for agents\n```\n\nEvery name under a channel must be declared in `agents:`. Channel names must be concrete\n(no wildcards in v1).\n\n## How access is resolved\n\nYou declare membership per channel; Cotal inverts it into each agent's minted creds:\n\n- **Read** comes from `allowSubscribe` (or `subscribe` when `allowSubscribe` is omitted).\n- **Post** comes from `allowPublish`, and is default-deny: an agent you don't list cannot\n  post, even to a channel it reads.\n- `subscribe` only sets what an agent *auto-listens to* at boot; it never widens read.\n\nWith `personaPermissions: reject` (the default) the manifest is the complete picture; a\npersona file's own channel grants are ignored, so the file you read is exactly what each\nagent can do. Set `include` (top level or per agent) to *also* inherit a persona's own\ngrants for channels the manifest doesn't mention. `cotal topology view -f` always prints\nthe resolved graph, inherited scopes included.\n\n---\n\nFor implementers: the channel-centric \u2192 per-agent inversion lives in\n[`resolve.ts`](../implementations/cli/src/lib/manifest/resolve.ts); the `spawn -f`\nclassification and teardown in\n[`spawn-plan.ts`](../implementations/cli/src/lib/manifest/spawn-plan.ts) and\n[`down-manifest.ts`](../implementations/cli/src/commands/down-manifest.ts).\n"
     },
     {
       "slug": "mesh-view",
@@ -42377,7 +42406,7 @@ var DOCS_BUNDLE = {
       "title": "Release and publish",
       "kind": "Project (non-normative maintainer notes)",
       "summary": "Cotal uses Changesets to version and publish the workspace packages under packages/, extensions/, and implementations/ to npm.",
-      "body": "# Release and publish\n\n> **Project** (non-normative maintainer notes) \xB7 **For:** maintainers shipping Cotal\n\nCotal uses [Changesets](https://github.com/changesets/changesets) to version and publish the\nworkspace packages under `packages/*`, `extensions/*`, and `implementations/*` to npm.\n`examples/**` is ignored, since it is not published.\n\n## One-time npm setup: trusted publishing (OIDC)\n\nTrusted publishing replaces the long-lived `NPM_TOKEN` secret with short-lived OIDC tokens\nissued by GitHub Actions. Each published package must be configured once on npmjs.com.\n\nFor **every** published package (`@cotal-ai/core`, `@cotal-ai/cli`, `@cotal-ai/manager`,\n`@cotal-ai/delivery`, `@cotal-ai/connector-core`, `@cotal-ai/connector-claude-code`,\n`@cotal-ai/connector-opencode`, `@cotal-ai/connector-hermes`, `@cotal-ai/cmux`, and the\n`cotal-ai` binary):\n\n1. Go to `https://www.npmjs.com/package/<name>/access` (e.g.\n   `https://www.npmjs.com/package/@cotal-ai/core/access`).\n2. Scroll to **Trusted publishing** \u2192 **Add a trusted publisher**.\n3. Pick **GitHub Actions**.\n4. Fill in:\n   - **Organization or user:** the GitHub owner (your org or user).\n   - **Repository:** `SWARL` (or whatever this repo is called).\n   - **Workflow filename:** `changesets.yml`.\n   - **Environment name:** leave blank.\n5. Save. Repeat for every package.\n\n> The first time, you may need to publish a version manually (with a classic token) so the\n> package exists on npm. After that, OIDC takes over.\n\n## Day-to-day flow\n\n1. Open a PR that changes code in a publishable package.\n2. Add a changeset describing the change:\n\n   ```bash\n   pnpm changeset\n   ```\n\n   Pick the affected packages plus the semver bump (patch / minor / major), and write a\n   one-line summary. Commit the generated `.changeset/<name>.md` file alongside your code\n   change.\n3. Merge to `main`.\n4. The `Changesets` workflow runs:\n   - If there are pending changesets, it opens (or updates) a PR titled `chore(release):\n     version packages` that bumps versions and updates `CHANGELOG.md` files.\n   - When **that** PR is merged, the same workflow detects the bumped versions, runs `pnpm\n     build`, and `pnpm publish`es each changed package to npm with provenance.\n\n## Manual publish (escape hatch)\n\nIf the workflow is broken, you can run the same steps locally with a classic npm token:\n\n```bash\npnpm ci:version\npnpm ci:publish\n```\n\nSet `NPM_TOKEN` in your environment first. **Do not** commit the token.\n\n## How `ci:publish` is wired\n\n`ci:publish` in the root `package.json` is:\n\n```bash\npnpm publish -r --provenance --access=public --no-git-checks\n```\n\n- `-r`: recursively publish all workspace packages.\n- `--provenance`: emit SLSA provenance attestations (a no-op without OIDC, automatic with it).\n- `--access=public`: required for scoped packages on first publish.\n- `--no-git-checks`: skip pnpm's branch / clean-tree guard, since CI does not need it.\n"
+      "body": "# Release and publish\n\n> **Project** (non-normative maintainer notes) \xB7 **For:** maintainers shipping Cotal\n\nCotal uses [Changesets](https://github.com/changesets/changesets) to version and publish the\nworkspace packages under `packages/*`, `extensions/*`, and `implementations/*` to npm.\n`examples/**` is ignored, since it is not published.\n\n## 0.11 runtime migration\n\nThe published binary no longer bundles the optional tmux and cmux runtimes. Existing operators\nmust run `cotal ext add @cotal-ai/tmux` or `cotal ext add @cotal-ai/cmux` once after upgrading,\nbefore using `runtime: tmux|cmux` in a manifest or passing `--runtime tmux|cmux`. Missing runtimes\nfail loudly with the matching install command; they never fall back to pty.\n\n## One-time npm setup: trusted publishing (OIDC)\n\nTrusted publishing replaces the long-lived `NPM_TOKEN` secret with short-lived OIDC tokens\nissued by GitHub Actions. Each published package must be configured once on npmjs.com.\n\nFor **every** published package (`@cotal-ai/core`, `@cotal-ai/cli`, `@cotal-ai/manager`,\n`@cotal-ai/delivery`, `@cotal-ai/connector-core`, `@cotal-ai/connector-claude-code`,\n`@cotal-ai/connector-opencode`, `@cotal-ai/connector-hermes`, `@cotal-ai/cmux`, `@cotal-ai/orca`, and the\n`cotal-ai` binary):\n\n1. Go to `https://www.npmjs.com/package/<name>/access` (e.g.\n   `https://www.npmjs.com/package/@cotal-ai/core/access`).\n2. Scroll to **Trusted publishing** \u2192 **Add a trusted publisher**.\n3. Pick **GitHub Actions**.\n4. Fill in:\n   - **Organization or user:** the GitHub owner (your org or user).\n   - **Repository:** `SWARL` (or whatever this repo is called).\n   - **Workflow filename:** `changesets.yml`.\n   - **Environment name:** leave blank.\n5. Save. Repeat for every package.\n\n> The first time, you may need to publish a version manually (with a classic token) so the\n> package exists on npm. After that, OIDC takes over.\n\n## Day-to-day flow\n\n1. Open a PR that changes code in a publishable package.\n2. Add a changeset describing the change:\n\n   ```bash\n   pnpm changeset\n   ```\n\n   Pick the affected packages plus the semver bump (patch / minor / major), and write a\n   one-line summary. Commit the generated `.changeset/<name>.md` file alongside your code\n   change.\n3. Merge to `main`.\n4. The `Changesets` workflow runs:\n   - If there are pending changesets, it opens (or updates) a PR titled `chore(release):\n     version packages` that bumps versions and updates `CHANGELOG.md` files.\n   - When **that** PR is merged, the same workflow detects the bumped versions, runs `pnpm\n     build`, and `pnpm publish`es each changed package to npm with provenance.\n\n## Manual publish (escape hatch)\n\nIf the workflow is broken, you can run the same steps locally with a classic npm token:\n\n```bash\npnpm ci:version\npnpm ci:publish\n```\n\nSet `NPM_TOKEN` in your environment first. **Do not** commit the token.\n\n## How `ci:publish` is wired\n\n`ci:publish` in the root `package.json` is:\n\n```bash\npnpm publish -r --provenance --access=public --no-git-checks\n```\n\n- `-r`: recursively publish all workspace packages.\n- `--provenance`: emit SLSA provenance attestations (a no-op without OIDC, automatic with it).\n- `--access=public`: required for scoped packages on first publish.\n- `--no-git-checks`: skip pnpm's branch / clean-tree guard, since CI does not need it.\n"
     },
     {
       "slug": "roadmap",
@@ -42391,7 +42420,7 @@ var DOCS_BUNDLE = {
       "title": "Run a mesh",
       "kind": "Guide (informative)",
       "summary": "Day-to-day operation of a local mesh: what cotal up actually runs, how spawning resolves personas, harnesses, and models, how to reach a mesh from any directory, and the operator-only maintenance v\u2026",
-      "body": "# Run a mesh\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\nDay-to-day operation of a local mesh: what `cotal up` actually runs, how spawning\nresolves personas, harnesses, and models, how to reach a mesh from any directory, and the\noperator-only maintenance verbs. Every command's full flag set is in the\n[CLI reference](cli.md).\n\n## The stack\n\n`cotal up` brings up the whole local stack and `cotal down` stops it:\n\n- **Broker**: a local `nats-server` (logs to `.cotal/nats.log`).\n- **Delivery daemon**: the durable backstop, auth mode only\n  ([what it does](delivery-daemon.md)).\n- **Manager**: a detached supervisor answering the control plane, so\n  `cotal spawn --detach` and the `cotal_spawn` tool work right after `up`.\n\nThree modes:\n\n- **Default (static auth).** JWT-authed, on by default: sender authenticity and per-agent\n  ACLs, enforced by the broker ([how](identity-and-auth.md)).\n- **`--user-auth --idp <url>`.** Per-user auth: people `cotal login` once, the operator\n  grants their agents on the actor ledger, and every connect is authorized live against\n  that grant. Starts the space's auth service alongside the broker\n  ([how](identity-and-auth.md)).\n- **`--open`.** An unauthenticated, live-only dev mesh (no auth, no delivery daemon). For\n  quick local experiments.\n\nAll bind **loopback** by default. `--host 0.0.0.0` widens the bind independently of the\nauth mode, so \"network-reachable\" never silently means \"unauthenticated\". With no explicit\n`--server`, `cotal up` auto-selects a free local port when the default address is already\nheld by another project; an explicit `--server` fails loud on collision.\n\n`cotal status` prints the detailed setup, process, registry, and live mesh status;\n`cotal setup` (after the first run) prints the compact card.\n\n## Spawning agents\n\n```bash\ncotal spawn                        # foreground: your default agent, in this terminal\ncotal spawn reviewer --detach      # supervised: the manager runs it in a PTY\ncotal attach reviewer              # watch/type into a detached agent (Ctrl-] detaches)\ncotal ps                           # what the manager is running\ncotal stop reviewer                # stop one\n```\n\nHow a spawn resolves:\n\n- **Persona.** A bare `cotal spawn` uses `.cotal/agents/default.md`; a positional name\n  picks `.cotal/agents/<name>.md`; `--config` takes an explicit ref or path. Set\n  `COTAL_DEFAULT_PERSONA=<name-or-path>` to change the fallback. Fields and format:\n  [agent files](agent-files.md).\n- **Harness.** Claude by default; `--agent opencode` / `--agent hermes` per spawn, or\n  `COTAL_DEFAULT_AGENT` to change the default. Per-connector guides:\n  [Claude](connect-claude.md) \xB7 [OpenCode](connect-opencode.md) \xB7\n  [Hermes](connect-hermes.md).\n- **Model.** `--model` overrides the persona file's `model:` (Claude: `opus` / `sonnet` or\n  a full id; OpenCode: `provider/model`). Connectors that expose a catalog report it via\n  `cotal models --agent opencode`: model ids plus available variants; pick one with\n  `--model provider/model --variant high`.\n- **Tools.** A spawned agent gets only the cotal tools by default; share your own MCP\n  servers deliberately with `--share-tools` ([config](config.md)).\n- **Launch options.** `--opt key=value` (repeatable) passes a native harness flag straight\n  through; a persona or manifest `launchOptions:` mapping does the same declaratively (a\n  `--opt` wins per key). It is a **raw passthrough**, with no allow/deny list: Claude renders\n  each as `--key value` (a bare `--key` for an empty value), OpenCode merges them into its\n  agent config, and Hermes has no option surface so it fails loud. The trust boundary is the\n  `spawn` capability itself, not the flag set, so granting `spawn` is host-launch authority\n  ([security](security.md)). A key must be a plain flag name; malformed or prototype-polluting\n  keys are refused.\n\nDetach from an attached PTY with **Ctrl-]** (the agent keeps running); rebind it with\n`COTAL_DETACH_KEY=ctrl-<char>` when it clashes with a keybinding inside the agent's TUI.\n\n**Runtimes.** The manager spawns into a **pty** it owns by default. `cotal supervise\n--runtime tmux` / `--runtime cmux` put each teammate in its own tmux window / cmux tab\ninstead. Explicit only: they throw if the matching extension isn't loaded, never silently\nfall back ([architecture](architecture.md)).\n\n## From any directory: the mesh registry\n\n`cotal up` records each running mesh in a machine-local registry\n(`~/.cotal/meshes/<space>.json`: broker URL, the project root holding its creds and\npersonas, and its mode). So a bare `cotal spawn <persona>` from *any* directory joins the\nrunning mesh with the right credentials instead of mistaking the cwd for a space:\n\n- One mesh up \u2192 used automatically. Inside a project with its own `.cotal/`, that project\n  wins.\n- Several up \u2192 pick with `--space <name>`, or set a default with `cotal use <name>`.\n- `cotal meshes` lists them (a `*` marks the default); `cotal down` removes the entry.\n\nThe registry stores a *path*, never a secret; trust material stays in each project's\n`.cotal/auth`. If the mesh is down or won't take your creds, spawn fails with one\nsentence, never a raw NATS trace.\n\n## Watching\n\n`cotal console` is the terminal view (TUI on a real terminal, plain line stream when\npiped); `cotal web` is the browser dashboard. Both are read-only observers; the\nwalkthrough is [Watch a mesh](watch-a-mesh.md).\n\n## History\n\nRetained history is operator-owned. `cotal clean history --force` purges a space's\nretained channel history; `--dms` also purges DMs (`cotal history clear` is an alias).\nIt is deliberately **not** an agent tool: agents cannot wipe the record\n([identity & auth](identity-and-auth.md)). For a **stopped** mesh, `cotal clean store\n--force` deletes the on-disk JetStream store outright, and `cotal clean all --force`\nalso resets the space identity ([CLI reference](cli.md#clean)).\n\n## Personas from the CLI\n\n`cotal personas` manages the local catalog offline: `list` (`--running` overlays live\nmarkers), `show <name>`, `edit <name>` (re-validates on save), `new <name>`, `rm <name>\n--force`. The runtime counterpart is the `cotal_persona` tool, which goes over the wire\nwith the manager's ownership checks. Fields: [agent files](agent-files.md).\n\n## When something looks absent\n\nPermission denials are **loud, never silent**: an over-tight ACL shows up as a logged\ndenial on the endpoint, not as a peer that mysteriously looks absent. Check\n`.cotal/manager.log`, `.cotal/delivery.log`, and `.cotal/nats.log`; `cotal status` shows\nwhat is actually running. The access rules are collected in\n[Channels & permissions](channels-and-permissions.md).\n"
+      "body": "# Run a mesh\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\nDay-to-day operation of a local mesh: what `cotal up` actually runs, how spawning\nresolves personas, harnesses, and models, how to reach a mesh from any directory, and the\noperator-only maintenance verbs. Every command's full flag set is in the\n[CLI reference](cli.md).\n\n## The stack\n\n`cotal up` brings up the whole local stack and bare `cotal down` stops it:\n\n- **Broker**: a local `nats-server` (logs to `.cotal/nats.log`).\n- **Delivery daemon**: the durable backstop, auth mode only\n  ([what it does](delivery-daemon.md)).\n- **Manager**: a detached supervisor answering the control plane, so\n  `cotal spawn --detach` and the `cotal_spawn` tool work right after `up`.\n\nThree modes:\n\n- **Default (static auth).** JWT-authed, on by default: sender authenticity and per-agent\n  ACLs, enforced by the broker ([how](identity-and-auth.md)).\n- **`--user-auth --idp <url>`.** Per-user auth: people `cotal login` once, the operator\n  grants their agents on the actor ledger, and every connect is authorized live against\n  that grant. Starts the space's auth service alongside the broker\n  ([how](identity-and-auth.md)).\n- **`--open`.** An unauthenticated, live-only dev mesh (no auth, no delivery daemon). For\n  quick local experiments.\n\nAll bind **loopback** by default. `--host 0.0.0.0` widens the bind independently of the\nauth mode, so \"network-reachable\" never silently means \"unauthenticated\". With no explicit\n`--server`, `cotal up` auto-selects a free local port when the default address is already\nheld by another project; an explicit `--server` fails loud on collision.\n\n`cotal status` prints the detailed setup, process, registry, and live mesh status;\n`cotal setup` (after the first run) prints the compact card.\n\nStop one part without tearing down the mesh by naming its registered component: `cotal down\nmanager`, `cotal down delivery`, or `cotal down web`. Component names from installed extensions\njoin the same surface; `cotal down` with no names retains whole-stack behavior.\n\n## Spawning agents\n\n```bash\ncotal spawn                        # foreground: your default agent, in this terminal\ncotal spawn reviewer --detach      # supervised: the manager runs it in a PTY\ncotal attach reviewer              # watch/type into a detached agent (Ctrl-] detaches)\ncotal ps                           # what the manager is running\ncotal stop reviewer                # stop one\n```\n\nHow a spawn resolves:\n\n- **Persona.** A bare `cotal spawn` uses `.cotal/agents/default.md`; a positional name\n  picks `.cotal/agents/<name>.md`; `--config` takes an explicit ref or path. Set\n  `COTAL_DEFAULT_PERSONA=<name-or-path>` to change the fallback. Fields and format:\n  [agent files](agent-files.md).\n- **Harness.** Claude by default; `--agent opencode` / `--agent hermes` per spawn, or\n  `COTAL_DEFAULT_AGENT` to change the default. Per-connector guides:\n  [Claude](connect-claude.md) \xB7 [OpenCode](connect-opencode.md) \xB7\n  [Hermes](connect-hermes.md).\n- **Model.** `--model` overrides the persona file's `model:` (Claude: `opus` / `sonnet` or\n  a full id; OpenCode: `provider/model`). Connectors that expose a catalog report it via\n  `cotal models --agent opencode`: model ids plus available variants; pick one with\n  `--model provider/model --variant high`.\n- **Tools.** A spawned agent gets only the cotal tools by default; share your own MCP\n  servers deliberately with `--share-tools` ([config](config.md)).\n- **Launch options.** `--opt key=value` (repeatable) passes a native harness flag straight\n  through; a persona or manifest `launchOptions:` mapping does the same declaratively (a\n  `--opt` wins per key). It is a **raw passthrough**, with no allow/deny list: Claude renders\n  each as `--key value` (a bare `--key` for an empty value), OpenCode merges them into its\n  agent config, and Hermes has no option surface so it fails loud. The trust boundary is the\n  `spawn` capability itself, not the flag set, so granting `spawn` is host-launch authority\n  ([security](security.md)). A key must be a plain flag name; malformed or prototype-polluting\n  keys are refused.\n\nDetach from an attached PTY with **Ctrl-]** (the agent keeps running); rebind it with\n`COTAL_DETACH_KEY=ctrl-<char>` when it clashes with a keybinding inside the agent's TUI.\n\n**Runtimes.** The manager spawns into a **pty** it owns by default. Optional runtimes are installed\nthrough the extension surface, for example `cotal ext add @cotal-ai/orca`, then selected with\n`--runtime orca` (similarly `@cotal-ai/tmux` and `@cotal-ai/cmux`). They put teammates in native\nterminal surfaces rather than manager-owned PTYs. Runtime names are open-ended and resolved from\nthe registry; a missing provider or app throws, never silently falls back\n([architecture](architecture.md)).\n\n## From any directory: the mesh registry\n\n`cotal up` records each running mesh in a machine-local registry\n(`~/.cotal/meshes/<space>.json`: broker URL, the project root holding its creds and\npersonas, and its mode). So a bare `cotal spawn <persona>` from *any* directory joins the\nrunning mesh with the right credentials instead of mistaking the cwd for a space:\n\n- One mesh up \u2192 used automatically. Inside a project with its own `.cotal/`, that project\n  wins.\n- Several up \u2192 pick with `--space <name>`, or set a default with `cotal use <name>`.\n- `cotal meshes` lists them (a `*` marks the default); `cotal down` removes the entry.\n\nThe registry stores a *path*, never a secret; trust material stays in each project's\n`.cotal/auth`. If the mesh is down or won't take your creds, spawn fails with one\nsentence, never a raw NATS trace.\n\n## Watching\n\n`cotal console` is the terminal view (TUI on a real terminal, plain line stream when\npiped); `cotal web` is the browser dashboard. Both are read-only observers; the\nwalkthrough is [Watch a mesh](watch-a-mesh.md).\n\n## History\n\nRetained history is operator-owned. `cotal clean history --force` purges a space's\nretained channel history; `--dms` also purges DMs (`cotal history clear` is an alias).\nIt is deliberately **not** an agent tool: agents cannot wipe the record\n([identity & auth](identity-and-auth.md)). For a **stopped** mesh, `cotal clean store\n--force` deletes the on-disk JetStream store outright, and `cotal clean all --force`\nalso resets the space identity ([CLI reference](cli.md#clean)).\n\n## Personas from the CLI\n\n`cotal personas` manages the local catalog offline: `list` (`--running` overlays live\nmarkers), `show <name>`, `edit <name>` (re-validates on save), `new <name>`, `rm <name>\n--force`. The runtime counterpart is the `cotal_persona` tool, which goes over the wire\nwith the manager's ownership checks. Fields: [agent files](agent-files.md).\n\n## When something looks absent\n\nPermission denials are **loud, never silent**: an over-tight ACL shows up as a logged\ndenial on the endpoint, not as a peer that mysteriously looks absent. Check\n`.cotal/manager.log`, `.cotal/delivery.log`, and `.cotal/nats.log`; `cotal status` shows\nwhat is actually running. The access rules are collected in\n[Channels & permissions](channels-and-permissions.md).\n"
     },
     {
       "slug": "security",
@@ -42405,7 +42434,7 @@ var DOCS_BUNDLE = {
       "title": "Setup internals (maintainer notes)",
       "kind": "Project (non-normative maintainer notes)",
       "summary": "cotal setup (implementations/cli/src/commands/setup.ts) is configure-only and state-independent: it checks prerequisites, installs the Claude Code plugin, and seeds persona files, and it launches n\u2026",
-      "body": "# Setup internals (maintainer notes)\n\n> **Project** (non-normative maintainer notes) \xB7 **For:** maintainers changing how setup works\n>\n> How `cotal setup` works, and the cross-repo couplings it depends on. If you change one of\n> the things in the **Invariants** table, update the listed siblings in the same change, or\n> setup silently breaks for npx users.\n\n## The flow\n\n`cotal setup`\n([`implementations/cli/src/commands/setup.ts`](../implementations/cli/src/commands/setup.ts))\nis **configure-only and state-independent**: it checks prerequisites, installs the Claude Code\nplugin, and seeds persona files, and it **launches nothing**: no mesh, no web dashboard, no\nmanager, no delivery daemon, no cmux/tmux session, no demo. Starting the stack is `cotal up`; the\ndashboard is `cotal web`. Every file it writes is announced (`\u2192 wrote \u2026` via `provenance.wrote`).\nIt is two-tier, gated on a machine marker.\n\n**First run** (no `~/.cotal/onboarded.json`, or `--full`, or `--yes`) runs `runFirstRun(yes)`:\n\n- splash \u2192 intro \u2192 core **checks** (Node >= 20; **locate** `nats-server`: located, never\n  started) \u2192 **connector picker** \u2192 write the demo personas (david/sven/me) and seed the generic\n  `default` \u2192 **offer a global install** (`offerGlobalInstall`) \u2192 onboarded marker \u2192 a finale that\n  lists the commands to start things (`cotal up --detach`, `cotal web`, `cotal spawn \u2026`,\n  `cotal console`, `cotal down`). Nothing is running when it returns.\n- The old `--auth` / `--open` flags are **gone**: they set the mesh MODE at launch time, and setup\n  no longer launches; mode is now `cotal up [--open]`'s concern (an unknown-option error names\n  them, no silent no-op).\n\n**Later runs** run `runEnsure`: re-seed the `default` persona if it's missing (announced), then\nprint the **status card** (`readyCard`). The card is **read-only probes** (`machineStatus`/`meshStatus`/`webUp`/`managerUp` for NATS, the plugin, the mesh, the web\ndashboard, and the manager) and for anything down it prints the exact command to start it\n(`cotal up --detach`, `cotal web`, `cotal supervise`). Displaying state never depends on it; setup\nstill launches nothing.\n\nSteps run in-process via `runSteps`\n([`lib/steps.ts`](../implementations/cli/src/lib/steps.ts)). A step can be `optional` (asked\nY/n), carry a `confirm` consent prompt, or be `live` (it draws its own pane via\n[`lib/live-window.ts`](../implementations/cli/src/lib/live-window.ts)). On failure, an\ninteractive run offers a Claude handoff\n([`lib/assist.ts`](../implementations/cli/src/lib/assist.ts)).\n\nThe **connector picker** (`pickConnectors`) multiselects Claude / OpenCode (detected\npre-checked). Only **Claude** runs an install (its wake channel binds to an *installed* plugin);\n**OpenCode auto-wires at spawn** (it injects its plugin via `buildLaunch`, never writing the\nuser's config), so the picker just marks it ready. Two experts (david, the engineer; sven, the\nguide) plus the operator's own driving session (`me`) are written by default, and `me` is the\npersona `cotal spawn me` drives.\n\n**`--yes`** forces non-interactive accept-all even on a TTY: optional plus `confirm` steps run\n(so the demo personas are written), the global install takes its default, and a failure aborts\nwith the log path and a non-zero exit. It still launches nothing. The control plane comes up with\n`cotal up --detach`. This is the agent/CI contract; keep it working.\n\n## Invariants\n\n| Thing | Must stay in sync across | Why |\n|---|---|---|\n| Marketplace name **`cotal-mesh`** | `setup.ts` (materialized `marketplace.json`), `CHANNEL_REF` in [`extensions/connector-claude-code/src/extension.ts`](../extensions/connector-claude-code/src/extension.ts), repo [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) | The wake channel ref `plugin:cotal@cotal-mesh` binds by this name |\n| Plugin assets | `setup.ts` copy list (`dist/mcp.cjs`, `dist/hook.cjs`, `.claude-plugin/plugin.json`, `.mcp.json`, `hooks/hooks.json`) and the connector `package.json` `files` field | Setup materializes the plugin from `Connector.pluginRoot`; missing or renamed assets break the install |\n| `Connector.pluginRoot` | [`packages/core/src/connector.ts`](../packages/core/src/connector.ts) (contract) plus set in the claude connector's `extension.ts` | How setup finds the plugin dir without importing the extension |\n| `BUNDLED_PKG_PREFIX` | [`lib/nats-bin.ts`](../implementations/cli/src/lib/nats-bin.ts) \u2194 the `@eplightning/nats-server-*` `optionalDependencies` in [`implementations/cli/package.json`](../implementations/cli/package.json) | The bundled NATS binary is resolved by `${prefix}-${platform}-${arch}`. (Future: swap the prefix to our own `@cotal-ai/nats-server-*`.) |\n| Onboard marker plus `ONBOARD_VERSION` | `~/.cotal/onboarded.json` in [`lib/onboard.ts`](../implementations/cli/src/lib/onboard.ts); version const in `setup.ts` | Flips first-run vs ensure |\n| Demo-agent format | `DEMO_AGENTS` in `setup.ts` matches the frontmatter shape read by [`packages/core/src/agent-file.ts`](../packages/core/src/agent-file.ts) (same as `examples/01-lateral-coordination/agents/`) | `cotal spawn <name>` loads these |\n| Managed personas | each `DEMO_AGENTS` body carries a `# managed by cotal-setup` frontmatter marker; `writeDemoAgent` refreshes the file when the body changes, backing a marker-less (user-edited) file up to `<name>.md.bak` first | Edit `DEMO_AGENTS` plus re-run setup to update david/sven/me; delete the marker line to take ownership |\n| `DEFAULT_SERVER` | [`packages/core/src/endpoint.ts`](../packages/core/src/endpoint.ts) | The address `cotal up` starts and the status card probes |\n\n## Background processes (`cotal up`)\n\n`cotal up` brings up the whole local stack in one place; since setup became configure-only\n(stage 2b), this is where the mesh and control plane start, so `cotal spawn --detach` /\n`cotal_spawn` find a manager right after `up`. The control plane comes up in cutover order:\nold-manager preflight \u2192 **delivery daemon** (auth mode only) \u2192 **manager**, via\n`ensureControlPlane`\n([`lib/delivery-proc.ts`](../implementations/cli/src/lib/delivery-proc.ts)). The detached\nprocesses, all stopped by `cotal down`:\n\nWith no explicit `--server`, `cotal up` auto-selects a free local port when the default broker\naddress is already held by another root or an unrecorded broker; an explicit `--server` remains\nfail-loud on collision.\n\n- **Mesh:** `startMeshDetached`\n  ([`commands/up.ts`](../implementations/cli/src/commands/up.ts)) is the one place that boots a\n  background nats-server (foreground `up` and `up --detach` both route through it). Writes\n  `.cotal/nats.pid` and tails `.cotal/nats.log`.\n- **Delivery daemon:** `startDeliveryDetached` / `ensureDelivery`\n  ([`lib/delivery-proc.ts`](../implementations/cli/src/lib/delivery-proc.ts)) re-execs `cotal\n  deliver` detached with a pre-minted scoped `delivery.creds` (auth mode only, the durable\n  backstop; open mode has none). Writes `.cotal/delivery.pid` and `.cotal/delivery.log`.\n- **Manager:** `startManagerDetached` / `ensureManager`\n  ([`lib/manager-proc.ts`](../implementations/cli/src/lib/manager-proc.ts)) re-execs `cotal\n  supervise` detached (pty runtime); it answers the control plane\n  (`cotal_spawn` / `cotal_despawn` / `cotal_persona`). Writes `.cotal/manager.pid` and\n  `.cotal/manager.log`; `managerUp()` checks pid liveness for setup's status card.\n\nThe **web dashboard** is *not* part of `cotal up`. It ships as the `@cotal-ai/web` extension.\n`cotal setup` installs it automatically by reusing the same path as `cotal ext add @cotal-ai/web`\n(best-effort; failed install leaves the manual retry command). Start it with `cotal web`\n(re-execs the CLI detached; `.cotal/web.pid` / `.cotal/web.log`), addressed as\n`http://cotal.localhost:7799` (binds loopback; `*.localhost` resolves in Chrome/Firefox/Edge,\nSafari may need plain `127.0.0.1`). `webUp()` probes the port for setup's status card.\n\nAll re-execs resolve this CLI via `selfArgv()` / `selfCotal()`\n([`lib/self-exec.ts`](../implementations/cli/src/lib/self-exec.ts)) = `[node, ...loaderFlags,\nentry]` (tsx loader in dev, compiled JS in prod), so they never need `cotal` on PATH; the stack\ncomes up identically via `npx`, `npm i -g`, and a dev clone.\n\nFor ergonomics only, an npx run with no global `cotal` offers to `npm i -g cotal-ai`\n(`offerGlobalInstall`, pinned to the running version): gated on `isNpx()` plus a PATH scan\n(`cotalOnPath()`, not `onPath(\"cotal\")`, since `cotal --version` is not a real command). The\ninteractive prompt defaults to yes, the non-interactive path (`--yes` or no TTY) takes the\ndefault, and a failed install is non-fatal (warn plus manual command). The same `self-exec.ts`\nexposes `displayCmd()`, the prefix (`cotal` / `npx cotal-ai` / `pnpm cotal`) used in the\nstatus-card hints so they match how you ran it.\n"
+      "body": "# Setup internals (maintainer notes)\n\n> **Project** (non-normative maintainer notes) \xB7 **For:** maintainers changing how setup works\n>\n> How `cotal setup` works, and the cross-repo couplings it depends on. If you change one of\n> the things in the **Invariants** table, update the listed siblings in the same change, or\n> setup silently breaks for npx users.\n\n## The flow\n\n`cotal setup`\n([`implementations/cli/src/commands/setup.ts`](../implementations/cli/src/commands/setup.ts))\nis **configure-only and state-independent**: it checks prerequisites, installs the Claude Code\nplugin, and seeds persona files, and it **launches nothing**: no mesh, no web dashboard, no\nmanager, no delivery daemon, no cmux/tmux session, no demo. Starting the stack is `cotal up`; the\ndashboard is `cotal web`. Every file it writes is announced (`\u2192 wrote \u2026` via `provenance.wrote`).\nIt is two-tier, gated on a machine marker.\n\n**First run** (no `~/.cotal/onboarded.json`, or `--full`, or `--yes`) runs `runFirstRun(yes)`:\n\n- splash \u2192 intro \u2192 core **checks** (Node >= 20; **locate** `nats-server`: located, never\n  started) \u2192 **connector picker** \u2192 write the demo personas (david/sven/me) and seed the generic\n  `default` \u2192 **offer a global install** (`offerGlobalInstall`) \u2192 onboarded marker \u2192 a finale that\n  lists the commands to start things (`cotal up --detach`, `cotal web`, `cotal spawn \u2026`,\n  `cotal console`, `cotal down`). Nothing is running when it returns.\n- The old `--auth` / `--open` flags are **gone**: they set the mesh MODE at launch time, and setup\n  no longer launches; mode is now `cotal up [--open]`'s concern (an unknown-option error names\n  them, no silent no-op).\n\n**Later runs** run `runEnsure`: re-seed the `default` persona if it's missing (announced), then\nprint the **status card** (`readyCard`). The card is **read-only probes** (`machineStatus`/`meshStatus`/`webUp`/`managerUp` for NATS, the plugin, the mesh, the web\ndashboard, and the manager) and for anything down it prints the exact command to start it\n(`cotal up --detach`, `cotal web`, `cotal supervise`). Displaying state never depends on it; setup\nstill launches nothing.\n\nSteps run in-process via `runSteps`\n([`lib/steps.ts`](../implementations/cli/src/lib/steps.ts)). A step can be `optional` (asked\nY/n), carry a `confirm` consent prompt, or be `live` (it draws its own pane via\n[`lib/live-window.ts`](../implementations/cli/src/lib/live-window.ts)). On failure, an\ninteractive run offers a Claude handoff\n([`lib/assist.ts`](../implementations/cli/src/lib/assist.ts)).\n\nThe **connector picker** (`pickConnectors`) multiselects Claude / OpenCode (detected\npre-checked). Only **Claude** runs an install (its wake channel binds to an *installed* plugin);\n**OpenCode auto-wires at spawn** (it injects its plugin via `buildLaunch`, never writing the\nuser's config), so the picker just marks it ready. Two experts (david, the engineer; sven, the\nguide) plus the operator's own driving session (`me`) are written by default, and `me` is the\npersona `cotal spawn me` drives.\n\n**`--yes`** forces non-interactive accept-all even on a TTY: optional plus `confirm` steps run\n(so the demo personas are written), the global install takes its default, and a failure aborts\nwith the log path and a non-zero exit. It still launches nothing. The control plane comes up with\n`cotal up --detach`. This is the agent/CI contract; keep it working.\n\n## Invariants\n\n| Thing | Must stay in sync across | Why |\n|---|---|---|\n| Marketplace name **`cotal-mesh`** | `setup.ts` (materialized `marketplace.json`), `CHANNEL_REF` in [`extensions/connector-claude-code/src/extension.ts`](../extensions/connector-claude-code/src/extension.ts), repo [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) | The wake channel ref `plugin:cotal@cotal-mesh` binds by this name |\n| Plugin assets | `setup.ts` copy list (`dist/mcp.cjs`, `dist/hook.cjs`, `.claude-plugin/plugin.json`, `.mcp.json`, `hooks/hooks.json`) and the connector `package.json` `files` field | Setup materializes the plugin from `Connector.pluginRoot`; missing or renamed assets break the install |\n| `Connector.pluginRoot` | [`packages/core/src/connector.ts`](../packages/core/src/connector.ts) (contract) plus set in the claude connector's `extension.ts` | How setup finds the plugin dir without importing the extension |\n| `BUNDLED_PKG_PREFIX` | [`lib/nats-bin.ts`](../implementations/cli/src/lib/nats-bin.ts) \u2194 the `@eplightning/nats-server-*` `optionalDependencies` in [`implementations/cli/package.json`](../implementations/cli/package.json) | The bundled NATS binary is resolved by `${prefix}-${platform}-${arch}`. (Future: swap the prefix to our own `@cotal-ai/nats-server-*`.) |\n| Onboard marker plus `ONBOARD_VERSION` | `~/.cotal/onboarded.json` in [`lib/onboard.ts`](../implementations/cli/src/lib/onboard.ts); version const in `setup.ts` | Flips first-run vs ensure |\n| Demo-agent format | `DEMO_AGENTS` in `setup.ts` matches the frontmatter shape read by [`packages/core/src/agent-file.ts`](../packages/core/src/agent-file.ts) (same as `examples/01-lateral-coordination/agents/`) | `cotal spawn <name>` loads these |\n| Managed personas | each `DEMO_AGENTS` body carries a `# managed by cotal-setup` frontmatter marker; `writeDemoAgent` refreshes the file when the body changes, backing a marker-less (user-edited) file up to `<name>.md.bak` first | Edit `DEMO_AGENTS` plus re-run setup to update david/sven/me; delete the marker line to take ownership |\n| `DEFAULT_SERVER` | [`packages/core/src/endpoint.ts`](../packages/core/src/endpoint.ts) | The address `cotal up` starts and the status card probes |\n\n## Background processes (`cotal up`)\n\n`cotal up` brings up the whole local stack in one place; since setup became configure-only\n(stage 2b), this is where the mesh and control plane start, so `cotal spawn --detach` /\n`cotal_spawn` find a manager right after `up`. The control plane comes up in cutover order:\nold-manager preflight \u2192 **delivery daemon** (auth mode only) \u2192 **manager**, via\n`ensureControlPlane`\n([`lib/delivery-proc.ts`](../implementations/cli/src/lib/delivery-proc.ts)). The detached\nprocesses, all stopped by `cotal down`:\n\nWith no explicit `--server`, `cotal up` auto-selects a free local port when the default broker\naddress is already held by another root or an unrecorded broker; an explicit `--server` remains\nfail-loud on collision.\n\n- **Mesh:** `startMeshDetached`\n  ([`commands/up.ts`](../implementations/cli/src/commands/up.ts)) is the one place that boots a\n  background nats-server (foreground `up` and `up --detach` both route through it). Writes\n  `.cotal/nats.pid` and tails `.cotal/nats.log`.\n- **Delivery daemon:** `startDeliveryDetached` / `ensureDelivery`\n  ([`lib/delivery-proc.ts`](../implementations/cli/src/lib/delivery-proc.ts)) re-execs `cotal\n  deliver` detached with a pre-minted scoped `delivery.creds` (auth mode only, the durable\n  backstop; open mode has none). Writes `.cotal/delivery.pid` and `.cotal/delivery.log`.\n- **Manager:** `startManagerDetached` / `ensureManager`\n  ([`lib/manager-proc.ts`](../implementations/cli/src/lib/manager-proc.ts)) re-execs `cotal\n  supervise` detached (pty runtime); it answers the control plane\n  (`cotal_spawn` / `cotal_despawn` / `cotal_persona`). Writes `.cotal/manager.pid` and\n  `.cotal/manager.log`; `managerUp()` checks pid liveness for setup's status card.\n\nThe **web dashboard** is *not* part of `cotal up`. It ships as the `@cotal-ai/web` extension.\n`cotal setup` installs it automatically by reusing the same path as `cotal ext add @cotal-ai/web`\n(best-effort; failed install leaves the manual retry command). Start it with `cotal web`; it records\n`.cotal/web.pid`, self-registers that process with `down`, and is addressed as\n`http://cotal.localhost:7799` (binds loopback; `*.localhost` resolves in Chrome/Firefox/Edge,\nSafari may need plain `127.0.0.1`). `webUp()` probes the port for setup's status card.\n\nAll recorded local processes self-register `local-process` descriptors. Bare `cotal down` resolves\nthe full set and stops it in dependency order; `cotal down manager` (or another component name)\nselects only that descriptor. Installed extensions cache their contributed registry keys, so the\nbase CLI does not hardcode optional package pidfiles.\n\nAll re-execs resolve this CLI via `selfArgv()` / `selfCotal()`\n([`lib/self-exec.ts`](../implementations/cli/src/lib/self-exec.ts)) = `[node, ...loaderFlags,\nentry]` (tsx loader in dev, compiled JS in prod), so they never need `cotal` on PATH; the stack\ncomes up identically via `npx`, `npm i -g`, and a dev clone.\n\nFor ergonomics only, an npx run with no global `cotal` offers to `npm i -g cotal-ai`\n(`offerGlobalInstall`, pinned to the running version): gated on `isNpx()` plus a PATH scan\n(`cotalOnPath()`, not `onPath(\"cotal\")`, since `cotal --version` is not a real command). The\ninteractive prompt defaults to yes, the non-interactive path (`--yes` or no TTY) takes the\ndefault, and a failed install is non-fatal (warn plus manual command). The same `self-exec.ts`\nexposes `displayCmd()`, the prefix (`cotal` / `npx cotal-ai` / `pnpm cotal`) used in the\nstatus-card hints so they match how you ran it.\n"
     },
     {
       "slug": "spaces",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cotal-ai/connector-opencode",
   "description": "Cotal connector for OpenCode: a native in-process plugin that joins a session to the mesh.",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
     }
   },
   "dependencies": {
-    "@cotal-ai/connector-core": "0.11.1"
+    "@cotal-ai/connector-core": "0.11.2"
   },
   "peerDependencies": {
     "@cotal-ai/core": ">=0.1.0",
@@ -30,7 +30,7 @@
     "@opencode-ai/sdk": "^1.16.2",
     "esbuild": "^0.28.0",
     "tsx": "^4.22.4",
-    "@cotal-ai/core": "0.11.1"
+    "@cotal-ai/core": "0.11.2"
   },
   "files": [
     "dist"