@openwop/cli 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 David Tufts and openwop contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.

package/README.md

@@ -1,6 +1,26 @@
 # OpenWOP CLI
 
-The OpenWOP CLI is the local control plane for the `apps/workflow-engine` demo app and a lightweight client for OpenWOP-compatible hosts.
+The OpenWOP CLI is the local control plane for the [OpenWOP](https://github.com/openwop/openwop) demo app (`apps/workflow-engine`, live at [app.openwop.dev](https://app.openwop.dev)) and a lightweight client for any OpenWOP-compatible host.
+
+This is the standalone home of the `@openwop/cli` package; it ships independently of the [`openwop/openwop`](https://github.com/openwop/openwop) spec corpus.
+
+## Command groups
+
+The CLI is a host-agnostic **control plane**: every group drives one protocol surface a host advertises, and degrades gracefully when the host doesn't serve it. Full catalog in [`FEATURES.md`](./FEATURES.md); shape + boundaries in [`ARCHITECTURE.md`](./ARCHITECTURE.md); what's planned next in [`ROADMAP.md`](./ROADMAP.md).
+
+| Area | Groups |
+|---|---|
+| **Setup & health** | `onboard` · `doctor` · `demo` · `health` · `capabilities` · `config` |
+| **Run lifecycle** | `runs` · `chat` · `interrupts` · `workflows` · `catalog` · `media` |
+| **Agents & orchestration** | `agents` · `roster` · `org-chart` · `kanban` · `workforces` (`fleet`) |
+| **Governance & safety** | `approvals` · `governance` (`policy`) · `consent` · `toggles` |
+| **Identity & access** | `orgs` · `users` · `profiles` · `auth` (`sso`) |
+| **Extensibility & connections** | `packs` · `mcp` · `connections` (`conn`) · `providers` · `byok` |
+| **Memory & workspace** | `memory` · `workspace` · `prompts` |
+| **Automation & messaging** | `cron` · `webhooks` · `messaging` · `relay` · `notifications` · `notify` |
+| **Observability & admin** | `analytics` (`usage`) · `account` · `admin` · `conformance` |
+
+> **Recent sprint (`[Unreleased]`, slated for `0.3.0`):** 11 new groups + a `cron enable/disable` extension surfaced the host's governance/safety, identity, extensibility, orchestration, and observability surfaces — `approvals`, `governance`, `consent`, `toggles`, `users`, `profiles`, `auth`, `mcp`, `connections`, `workforces`, `analytics`. See [`CHANGELOG.md`](./CHANGELOG.md) for the per-group detail.
 
 ## Install
 
@@ -12,25 +32,21 @@ curl -fsSL https://openwop.dev/install.sh | bash
 
 Or directly: `npm i -g @openwop/cli` (needs Node 22+), then `openwop onboard`.
 
-From a repo clone the CLI is a TypeScript package — build it once, then run the bundled entry (or `npm run cli -- <command>` from the repo root, which builds first):
-
-```bash
-npm --prefix cli install && npm --prefix cli run build   # → cli/dist/openwop.js
-```
-
 ## Quick start
 
 ```bash
-node cli/dist/openwop.js --help
-node cli/dist/openwop.js doctor                 # check prerequisites
-node cli/dist/openwop.js onboard                # guided setup (host + provider + key + model)
-node cli/dist/openwop.js demo start             # boot local backend + frontend (optional)
-node cli/dist/openwop.js demo status
-node cli/dist/openwop.js catalog nodes --search ai
-node cli/dist/openwop.js runs create sample.demo.uppercase --input text=hello --wait
-node cli/dist/openwop.js packs search ads        # browse the signed pack registry
+openwop --help
+openwop doctor                 # check prerequisites
+openwop onboard                # guided setup (host + provider + key + model)
+openwop demo start             # boot local backend + frontend (from inside an openwop checkout)
+openwop demo status
+openwop catalog nodes --search ai
+openwop runs create sample.demo.uppercase --input text=hello --wait
+openwop packs search ads        # browse the signed pack registry
 ```
 
+> The `demo` subcommands operate on an [`openwop/openwop`](https://github.com/openwop/openwop) checkout discovered by walking up from your current directory; run them from inside a clone of that repo.
+
 ## Onboarding
 
 The `onboard` wizard walks you through:
@@ -188,6 +204,222 @@ openwop admin cleanup --status          # read-only liveness probe
 
 `account delete` requires a signed-in user (OIDC bearer). `admin` routes are gated by the host's `OPENWOP_ADMIN_TOKEN` — pass it via `--api-key`.
 
+## Governance
+
+Tenant governance administration (ADR 0028 — a superadmin-gated host extension). The host is the policy authority; the CLI only **renders** its resolved view and never evaluates a policy outcome locally. Because the surface is non-normative (not advertised in `/.well-known/openwop`), the command **fails closed legibly** (exit 2) when a host doesn't expose it.
+
+```bash
+openwop governance policy                        # render stored policy + the host's declared defaults
+openwop governance policy get --json             # raw host view
+openwop governance policy set --action email.send=approval-required --action nudge=disabled
+openwop governance policy set --provider-allowlist anthropic,openai --retention-graph-days 90
+openwop governance audit --prefix governance. --limit 20   # tenant-scoped audit read view
+```
+
+Action kinds are `email.send`, `calendar.invite`, `calendar.reschedule`, `nudge`; policies are `disabled | draft-only | approval-required` (unset kinds fall back to the host's declared default). Aliased as `openwop policy`.
+The `approvals` group drives the host's approval inbox — the human side of "agents propose, humans dispose". A review-mode roster member's heartbeat queues a proposal instead of starting the run; you resolve it here:
+
+```bash
+openwop approvals list --status pending        # the queue (also: approved | rejected)
+openwop approvals get appr_123 --json          # inspect one proposal
+openwop approvals claim appr_123 --note "LGTM" # affirmative sign-off → starts the run
+openwop approvals reject appr_123              # dismiss the proposal (alias: deny)
+```
+
+The host is the authority for every decision: the CLI renders the host's resolved queue and relays your claim/reject — it never decides locally, and fails closed if the host doesn't advertise the surface. Exit codes reflect the verdict so scripts can gate on it: `0` approved · `3` pending · `1` rejected/error. (Distinct from `interrupts`, which are run-level HITL tokens.)
+## Consent (privacy / GDPR)
+
+`consent` drives the host's tenant-scoped, region-aware consent surface (ADR 0020). The host is the authority — the CLI **renders** its resolved view and never computes a consent decision itself; when the org-tenant's `consent` toggle is off the host returns a uniform 404 and the command fails closed with a legible message.
+
+```bash
+openwop consent policy <orgId>                                   # show the tenant policy (defaultMode + regulated regions)
+openwop consent set-policy <orgId> --default-mode opt-out --regulated-region EU --regulated-region UK
+openwop consent records <orgId> --json                           # list all consent records for the tenant
+openwop consent get <orgId> <subjectKey>                         # one subject's record (or none)
+openwop consent erase <orgId> <subjectKey> --yes                 # GDPR erasure (irreversible; --yes required)
+openwop consent public get <orgId> <subjectKey>                  # public, unauthed: a visitor's recorded categories (or the policy default)
+openwop consent public record <orgId> <subjectKey> --category analytics=true --category marketing=false
+```
+
+Exit codes: `0` success · `1` host/HTTP error (including consent not enabled) · `2` usage error.
+
+## 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).
+
+```bash
+openwop mcp ping                                  # liveness probe of the mount
+openwop mcp info --json                           # initialize: server/protocol/capabilities
+openwop mcp tools list                            # workflows exposed as MCP tools
+openwop mcp tools call sample.demo.uppercase --args '{"text":"hi"}'
+openwop mcp resources list                        # + `templates` / `read <uri>`
+openwop mcp prompts get greet --args '{"name":"Ada"}'
+```
+
+`--json` emits the raw JSON-RPC result on any read. JSON-RPC errors surface the host's own message (contract errors → exit 2, host errors → exit 1); a tool whose result is `isError` exits 1.
+
+The `connections` group (alias `conn`) inspects the host's third-party connections and their OAuth client configuration (ADR 0024):
+
+```bash
+openwop connections list                       # connections + status
+openwop connections test conn:abc              # health-probe (exit 0 healthy / 1 not)
+openwop connections authorize google --scope https://www.googleapis.com/auth/calendar --write
+openwop connections oauth-clients list          # host-configured OAuth apps (superadmin)
+```
+
+`authorize` mints a consent URL and **prints it only** — the CLI never completes the OAuth round-trip (the browser + host callback do). **Secrets stay host-side:** client secrets and tokens are never returned, printed, or logged — the CLI runs every response through a recursive redactor before output, surfacing refs and status only.
+## Profiles (self-service persona)
+
+`profiles` drives the host's user-profile surface (ADR 0005): your job title, bio, contact, skills, availability, portfolio, and pinned agents. The host is the authority and the CLI renders its resolved view — reads are visible to any signed-in tenant member, **writes only ever touch your own profile**. Requires a durable signed-in account (bearer via `--api-key`).
+
+```bash
+openwop profiles me                                              # your own profile
+openwop profiles get <userId>                                    # a tenant member's profile (team-visible)
+openwop profiles list                                            # the tenant persona directory
+openwop profiles edit --job-title "Staff Engineer" --availability-status busy --timezone Europe/London
+openwop profiles skills set --skill TypeScript=5 --skill Rust=3  # replace your skill list (proficiency 1..5)
+openwop profiles endorse <userId> <skill>                        # endorse a peer's skill (unendorse to remove)
+openwop profiles pin <rosterId>                                  # pin/unpin an agent to your sidebar
+openwop profiles portfolio add --token <mediaToken>              # attach an image asset (remove <token> to drop)
+openwop profiles activity --limit 10 --status failed             # your run-activity feed
+```
+
+**Boundary:** `profiles` is the persona/skills surface — **not** the user directory (account lifecycle) and **not** RBAC (that's `orgs`). Exit codes: `0` success · `1` host/HTTP error (incl. not found / not signed in) · `2` usage error.
+## Users (identity directory + lifecycle)
+
+`users` drives the host's tenant identity directory and account lifecycle (ADR 0002). It is the durable record of **who** exists in a tenant and whether their account is active — **not** authorization (role/permission membership lives in `orgs`) and **not** editable persona (that's `profiles` / `users me`). The `groups` field is the raw IdP `groups[]` captured at sign-in for the RBAC handoff; it grants nothing by itself. The host is the authority: the surface 404s when not served (fail closed, exit 2), and a disabled account is denied 403.
+
+```bash
+openwop users list                                              # the tenant's users
+openwop users me                                                # your own durable record
+openwop users me --display-name "Ada L."                        # self-serve rename (PATCH /me)
+openwop users create --principal oidc:abc123 --email a@b.dev --group eng --source oidc
+openwop users get <userId> --json
+openwop users update <userId> --display-name "Ada" --group eng --group oncall   # groups replace; --email '' clears
+openwop users disable <userId>                                  # lifecycle (fail-closed control)
+openwop users enable <userId>
+openwop users delete <userId> --yes                             # irreversible; --yes required
+```
+
+Identity `source` is one of `oidc | password | saml | scim | manual`. Exit codes: `0` ok · `1` host error · `2` usage / surface not served / account disabled.
+
+## 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).
+
+```bash
+openwop toggles list                                             # every toggle's resolved state for you (incl. off)
+openwop toggles list --json                                      # raw host view
+openwop toggles get crm.triageAgent                             # one toggle: status / enabled / variant / bindings
+```
+
+Resolved fields are host-authored: `status` (`on | off | beta`), `enabled` (bool), assigned `variant`, and the variant's `bindings` (slot → ref@version). Exit codes: `0` ok · `1` host error · `2` usage / surface not served / unknown toggle.
+
+The `workforces` group (alias `fleet`) drives the host's durable multi-agent orchestration — a *Governed Workforce* is a bundle of agent specs with graduated-autonomy posture and aggregate telemetry:
+
+```bash
+openwop workforces list                         # governed workforces + status
+openwop fleet metrics wf_support                # aggregate telemetry (runs, rates, cost)
+openwop workforces governance wf_support        # autonomy graduation + governance posture
+openwop workforces trace wf_support --q batch_42 # cross-run trace/audit search
+openwop workforces status wf_support production  # request a cutover (host gates on graduation)
+```
+
+This group **composes with** `kanban` (task boards) and `roster` (standing agents) but does not duplicate them — it renders the workforce's governance/metrics view, never re-modelling boards or roster entries. The host is the authority; the CLI renders its resolved view and fails closed if the surface isn't advertised. `status production` is gated host-side on the workforce having graduated to bounded-autonomous (a 409 surfaces legibly); `eval` needs the host's eval suite enabled.
+
+## Enterprise SSO (SAML / SCIM)
+
+`auth` (alias `sso`) drives the host's enterprise identity surface (RFC 0050). The host is the authority; the CLI surfaces **status, public SP metadata, and provisioning results only**. SAML signing certs, SCIM bearer tokens, and client secrets are host-side and are never printed — every response is run through a recursive redactor before output (the public SP metadata XML, meant to be uploaded to your IdP, is the deliberate exception).
+
+```bash
+openwop auth status                                              # which SSO/SCIM profiles this host advertises + whether SAML SSO is live
+openwop auth saml metadata                                       # SP metadata XML to upload to your IdP
+openwop auth saml login-url --return-to /dashboard               # the SP-initiated IdP redirect URL (not followed)
+openwop auth saml validate --idp-url http://localhost:9100/idp --variant valid   # conformance: validate a synthetic-IdP assertion
+openwop auth scim provision --op create-user --user-name jo@acme.com --email jo@acme.com
+```
+
+`auth status` trusts discovery (`/.well-known/openwop`) as authoritative — an unadvertised profile is never probed, so a host's SPA catch-all can't false-report a surface as live. Each surface fails closed with a legible message when the host hasn't configured it.
+
+**Boundary:** `auth` is SSO/SAML/SCIM identity-provider config — **not** the user directory (`users`), RBAC (`orgs`), or BYOK provider credentials (`byok`/`providers`). Exit codes: `0` success (`saml validate`: `0` = authenticated) · `1` host error / not configured (`saml validate`: `1` = rejected) · `2` usage error.
+## Analytics (usage)
+
+`analytics` (alias `usage`) reads a host's org-scoped usage analytics (ADR 0018). The **host** aggregates server-side and gates each org read by RBAC (`workspace:read`) plus the org-tenant's `analytics` toggle; the CLI only **renders** the rollup it returns — it never computes usage locally — and fails closed (exit 2) when analytics isn't served. This is **usage / cost / observability**, deliberately distinct from `governance audit` (the policy-decision log) — hence the alias is `usage`, not `audit`.
+
+```bash
+openwop analytics summary <orgId>                               # aggregate rollup (total, sessions, by-type, top paths, utm)
+openwop usage events <orgId> --json                             # recent raw events (max 100)
+openwop analytics collect <orgId> --session s_abc --type pageview --path /pricing   # public consent-gated beacon
+```
+
+The `collect` beacon is **public** (sent without auth) and consent-gated host-side: a `201` records the event; a `202` honestly reports that analytics consent wasn't granted (nothing recorded). Event type is one of `pageview | event | conversion`. Exit codes: `0` ok · `1` host error · `2` usage / analytics not served / not authorized.
+
+### Reviewable-learning proposals (`proposals`, RFC 0096)
+
+The `proposals` group drives the host's reviewable-learning proposal lifecycle. An agent's learned change lands as an **inert** proposal — a stored artifact draft that does nothing until a human reviews and applies it. The **host** is the authority: `apply` asks it to materialize the byte image last persisted on the proposal (no re-synthesis) and route activation through its advertised mode (e.g. an RFC 0051 approval-gate); the CLI never activates locally.
+
+```bash
+openwop proposals list --state pending                 # the review queue (also --kind <artifactKind>)
+openwop proposals get prop_123 --json                  # inspect one proposal
+openwop proposals revise prop_123 --artifact-json '{"systemPrompt":"…"}'  # edit the draft (never activates)
+openwop proposals apply prop_123                       # host materializes + routes through its activation gate
+openwop proposals reject prop_123 --note "out of scope"
+openwop proposals archive prop_123 --yes               # soft-delete
+```
+
+Capability-gated on `agents.proposals` (advertised in `/.well-known/openwop`); fails closed (exit 1) when the host doesn't serve the surface. Boundary: distinct from `approvals` (the human run-action queue) — proposals are the artifact *drafts* reviewed before they become live behavior. Exit codes (get/apply/reject reflect the verdict): `0` applied · `3` pending (in review) · `1` rejected/archived or error.
+
+### Standing goals (`goals`, RFC 0097)
+
+The `goals` group drives the host's standing goals — an objective the host pursues across runs until a **judge** (RFC 0090) verdicts it satisfied or a **bound** (RFC 0058) stops it. **Completion is the judge's verdict**: there is no `complete`/`satisfy` verb and the CLI never sets `satisfied` — you cannot declare victory from the client.
+
+```bash
+openwop goals list --state active                      # the goal list (also satisfied | escalated | bound-exceeded | paused)
+openwop goals get goal_123 --json                      # inspect (objective, judge, continuation, bounds, iterations)
+openwop goals create --objective "Keep the triage backlog under 20" \
+  --judge verifier --continuation schedule --max-iterations 50 --max-cost 5.00 --timeout-ms 600000
+openwop goals pause goal_123                            # suspend continuation (resume to restart)
+openwop goals abandon goal_123 --yes                   # close the goal
+```
+
+A bounds-less goal is rejected `422` when the host advertises `requiresBounds` — pass `--max-iterations`/`--max-cost`/`--timeout-ms`. The create body maps to the Goal entity shape (`completion.check` / `continuation.mode` / `bounds.{maxLoopIterations,runTimeoutMs,maxCostUsd}`). Capability-gated on `agents.goals`; fails closed (exit 1) when the surface isn't served. Boundary: a goal is **not** an RFC 0068 commitment — it *uses* a commitment/schedule/heartbeat as a continuation arm and adds a judge loop + termination guarantee. Exit codes: `0` satisfied · `3` escalated or still open (active/paused) · `1` bound-exceeded/abandoned or error.
+
+### Agent-platform portability — `export` / `import` (RFC 0098)
+
+Move reusable estate (agents, packs, schedules, rosters, templates) between hosts as a portable bundle. **Secrets are refs, never values:** the bundle carries only `secretsToRebind` references — never credential material — and the host rejects a bundle that smuggles a literal credential before it applies anything. Always **dry-run first**.
+
+```bash
+openwop export --json                                  # the full refs-only bundle
+openwop export --kinds agent --kinds schedule --out estate.json   # filtered, to a file
+openwop import estate.json --dry-run                   # preview: creates/updates/skips/conflicts (no writes)
+openwop import estate.json                             # apply (idempotent; entities re-owned to you)
+```
+
+The CLI runs every response through a secret redactor before printing or writing to disk (defense-in-depth on top of the host's refs-only guarantee). Capability-gated on top-level `portability`; fails closed when the host doesn't serve the surface. This subsumes the old SPA-only `migrate-tenant` bootstrap. Import exit codes: `0` applied (or a clean dry-run plan) · `2` the plan has conflicts (nothing overwritten) · `1` error — a literal credential or `dependsOn` cycle (422), or no import scope (403).
+
+### External-event trigger subscriptions (`triggers`, RFC 0099)
+
+The `triggers` group drives the host's **normative** trigger bridge: a subscription binds an external source (`webhook` / `email` / `form`) to a workflow the caller can start, and a verified inbound event then starts a run with the event as `ctx.triggerData`.
+
+```bash
+openwop triggers register --source webhook --workflow wf_intake --dedup --verification required
+openwop triggers list --state active
+openwop triggers get sub_123 --json
+```
+
+`register` returns the created subscription plus its source `binding` (the ingest URL/address). A webhook **binding secret is shown once** — store it then; the CLI never persists it and re-reads return only the `secretFingerprint`. Capability-gated on `capabilities.triggerBridge` (register also honesty-gates on `triggerBridge.ingestion.externalSources`); fails closed when absent. Exit codes: `0` active · `3` paused · `1` failed/dead-lettered or error.
+
+### Async / durable A2A tasks (`a2a`, RFC 0100)
+
+When a host advertises `capabilities.a2a.durableTasks`, every backing run has a durable `A2ATaskState` (taskId === runId) readable after the caller disconnects.
+
+```bash
+openwop a2a status                    # what the host advertises (supported/streaming/push/durableTasks)
+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.
+
 ## 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.**
@@ -220,3 +452,30 @@ Exit codes:
 - `2` — user-fixable error (unknown command, missing argument, 4xx response).
 
 The CLI is dependency-light by design. It uses Node built-ins so contributors can operate the demo app without installing another command framework.
+
+## Development
+
+This repo is a self-contained TypeScript package (the build is `esbuild`; it does not depend on the spec corpus). Requires Node ≥ 20.
+
+```bash
+npm ci
+npm run typecheck     # tsc --noEmit (strict, noImplicitAny)
+npm run build         # → dist/openwop.js (esbuild bundle)
+npm test              # build + node --test test/*.test.mjs
+node dist/openwop.js --help   # run the local build
+```
+
+CI (`.github/workflows/ci.yml`) runs typecheck + tests on every push and PR.
+
+## Releasing
+
+The package publishes to npm via an OIDC **trusted publisher** with provenance — no tokens in CI. Pushing a `vX.Y.Z` tag triggers `.github/workflows/publish.yml`, which builds, tests, and publishes `@openwop/cli@X.Y.Z` (idempotent: it skips if that version is already on npm).
+
+1. Bump `version` in `package.json` **and** `VERSION` in `src/constants.ts` (kept in lockstep), add a `CHANGELOG.md` entry.
+2. Commit (DCO-signed), then tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+
+> **One-time setup (maintainer):** register this repo + `publish.yml` as the trusted publisher for `@openwop/cli` on npmjs.com (package → Settings → Trusted Publishers). The package was previously published from `openwop/openwop`; the binding must be repointed here before the first release.
+
+## Contributing
+
+Commits must be [DCO](https://developercertificate.org/) signed off (`git commit -s`). Follow [Conventional Commits](https://www.conventionalcommits.org/). Licensed under Apache-2.0 (see [`LICENSE`](./LICENSE)).