@openwop/cli 1.0.1 → 1.2.0

package/README.md

@@ -19,8 +19,15 @@ The CLI is a host-agnostic **control plane**: every group drives one protocol su
 | **Memory & workspace** | `memory` · `workspace` · `prompts` |
 | **Automation & messaging** | `cron` · `webhooks` · `messaging` · `relay` · `notifications` · `notify` |
 | **Observability & admin** | `analytics` (`usage`) · `account` · `admin` · `brand` · `conformance` |
-| **Product surfaces** | `crm` · `csm` · `comments` · `sharing` · `forms` · `email` · `chat-widget` · `marketplace` · `kb` · `cms` · `documents` · `projects` · `strategy` · `advisors` · `campaigns-orchestration` · `notebooks` · `podcasts` · `priority-matrix` |
+| **Product surfaces** | `crm` · `csm` · `comments` · `sharing` · `forms` · `email` · `chat-widget` · `marketplace` · `kb` · `cms` · `documents` · `projects` · `strategy` · `advisors` · `campaigns-orchestration` · `notebooks` · `podcasts` · `priority-matrix` · `docs` · `knowledge-sync` · `entities` · `creative-briefs` · `creative-video` · `production` · `tutorials` · `walkthroughs` · `widgets` · `ui-state` · `ui-plugin` · `canvas-collab` · `workflow-collab` · `canvas-packs` · `present` |
+| **Commerce & sales** | `commerce` · `commerce-connect` · `promotions` · `recommendations` · `dealers` · `commissions` · `territories` · `sales-maps` (+ `crm` extensions) |
+| **Marketing** | `brand-kits` · `campaign-brief` · `campaign-connectors` · `campaign-intel` · `campaign-journeys` · `cdp` · `destination-sync` · `discovery` · `funnels` · `webinars` · `public` |
+| **Operator administration** | `vault` · `developer-keys` · `billing` · `environments` · `custom-domains` · `site-config` · `runtime-posture` · `maintenance` · `menu-config` |
+| **Operations & work management** | `operations` · `service-desk` · `job-search` · `kicktodo` · `dashboard` · `bi` · `insights-suite` · `intent-ledger` · `work-graph` · `work-selection` · `tasks` · `model-router` · `dev` (+ `strategy` / `priority-matrix` / `projects` / `goals` / `workforces` / `roster` / `profiles` / `twin` / `agent-ops` / `analytics` / `marketplace` / `connections` / `workspace` extensions) |
 | **Protocol surfaces (RFC)** | `a2a` · `triggers` · `goals` · `proposals` · `export` / `import` |
+| **Protocol + run operations** | `content` (RFC 0103) · `dispatch` (RFC 0118) · `openapi` · `agent-knowledge` · `compat-endpoints` (RFC 0108) · `host-events` · `client-support` (+ `runs` / `interrupts` / `workflows` / `approvals` / `reviews` / `webhooks` / `prompts` / `catalog` extensions) |
+| **Conversations & messaging** | `chat` (sessions/messages/search/export/tools) · `assistant` · `channels` · `scheduled-chats` · `voice` · `ai` · `computer-use` · `whatsapp` · `agent-author` · `workflow-author` · `workflow-proposals` (+ `a2a`, `notifications` extensions) |
+| **Settings & policy** | `capability-firewall` · `heartbeat` · `settings` (+ `cms` / `email` / `kb` / `forms` / `chat-widget` / `consent` / `approvals` / `profiles` / `advisors` / `campaigns-orchestration` / `notifications` / `workflows` / `kanban` / `job-search` extensions) |
 
 > **`0.18.x`:** the catalog now covers the full app feature surface — the agent
 > platform (`agent-profile`, `agent-packs`, `agent-allowlists`, `agent-ops`,
@@ -30,16 +37,70 @@ The CLI is a host-agnostic **control plane**: every group drives one protocol su
 > `triggers`, `goals`, `proposals`, `export`/`import`). See [`CHANGELOG.md`](./CHANGELOG.md)
 > for the per-group detail.
 
+> **Knowledge + content surfaces:** `documents` (+ `artifacts`, `locate`,
+> templates catalog/assemble), `notebooks` (sources/transformations/chat/search),
+> `podcasts` (shows + episode/speaker profiles), `knowledge-sync`, the `media`
+> library (assets, collections, AI image edit/upscale, local-file `upload`),
+> `entities` (+ anonymous `public` reads), `creative-briefs`, `creative-video`,
+> `production`, and the smaller `tutorials` / `walkthroughs` / `widgets` /
+> `ui-state` / `ui-plugin` / `canvas-collab` / `workflow-collab` / `canvas-packs`
+> / `present` groups. Example:
+>
+> ```bash
+> openwop media assets create ./logo.png --org org_1 --tags brand
+> openwop entities types list --json
+> openwop documents render doc_1 --org org_1 --format docx
+> ```
+
+> **Protocol + run operations:** `agents list|info`, `roster list` and
+> `org-chart get|dept` now read the NORMATIVE `/v1/agents`, `/v1/agents/roster`
+> and `/v1/agents/org-chart[/{departmentId}]`, falling back to the host-extension
+> path only when the host does not serve the normative read (`--host` forces it,
+> `--verbose` names the path that answered). New: `content` (RFC 0103
+> `/v1/content/*`), `runs effects|revision|pin|unpin|redrive`, `interrupts
+> inspect|respond`, `webhooks rotate-secret|dead-letters`, `catalog packs
+> search|get|export`, `workflows archive|promote|revisions|rollback|stats|estimate|pins|debug-run|eval-set…`,
+> `approvals sla-policy|email-pref|delegations`, `prompts library …`,
+> `agent-knowledge`, `compat-endpoints`, `host-events`, `client-support`,
+> `dispatch fanout`, `openapi`. Example:
+>
+> ```bash
+> openwop content page pricing --locale es
+> openwop runs effects run_123 --json
+> openwop interrupts respond run_123 approve-gate --data-json '{"action":"approve"}'
+> openwop workflows promote wf_123 && openwop workflows revisions wf_123
+> openwop webhooks rotate-secret sub_1 --generate
+> ```
+
 ## Protocol version support (v2 and v1)
 
 The CLI speaks the **OpenWOP wire directly** — no SDK dependency — and negotiates the protocol major once per invocation (`src/protocol.ts`, per `spec/v2/core/versioning.md` §1.5):
 
-- It reads `/.well-known/openwop` and selects the **highest major it implements that the host advertises** in `protocolVersions[]` — 2 when the host lists any `2.x`, otherwise 1.
-- Under major 2, every request for an operation named in `spec/v2/path-manifest.json` goes to the **unversioned path with `OpenWOP-Version: 2.0`** (`/v1/runs` → `/runs`). Host-proprietary routes the manifest does not name — the demo backend's `/v1/host/sample/*` — are sent exactly as written; they have no v2 home yet (`versioning.md` §5).
+- It reads `/.well-known/openwop` once (asking for the v2 representation with `OpenWOP-Version: 2`; a host that doesn't serve major 2 answers `406` with the list it does serve) and selects the **highest major it implements that the host advertises** in `protocolVersions[]` — 2 when the host lists any `2.x`, otherwise 1.
+- Under major 2, every request for an operation named in `spec/v2/path-manifest.json` goes to the **unversioned path with `OpenWOP-Version: 2.0`** (`/v1/runs` → `/runs`). Host-proprietary routes the manifest does not name — the reference host's `/v1/host/openwop-app/*` — go to the **unversioned root the host advertises** for that org under `extensions.*` (`{ "root": "/host/openwop-app/", "twin": "/v1/host/openwop-app/" }`, `versioning.md` §5), with **no** version header (a `/host/<org>/` path has no major). With no advertised root, the `/v1/host/<org>/…` twin is sent as written.
 - Under major 1 nothing changes: `/v1/…` paths, header-less, the v1 default the overlap guarantees.
 - `OPENWOP_PROTOCOL_MAJOR=1` or `=2` pins the major without probing discovery.
 
-`openwop doctor`'s `protocol` row reports `protocolVersions`, `preferredVersion`, and the major this process selected; it fails only when the host advertises neither major the CLI implements.
+`openwop doctor`'s `protocol` row reports `protocolVersions`, `preferredVersion`, and the major this process selected; it fails when the host advertises neither major the CLI implements. Its `response version` row reports the `OpenWOP-Version` the host answered with and fails on a silent downgrade (`versioning.md` §1.4); its `min client` row fails when the host's `minClientVersion` is above the version the CLI speaks (2.0 / 1.1) — the host MAY then refuse requests with `426 client_version_unsupported` (§1.5).
+
+What else the CLI does as a v2 client (audited against `spec/v2/core/*` at corpus `v2.42.6`):
+
+| Obligation | Behaviour |
+|---|---|
+| Tenant-bound ids (`identity.md` §5) | A `<tenantId>/<id>` run id is sent in the projected wire form (`acme~2Fr1`) on every `/runs/{runId}…` path under major 2 — never `%2F`, which a decoding front door turns into a 404. Pass ids as the host prints them. |
+| Error envelope (`errors.md`) | Errors print as `HTTP <status> <code>: <message>`; `426`/`406`/`429` add an actionable hint (`Retry-After` for 429). |
+| Poll cursor (`events.md` §Poll) | `afterSequence` under major 2, `lastSequence` under major 1; `isTerminal` / `isComplete`. |
+| SSE resume (`events.md` §Resuming with `Last-Event-ID`; v1 `stream-modes.md` §Resumption) | Every run stream (`runs events --follow` / `runs watch`, `chat`, `workflow-author`) remembers the last `id:` and, when the connection drops or closes before the terminal event, reconnects with `Last-Event-ID` after the server's `retry:` delay (doubling per attempt without progress, cap 30 s, 5 attempts). A close is first checked against the run's status, so a mode that never carries the terminal event (`messages`) ends cleanly. Events are deduped by `sequence`, so nothing prints twice even from a host that re-emits the resumption point. `--since N` / `--last-event-id ID` start mid-log: both majors send the `Last-Event-ID` header (neither defines a `since` stream parameter); v2 requires an integer id, v1's is sent verbatim. |
+| Stream modes (`events.md` §Stream modes; v1 `stream-modes.md`) | `--stream-mode` `updates`, `values`, `messages`, `debug` or a comma list of `updates`/`messages`/`debug` → `?streamMode=`, validated against the spec pattern before any request (`values` never combines). A host `400 unsupported_stream_mode` is reported with its `details.supported`, never silently replaced by the (mode-less) poll fallback. `state.snapshot` and `ai.message.chunk` frames are rendered by their frame name; `event: batch` arrays are unpacked. |
+| Event names (`events.md` §Types) | v1 and v2 names (`run.resuming` / `run.resume-started`, `agent.toolCalled` / `agent.tool-called`, …) render identically; the table is pinned to `spec/v2/event-codemap.json`. |
+| `Idempotency-Key` (`idempotency.md`) | Sent on run create/fork, chat turns, interrupt resolve, and webhook / trigger / prompt creation; `--idempotency-key` on `runs create|fork` and `interrupts resolve`. |
+| Interrupt resolve (`interrupt.md`) | Body is the closed `{ "resumeValue": … }`. |
+| Discovery (`capabilities.md`) | `openwop capabilities` renders the v2 root (records by status, `minClientVersion`, `eventLogSchemaVersion`, `extensions`) from the negotiation read. |
+| Run list (`runs.md` §List) | `runs list --cursor` / `--workflow-id`; the `nextCursor` hint is printed. |
+| Stream origin (host extension; openwop-app ADR 0761) | Some front doors buffer event streams entirely — `https://app.openwop.dev/api` delivered **0 bytes of an event stream in 25 s** (measured 2026-09-27), and `runs.md` keeps `eventsUrl` on the request's origin, so the protocol cannot redirect. Every stream (`runs watch`, `chat`, `notifications stream`, `kanban watch`, `present`) is therefore read from the **stream origin**: `--stream-base-url` > `OPENWOP_STREAM_BASE_URL` > config `host.streamBaseUrl` > a host-advertised `extensions.*.streamBase` (accepted only if `https:` with no credentials/query/fragment, read from an `https:` host; loopback `http:` only for a loopback base) > `--base-url`. Non-stream requests always use `--base-url`. To keep streams on `--base-url` too (e.g. an egress proxy), set `--stream-base-url` to the same URL; `openwop doctor`'s **stream origin** row shows which origin is in use and why. |
+| Stalled streams | A run stream that delivers **no bytes** (keep-alives included) for `--idle-timeout-ms` (default 45000; 0 disables) is aborted and resumed with `Last-Event-ID` — a half-open connection no longer hangs the command. `scripts/live-sse-resume.mjs` checks resume against a real run (`--mode drop|stall`). |
+
+When the host's `minClientVersion` is above the CLI, every command prints one warning (from the discovery read it already made); refusing is left to the host (`426`). Not exposed: the `bufferMs` batching hint (batched frames from a host that batches anyway are consumed).
 
 The pre-1.0 `0.18.x` line was frozen v1-only; that decision was reversed with 1.0.0 (CHANGELOG). The frozen line stays on branch `cli-v1-frozen` for anyone who needs a client that never sends `OpenWOP-Version`.
 
@@ -74,7 +135,7 @@ The `onboard` wizard walks you through:
 
 1. **Host URL** — `https://app.openwop.dev/api` (shared demo), `http://localhost:8080` (local), or a custom URL.
 2. **AI provider** — `anthropic`, `openai`, `google`, or `minimax` (matches what the demo backend dispatches to).
-3. **API key** — auto-detects `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_API_KEY` / `MINIMAX_API_KEY`, or hidden-input via raw-mode stdin. The key is POSTed to `/v1/host/sample/byok/secrets` on the configured host. **The key is never written to your local config file** — only a credential ref pointer is stored.
+3. **API key** — auto-detects `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_API_KEY` / `MINIMAX_API_KEY`, or hidden-input via raw-mode stdin. The key is POSTed to `/v1/host/openwop-app/byok/secrets` on the configured host. **The key is never written to your local config file** — only a credential ref pointer is stored.
 4. **Model** — provider-specific recommended defaults plus a custom option.
 5. **Test the connection** — verifies the credential ref appears in the host's BYOK list.
 
@@ -99,7 +160,7 @@ openwop providers remove openai
 openwop providers test anthropic
 ```
 
-`providers add` POSTs to `/v1/host/sample/byok/secrets`; `remove` DELETEs; `list` and `test` read.
+`providers add` POSTs to `/v1/host/openwop-app/byok/secrets`; `remove` DELETEs; `list` and `test` read.
 
 ## Chat
 
@@ -116,6 +177,35 @@ openwop chat sample.chat.turn --no-stream --json
 - **Quitting** — `/exit`, `/quit`, or Ctrl-D (EOF).
 - **`--json`** — emits raw event records (one JSON object per event) instead of the pretty `assistant>` rendering.
 - Extra per-turn inputs (`--input k=v`, `--inputs-json`) ride along on every run, so you can pin a `credentialRef`, model, or other configurable input.
+
+### Conversations, channels & voice
+
+`chat` is the ONE chat group: besides the REPL it drives the host's persistent
+conversations (`/v1/host/openwop-app/chat/*`) — sessions, messages, reactions,
+participants, feedback, search, export/import, and per-conversation tool scope.
+Team channels, scheduled agent chats, the executive assistant, voice, and the AI
+authoring surfaces each have their own group; every `--help` names the exact path.
+
+```bash
+openwop chat sessions create --title "Launch plan" --type group --participant agent:core.openwop.agents.planner.default
+openwop chat messages send <sessionId> --content "Summarize the thread"
+openwop chat search "pricing" --limit 5 --json
+openwop chat export <sessionId> --format md --output thread.md
+openwop chat tools set <sessionId> --mode restricted --enable openwop:fs.read
+openwop channels post <channelId> --content "@planner draft the agenda"
+openwop channels stream <channelId> --max-events 5
+openwop scheduled-chats create --org org_1 --conversation <id> --agent <agentId> --prompt "Weekly status" --cron "0 9 * * 1"
+openwop assistant pending approve <actionId> --content-hash <hash-from-the-card>
+openwop voice session audio <sessionId> --file hello.webm && openwop voice session commit <sessionId>
+openwop workflow-author draft --intent "Every Monday, summarize open tickets and email me" --follow
+openwop notifications stream --max-events 3
+```
+
+Streams (`channels stream|presence`, `notifications stream`, `voice realtime
+transcript`) stop after `--max-events` or `--timeout-ms` (default 30 s). Secrets
+stay server-side: the realtime voice token is redacted unless `--reveal-token`,
+and `ai bind-credential` reads the credential from a file or env var and prints
+only the returned reference.
 ## Packs (signed node-pack registry)
 
 ```bash
@@ -136,7 +226,7 @@ These talk to the signed node-pack registry — a **separate surface** from the
 
 ## Messaging & relay
 
-Connect chat channels (Signal / WhatsApp / iMessage) to the host so inbound messages drive workflow runs and replies are delivered back. Channels are a **host-extension** surface (`/v1/host/sample/messaging`), not part of the normative OpenWOP wire — the protocol stays channel-agnostic.
+Connect chat channels (Signal / WhatsApp / iMessage) to the host so inbound messages drive workflow runs and replies are delivered back. Channels are a **host-extension** surface (`/v1/host/openwop-app/messaging`), not part of the normative OpenWOP wire — the protocol stays channel-agnostic.
 
 ```bash
 openwop relay setup --channel signal        # register + activate a device, store its token
@@ -182,9 +272,10 @@ openwop runs annotate <runId> --rating 5 [--note "great"] # attach a rating/labe
 openwop runs annotate <runId> --label triage --event-id <id>
 openwop runs debug-bundle <runId> [--max-events n] [--out bundle.json]
 openwop runs ancestry <runId>                             # RFC 0040 cross-host parent chain
+openwop runs watch <runId> [--since N] [--stream-mode updates,messages]   # SSE follow, auto-resumes on a drop
 ```
 
-`runs events --since N` maps to the spec-canonical `lastSequence` query param (events with `sequence > N`). `runs annotate` posts exactly one signal kind (`--rating 1-5` | `--label` | `--correction` | `--flag`), validated client-side. `runs debug-bundle --out <file>` saves the full event bundle to disk.
+`runs events --since N` polls with the poll cursor (`afterSequence` under v2, `lastSequence` under v1; events with `sequence > N`). `runs events --follow` / `runs watch` stream over SSE instead, where `--since N` becomes the `Last-Event-ID` header (see §Protocol version support). `runs annotate` posts exactly one signal kind (`--rating 1-5` | `--label` | `--correction` | `--flag`), validated client-side. `runs debug-bundle --out <file>` saves the full event bundle to disk.
 
 ## Operator surfaces
 
@@ -268,7 +359,7 @@ Exit codes: `0` success · `1` host/HTTP error (including consent not enabled)
 
 ## MCP server mount
 
-An MCP client for the host's JSON-RPC server mount (RFC 0020) — a single JSON-RPC 2.0 endpoint at `POST /v1/host/sample/mcp` speaking modelcontextprotocol.io 2025-06-18. The mount is **host-controlled**: it's env-gated (`OPENWOP_MCP_SERVER_ENABLED`, **OFF by default**) and the CLI cannot toggle it. When the mount isn't exposed the endpoint 404s and these commands **fail closed legibly** (exit 2).
+An MCP client for the host's JSON-RPC server mount (RFC 0020) — a single JSON-RPC 2.0 endpoint at `POST /v1/host/openwop-app/mcp` speaking modelcontextprotocol.io 2025-06-18. The mount is **host-controlled**: it's env-gated (`OPENWOP_MCP_SERVER_ENABLED`, **OFF by default**) and the CLI cannot toggle it. When the mount isn't exposed the endpoint 404s and these commands **fail closed legibly** (exit 2).
 
 ```bash
 openwop mcp ping                                  # liveness probe of the mount
@@ -328,7 +419,7 @@ Identity `source` is one of `oidc | password | saml | scim | manual`. Exit codes
 
 ## Feature toggles
 
-`toggles` renders the caller's **resolved** feature-toggle assignments (a non-normative host extension under `/v1/host/sample/feature-toggles/assignments`). The **host** is the sole authority — it resolves every toggle server-side from the authenticated principal — and the CLI only *displays* what the host returns. It **never** computes, asserts, or overrides a toggle decision locally, and it does not author config (the superadmin config surface is intentionally not exposed). When the host doesn't serve the surface the command fails closed (exit 2).
+`toggles` renders the caller's **resolved** feature-toggle assignments (a non-normative host extension under `/v1/host/openwop-app/feature-toggles/assignments`). The **host** is the sole authority — it resolves every toggle server-side from the authenticated principal — and the CLI only *displays* what the host returns. It **never** computes, asserts, or overrides a toggle decision locally, and it does not author config (the superadmin config surface is intentionally not exposed). When the host doesn't serve the surface the command fails closed (exit 2).
 
 ```bash
 openwop toggles list                                             # every toggle's resolved state for you (incl. off)
@@ -443,6 +534,63 @@ openwop a2a task run_abc123 --json    # the durable task's live state
 
 The record is content-free by design (state, `interruptKind`, push config — never run inputs/outputs/credentials); the CLI renders the host's resolved state and never derives one locally. Gated on `capabilities.a2a` (the durable read needs `durableTasks: true`). `task` exit codes: `0` completed · `3` submitted/working/input-required/auth-required · `1` failed/canceled/rejected or error.
 
+## Commerce & sales
+
+Host-extension groups over the reference host's commerce and sales surfaces
+(`/v1/host/openwop-app/{commerce,commerce-connect,promotions,recommendations,dealers,commissions,territories,sales-maps,crm}/…`,
+plus the public visitor routes `public-store`, `public-recommendations`, `partner`,
+`public-book`, `public-sign`, sent without auth). Each group's `--help` lists every
+command with the exact method + path it hits. Org-scoped commands take `--org <orgId>`;
+flags are the host's field names in kebab-case, and `--body`/`--body-file` supply a
+full JSON body. Money amounts pass through exactly in the unit the host's field
+names (`priceMinor`, `priceMajorUnits`, `price` …) — the CLI never computes a total.
+Stripe Connect seller onboarding returns a hosted link only; no card or bank data
+ever passes through the CLI.
+
+```bash
+openwop commerce products list --org org_1 --q shirt
+openwop commerce orders get ord_1 --org org_1 --json
+openwop commerce public products --org org_1               # the anonymous storefront view
+openwop commerce ucp token --org org_1 --client-id c_1 --client-secret-env UCP_SECRET
+openwop commerce-connect seller onboard                     # prints the Stripe-hosted onboarding link
+openwop promotions create --org org_1 --name "10% off 50+" --type cart_threshold --min-spend 50 --reward '{"kind":"percentage","value":10}'
+openwop crm deals list --org org_1
+openwop crm segments members seg_1 --json
+openwop crm public-sign get <token>
+openwop territories models activate mdl_1 --org org_1
+openwop commissions statements pay st_1 --org org_1
+```
+
+Destructive commands (deletes, refunds, cancels, voids) refuse without `--yes`.
+Exit codes: `0` ok · `2` usage error / request rejected · `4` not signed in or not permitted · `1` server error.
+
+## Marketing surfaces
+
+Marketing features on the reference host's `/v1/host/openwop-app/*` extension
+(each is feature-toggled and org-scoped host-side; the CLI renders the host's decision):
+
+```bash
+openwop brand-kits list --org org_1                 # marketing brand kits (NOT `openwop brand`, the app-wide identity)
+openwop campaign-brief briefs create --org org_1 --name "Q4 launch" --objective "Pipeline"
+openwop campaign-connectors kpi --org org_1 --json  # ad-platform performance roll-up
+openwop campaign-intel plan-budget --org org_1 --total-budget-minor 500000 --target-conversions 200 --horizon-days 30
+openwop cdp resolve --type email --value a@example.com
+openwop destination-sync dry-run sync_1 --sample-json '{"email":"a@example.com"}'
+openwop funnels publish fn_1 --org org_1
+openwop webinars list --org org_1
+
+# Anonymous visitor surfaces (no bearer sent) — test what your visitors see:
+openwop public pages org_1
+openwop public sitemap org_1
+openwop public pricing --json
+openwop funnels public view org_1 webinar
+openwop forms public get form_1
+openwop email public click <token>                   # prints the redirect target, does not follow it
+```
+
+Destructive commands (`delete`, a live `campaign-intel apply`, an email
+unsubscribe/preference change) refuse without `--yes`.
+
 ## Config
 
 `~/.openwop/config.json` (or `$OPENWOP_CONFIG_HOME/.openwop/`) stores the host URL, default provider, default model, and credential ref. **API keys are never stored locally.**
@@ -455,6 +603,116 @@ openwop config set defaultModel gpt-4o
 openwop config unset credentialRef
 ```
 
+## Identity & operator administration
+
+Identity, RBAC, tenancy and operator surfaces of the reference host (all under
+`/v1/host/openwop-app/…`; each group's `--help` names the exact path). Super-admin
+surfaces (`vault`, `site-config get|set`, `runtime-posture`, `maintenance`,
+`toggles admin`, `governance`, `billing` import/coupons/seats, `menu-config set tenant`,
+`brand get|set|asset`) fail **closed** with exit `4` and say how to get a super-admin
+principal (`OPENWOP_SUPERADMIN_TENANTS`); `admin …` needs the host admin token.
+Secrets are refs only: vault values, the break-glass token and an anonymous session
+cookie are read from a file or a no-echo prompt, never argv, and never printed. A
+developer key's token is printed once, when the host issues it.
+
+```bash
+openwop orgs invites org_1 create --email jo@acme.com --role editor
+openwop orgs decide --principal user:jo --action runs:read      # exit 0 allowed / 1 denied
+openwop users me security
+openwop vault list
+openwop vault set billing:stripe-key --scope host --value-file ./stripe.key
+openwop developer-keys create --name "CI deploy" --scope runs:write
+openwop environments promote --from dev                          # exit 3 when queued for approval
+openwop billing portal                                           # a Stripe-hosted URL; no card data
+openwop governance egress-rules set --mode allowlist --host api.stripe.com
+openwop toggles admin set crm --status beta                      # read-modify-write
+openwop admin run-retention hold t_acme --reason "legal hold"
+```
+
+Not driven (browser or server-to-server legs): `POST /auth/saml/sso/acs` (IdP form
+post), `POST /billing/webhook` (Stripe-signed), `POST /vault/secrets/:ref/reveal`
+(returns plaintext). Exit codes: `0` ok · `1` server error · `2` usage error / request
+rejected · `3` pending (approval queued, domain not yet live) · `4` not signed in / not permitted.
+
+## Operations & work management
+
+Host-extension groups over the reference host's operations and work surfaces:
+the operator console (`operations` — health, SLO, DLQ, dispatch outbox, webhook
+delivery, saga compensation), the help desk (`service-desk`, plus the anonymous
+`public` widget path), `job-search`, `kicktodo` readiness, your `dashboard`,
+org `bi` metrics, `insights-suite`, a conversation's `intent-ledger`, ambient
+`work-graph` suggestions, `work-selection` ranking, the run `tasks` deck, the
+`model-router` switch, and the demo-only `dev ucp-merchant`. It also fills out
+`strategy` (check-ins, versions, timeline, cadence, decisions, links),
+`priority-matrix` (ideas, scores, intake, evidence, schedules, sessions,
+scenarios, portfolio, federated peers), `projects` (knowledge, memory,
+schedules, visibility, group chat), `goals` (arm / evaluate / record-run),
+`workforces migration set`, `roster activity|check`, `profiles` (pins, avatar,
+personal knowledge), `analytics` (trend, nav telemetry), `marketplace` (feature
+bundles, pack enablement, certify, pack remove/restore) and `connections`
+(delete, inbound webhook binding, provider catalog).
+
+Each group's `--help` is generated from its route table and lists the exact
+method + path every command hits. Flags are the host's field names in kebab-case;
+writes also take `--body`/`--body-file`. Routes that REPLACE a whole document on
+write (job-search steering, strategy cadence, bi metric definitions,
+insights-suite config, profile contact) are read-modify-write, so flags you do not
+pass keep their saved values. Secrets (a federated peer's bearer, an inbound
+signing secret) are read from a file and never printed.
+
+```bash
+openwop operations health --json                       # superadmin
+openwop operations compensation run_42
+openwop service-desk tickets org_1 --status open
+openwop service-desk public send sdk_0123... --text "Hi"   # the anonymous widget path
+openwop strategy check-ins add s_1 kr_1 --value 42 --note "on track"
+openwop priority-matrix ideas score l_1 c_1 --score reach=8 --score effort=3
+openwop projects schedules add p_1 --cron-expr "0 9 * * 1" --workflow-id wf.weekly
+openwop job-search steering set org_1 --roles "Staff Engineer" --remote --daily-cap 5
+openwop bi metrics run org_1 open-deals --bucket week
+openwop tasks deck
+```
+
+Destructive commands refuse without `--yes`. Exit codes: `0` ok · `2` usage error /
+not found / rejected · `4` not signed in or not permitted · `1` server error
+(`kicktodo readiness` also exits `1` when the product reports `degraded`).
+
+## Residual host surfaces
+
+The last host-extension routes the reference host serves, added as three new
+groups — `capability-firewall` (composition rules, recent decisions, a read-only
+`simulate`, and the super-admin platform baseline), `heartbeat` (the host-wide
+agent heartbeat switch, super-admin) and `settings` (your personal token cap,
+reasoning directive and privacy opt-outs) — and as route tables inside existing
+groups: `cms` (scheduled publish/unpublish, version restore, review status, shared
+sections, language settings, translator locale grants, per-locale publish, AI
+section translation, page A/B experiments, and the page SEO head), `email` (sender
+settings, provider status, bounce-webhook configs, campaign engagement), `kb`
+(retrieval config, media-collection ingest, reindex drain/cancel), `forms`
+(templates), `chat-widget tool-catalog`, `consent` (purpose vocabulary, re-admit an
+erased subject), `approvals teams-pref`, `profiles memory-extraction`, `advisors`
+(strategy context, shared knowledge), `campaigns-orchestration`
+(workspace/versions/dispatches), `notifications preferences`, `workflows budget`,
+`kanban column-limit|work-item-run` and `job-search answers`.
+
+Replace-on-write documents (firewall rules, SEO head, heartbeat config,
+notification preferences, personal settings, workflow budget) are
+read-modify-write, so flags you do not pass keep their saved values. The email
+webhook verification secret is read from a file and never printed.
+
+```bash
+openwop capability-firewall simulate --org org_1 --next '{"egress":"safe-fetch"}' --seen '[{"safetyTier":"read"}]'
+openwop cms schedule publish page_1 --org org_1 --at 2026-10-01T09:00:00Z
+openwop cms experiments results page_1 pexp:1 --org org_1
+openwop email webhooks add --org org_1 --provider postmark --verification-secret-file ./secret.txt
+openwop notifications preferences set --quiet-hours --timezone Europe/Oslo
+openwop workflows budget set wf_1 --daily-usd 10 --hard-cap
+openwop settings prefs set --daily-token-cap 200000
+```
+
+Exit codes: `0` ok · `2` usage error / not found / rejected · `4` not signed in or
+not permitted (the super-admin surfaces say so) · `1` server error.
+
 ## Defaults
 
 - Host URL: `--base-url` > `OPENWOP_BASE_URL` > **saved config** (`onboard`'s `~/.openwop/config.json`) > `http://localhost:8080`. After `onboard`, everyday commands use the saved host with no flag.