npm - octwin-cli - Versions diffs - 0.3.0 → 0.6.0 - Mend

octwin-cli 0.3.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/CHANGELOG.md +67 -1
package/README.md +214 -210
package/dist/index.js +731 -255
package/dist/lib/args-check.js +11 -10
package/dist/lib/builtin-check.js +130 -0
package/dist/lib/declaration-check.js +192 -0
package/dist/lib/entity-check.js +150 -0
package/dist/lib/kb-index.js +214 -0
package/dist/lib/kb-path.js +17 -0
package/dist/lib/kb-symbols.js +271 -0
package/dist/lib/render-check.js +13 -12
package/dist/lib/template-check.js +107 -0
package/dist/lib/validate.js +33 -4
package/dist/lib/yaml-pos.js +29 -0
package/package.json +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,72 @@ Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucket
 **Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
 repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
+## [0.6.0] - 2026-08-09
+### Changed
+- **`octwin cases` is now `octwin work`, and it works again.** The platform's work-inbox
+  consolidation (2026-08-08) replaced the case-only surface with `/work` over every entity a pack
+  declares worked, and renamed the scopes to `work:read`/`work:write` — which left every `octwin
+  cases` call a silent 404 in a published CLI. The command family is renamed to match the platform:
+  `octwin work [recordId] [--queues]`, with writes `assign` / `note` / `decide` (the declared
+  operator actions, `--dry-run` previews) and `stage <id> --to <s>` riding the one platform-wide
+  stage verb (`POST …/xrm/records/:id/stage`, needs `records:write`). `transition` is gone with the
+  route it called.
+- **`octwin orders transition` rides the same stage verb.** `POST …/orders/:ref/transition` was
+  retired server-side in the same consolidation; the CLI now resolves the order's record id from the
+  detail read and moves the stage through `…/xrm/records/:id/stage` (scope: `records:write`).
+### Added
+- **A route guard so this cannot rot silently again**: `src/lib/cli-routes.test.ts` extracts every
+  `/api/self/**` URL the CLI builds and asserts it (method included) against the platform's dumped
+  route table — the gap that let both breakages above ship.
+## [0.5.1] - 2026-08-01
+### Fixed
+- **`validate --remote` blamed the platform's version for a bad `--project`.** Every 404 from
+  `POST /api/self/p/packs/validate` printed *"this platform has no /packs/validate endpoint yet
+  (older version)"*. That was accurate when the route resolved nothing, but it now resolves the
+  tenant and project **before** validating — and an unknown project, or one outside a token's pin,
+  answers 404 by design. So a typo in `--project` sent you looking for a version mismatch instead of
+  at the flag. The two cases are now told apart by the response **body**, not the status: a missing
+  route is Fastify's `error: 'Not Found'` and keeps the old wording, while the platform's own
+  `project '<slug>' not found under tenant` is printed as-is, with the flags to check.
+## [0.5.0] - 2026-08-01
+### Added
+- **`octwin seed [--pack <packId>]`** — apply the pack's demo/reference data to the project it is
+  installed on, without redeploying: `xrm.yaml` `demo:` records + scheduling availability, the
+  commerce catalog, and the demo operator topology. Reports what **each kind** produced.
+  Previously seeding was reachable only as `deploy --seed`, because the platform's seed endpoint was
+  keyed on an install id, guarded platform-admin, and carried no tenant/project segments — so the
+  `/api/self/**` surface could not reach it and a `pack:deploy` token never could. Re-seeding meant
+  a full redeploy or asking an operator. Idempotent and cheap to re-run: records upsert, and
+  existing media is REUSED rather than regenerated, so a second pass reports zero images.
+## [0.4.0] - 2026-08-01
+### Added
+- **`octwin projects create` / `octwin projects rm`** — a **disposable end-to-end environment** from
+  the CLI, which is what marketplace developers have been missing. `octwin deploy` has always needed
+  a project that already existed and the CLI could only *list* them, so standing up a throwaway
+  full deployment meant opening the console or asking an operator. Now:
+  ```bash
+  octwin projects create "Scratch"          # → slug `scratch`
+  octwin deploy --project scratch --seed    # publish + install + demo data
+  octwin chat "hi" --project scratch        # talk to it (--script for a whole conversation)
+  octwin projects rm scratch --yes          # throw it away
+  ```
+  A throwaway environment is deliberately **not a special kind of thing** — it is an ordinary
+  project in your own workspace, so it inherits your plan, entitlements, RBAC and teardown with no
+  separate lifecycle. `create` derives the URL slug from the name (`--slug` pins one, `--pack`
+  installs an already-published pack). `rm` is a HARD delete — the project and everything cascading
+  from it, no undo, not the same as archiving — so **without `--yes` it only prints what would be
+  destroyed**, making the dry run the default; the impact list is derived from `pg_constraint`, the
+  same payload the console's confirm dialog renders. Both need `projects:write`, which a
+  `pack:deploy` token does **not** confer — the CLI names that scope in the 403 hint.
 ## [0.3.0] - 2026-07-31
 ### Added
@@ -191,7 +257,7 @@ repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut th
   **flags → env (`PACK_PLATFORM_URL`/`PACK_TENANT`/`PACK_PROJECT`/`PACK_TOKEN`) → saved login**.
   An existing credentials file simply has no `default_url` until the next `octwin login` — which is
   exactly what the "no platform url" error now tells you to run. CI is unaffected (it passes
-  `PACK_PLATFORM_URL` + `PACK_TOKEN` as env and never had a `pack.json`).
+  `PACK_PLATFORM_URL` + `PACK_TOKEN` as env and never had a `pack.json` — that file is retired).
 ## [0.1.17] - 2026-07-27

package/README.md CHANGED Viewed

@@ -1,210 +1,214 @@
-# octwin-cli
-> The **Octwin** external-pack developer CLI — scaffold, validate, deploy, and manage pure-YAML packs on your own tenant. By **CEQUENS**.
-[![npm version](https://img.shields.io/npm/v/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
-[![license](https://img.shields.io/npm/l/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
-[![node](https://img.shields.io/node/v/octwin-cli.svg)](https://nodejs.org)
-Octwin is a pack-pluggable conversational-agent platform for WhatsApp and web. A **pack** is a
-self-contained bot domain — its agent, conversation flows, prompts, and data model — declared
-entirely in YAML. `octwin-cli` lets you build a **pure-YAML pack** in your own repo and deploy it
-to a running Octwin platform to test live on your own tenant: no platform checkout, no build step,
-and nothing untrusted to run (a pure-YAML pack is declarative data, so the platform can safely run
-it alongside other tenants).
-> The npm package is **`octwin-cli`**; the command it installs is **`octwin`**.
-## Requirements
-- **Node.js ≥ 20**
-- Access to an **Octwin platform** (its base URL), a **tenant** (your workspace) on it, and a
-  **deploy token** (generated in the Octwin console — see [Authentication](#authentication)).
-## Install
-```bash
-# zero-install — always the latest version
-npx octwin-cli@latest <command>
-# …or install the `octwin` command globally
-npm install -g octwin-cli
-octwin <command>
-```
-## Quick start
-```bash
-# 1. Scaffold a standalone pure-YAML pack (this is your repo)
-octwin init ./my-pack --id my-pack --description "My business bot"
-cd ./my-pack
-git init && git add -A && git commit -m "init pack"
-# 2. Author it — edit manifest.yaml, flows/tools/main.flow.yaml (+ its locale),
-#    and prompts/identity.md. Everything is pure YAML.
-# 3. Point it at your platform — one command, no config file
-#    (Octwin console → your workspace → API tokens → Generate)
-octwin login --url https://your-octwin.example.com --token oct_…
-# 4. Validate → deploy → confirm it's live
-octwin validate
-octwin deploy --seed        # --seed also loads any demo data the pack declares
-octwin status               # "✓ live and current" once it's warm
-# 5. Chat with it on your tenant (web widget / console test page). Edit and
-#    `octwin deploy` again — a redeploy hot-loads with no restart.
-```
-## Commands
-| Command | What it does |
-| --- | --- |
-| `octwin init <dir>` | Scaffold a new pure-YAML pack into `<dir>` (writes a starter `manifest.yaml`, flow, prompt, `.gitignore` and `README.md` — pack content only). Options: `--id`, `--description`, `--display-name`. |
-| `octwin validate` | Check the pack locally (structure + pure-YAML rules). `--remote` additionally runs the platform's **flow lint** — conventions the schema can't express, like an `assign:` whose value is a quoted literal, or a `$t()` key with no namespace. The lint needs a template-expanded `FlowDef`, which only the server builds, so it is a `--remote`-only check; a local ✓ does not cover it. |
-| `octwin login` | Save a deploy token for a platform URL **and make that URL the default target** (both stored in `~/.octwin/credentials.json`). `--url`, `--token`. |
-| `octwin whoami` | Verify the saved/passed token is valid for a tenant. `--url`, `--tenant`. |
-| `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. Reports the **marketplace-listing verdict** when the manifest carries `listing.public: true`. |
-| `octwin status` | Report what the platform has live for this pack — installed version, the **content sha** the instance loaded vs. the one the catalog holds (a redeploy of the *same* version changes it), its flows, and whether it is live on the public marketplace. |
-| `octwin pull <packId>` | Write a **deployed** pack's source back to disk — the inverse of `deploy`, and how a pack pushed from one machine is recovered. Defaults to the version installed on the target project; `--version` overrides, `--dir` defaults to `./<packId>`, a non-empty dir needs `--force`. You may pull a pack your tenant **owns**. |
-| `octwin chat "msg"` | Drive a turn through the dev web channel and print **every render with its tap ids**. `--as <handle>` picks the test user; `--tap "<tap-id>"` presses a rendered button/list row; `--json` dumps the raw envelopes. |
-| `octwin logs` | List recent conversations (handle, status, last activity; `--as` filters), or show one conversation's full event timeline — including what each turn rendered. `--json` for raw payloads. |
-| `octwin records` | Inspect the pack's XRM data (needs a `records:read` token). No args = list entities. |
-| `octwin cases` | Inspect casework (support tickets): the inbox, one case + its timeline and decisions, or `--queues` for queue keys + open counts. |
-| `octwin projects` | The `--project <slug>` values this token can name, with the plan's project cap. `--archived` includes archived ones. A `pack:deploy` token reaches it — it names a project in every other command, so this turns "guess the slug" into "read the list". |
-| `octwin agents` | The agent roster with each agent's **effective** model / history window and **which layer set it** (project override → platform default → pack manifest) — an operator platform default can override what your manifest declares. `--prompt` prints the exact system prompt the LLM sees. Needs `agents:read`. |
-| `octwin orders` | The orders a conversation produced. No args = the list; with a `reference_id` = line items, the subtotal/tax/shipping/discount/total breakdown, `payment_ref`, and the allowed transitions. Needs `orders:read` + the `orders` plan feature. |
-| `octwin analytics` | Stage-by-stage conversion for **any** entity declared with a `pipeline:` (`--overview` / `--milestones` / `--trends` / `--cost`; `--stage <id>` lists the records currently at a stage). Needs `records:read`. |
-| `octwin catalog` | Commerce products with price / availability / stock, plus the WhatsApp catalog binding. `--readiness` runs the Meta Graph checklist. Needs `catalog:read` + the `catalog` plan feature. |
-| `octwin scheduling` | The scheduling engine's state, or `--slots <resourceRecordId>` for the slots one bookable resource actually computes — how you verify the availability rules `deploy --seed` created. Needs `scheduling:read`. |
-| `octwin media generate "<prompt>"` | AI-generate an image, store it as a public asset, and print its `MEDIA-` handle + serve URL. `--out` downloads the bytes (WhatsApp renders only `.png`/`.jpg`); `--size`; `--json`. Pairs with `octwin chat --media` to drive media-collect flows. Needs `media:generate`. |
-| `octwin platform-kb pull` | Pull the platform's capability reference into `.octwin/platform-kb/` for the **`octwin-pack`** Claude Code authoring plugin: guides as markdown, plus **one JSON file per capability** (`primitives/record_list.json`, `render-intents/carousel.json`, `declarations/xrm.json`, …) and an **`INDEX.md`** mapping every entry to its file — so a lookup is a small targeted read, not a whole catalog. |
-| `octwin test` | Alias for `octwin validate --remote` — the platform's full manifest + flow-DSL check. |
-| `octwin feedback` | Submit this pack's `FEEDBACK.md` to the platform team, with the pack version, your CLI version and the `content_hash` of the capability reference you pulled — the two facts that separate a real platform gap from something already fixed or a stale KB. |
-| `octwin help` | Show usage. Every subcommand also answers `--help`. |
-### Writing, not just reading
-Every read command above has a write half behind a **leading verb**, so `octwin cases` reads and
-`octwin cases note <id> "…"` writes. Each needs the matching `:write` scope — `octwin <cmd> --help`
-lists the verbs and their exact flags.
-| Command | Verbs |
-| --- | --- |
-| `octwin records` | `create <entity> --set k=v` · `patch <id> --entity <e>` · `stage <id> --to <s>` · `note <id> "…"` · `tasks` · `task complete <id>` |
-| `octwin cases` | `assign <id> --to user:<uuid>\|none` · `note` · `transition <id> --to <status>` · `decide <id> --action <a> [--dry-run]` |
-| `octwin orders` | `transition <ref> --to <status>` · `refund <ref> --force` |
-| `octwin catalog` | `availability <sku> --to "in stock"` · `stock <sku> [--set-on-hand n]` |
-| `octwin scheduling` | `rules --resource <id>` · `rule add\|rm` · `exception add\|rm` |
-| `octwin agents` | `set <ref> [--model m] [--enable-tool t] [--disable-tool t]` |
-`--set k=v` coerces JSON scalars (`--set rating=4.5` sends a number); `--fields-json` takes anything
-nested. Destructive verbs want `--force` rather than a prompt — the CLI is non-interactive by
-design. `cases decide --dry-run` previews the customer-facing copy and the resulting status without
-committing, and needs only `cases:read`.
-Every command that talks to the platform accepts `--dir <path>` (the pack directory; defaults to
-the current directory) plus the target overrides `--url` / `--tenant` / `--project` / `--token`.
-### Debugging a live conversation
-The platform keeps **one open conversation per `--as` handle**, so consecutive `octwin chat` calls
-with the same handle **continue the same conversation** — agent memory, suspended flows, and all:
-```bash
-octwin chat "hi" --as tester1                 # turn 1 — prints the menu with each row's tap id
-octwin chat --tap "t:invoke:my-flow:x=1" --as tester1   # turn 2 — press a rendered row
-octwin chat "3 bedrooms" --as tester1         # turn 3 — free text into the running flow
-octwin logs --as tester1                      # find the conversation, then:
-octwin logs <conversationId>                  # the full timeline (taps, renders, tool events)
-```
-### Reading back the state your pack created
-`chat`/`logs` show what the bot *said*; these show what it *did*. A 401/403 on any of them names the
-token scope (and plan feature) that command needs, so you can mint a wider token instead of guessing.
-```bash
-octwin agents                                 # effective model per agent + which layer set it
-octwin agents my-pack::assistant --prompt     # the exact system prompt the LLM sees
-octwin orders                                 # then: octwin orders <reference_id>
-octwin analytics                              # then: octwin analytics <entity> [--stage <id>]
-octwin catalog                                # products + stock + the WhatsApp binding
-octwin scheduling --slots <resourceRecordId>  # the slots your availability rules compute
-```
-Three things worth knowing when you read the output:
-- **A `pending` payment is usually correct.** The forward payment lifecycle is **webhook-owned**, and a
-  workspace with no gateway runs the credential-free `manual` driver — so `payment_request` takes its
-  `empty` port and your flow should confirm pay-on-delivery. `octwin orders <ref>` says this inline.
-- **Your declared model may not be the one running.** An operator platform default overrides the pack
-  manifest; `octwin agents` is where that becomes visible.
-- **An empty funnel has two causes** — the entity has no `pipeline:`, or your token's role has no `view`
-  grant on `record.<entity>`. The command prints both rather than a bare "no data".
-## Configuration
-**`octwin login` is the configuration.** There is no config file in your pack — a pack directory
-holds pack content and nothing else, so the same repo deploys from any machine:
-```bash
-octwin login --url https://your-octwin.example.com --token oct_…
-```
-That stores the token *and* makes the URL your default target, in `~/.octwin/credentials.json`:
-```jsonc
-{
-  "default_url": "https://your-octwin.example.com",  // set by the last `octwin login`
-  "https://your-octwin.example.com": "oct_…"          // token, keyed by platform url
-}
-```
-Tenant and project need no setting at all — the **token carries its own tenant**, plus an optional
-project pin. `--tenant` / `--project` exist only as overrides (a multi-workspace human, or an
-unpinned token that must name a project).
-Each setting resolves **flag → environment variable → saved login**:
-| Setting | Flag | Env var | Saved login |
-| --- | --- | --- | --- |
-| Platform URL | `--url` | `PACK_PLATFORM_URL` | `default_url` |
-| Deploy token | `--token` | `PACK_TOKEN` | token for that URL |
-| Tenant slug *(override)* | `--tenant` | `PACK_TENANT` | — *(from the token)* |
-| Project slug *(override)* | `--project` | `PACK_PROJECT` | — *(from the token's pin)* |
-For **CI**, skip `login` entirely and pass `PACK_PLATFORM_URL` + `PACK_TOKEN` as environment
-variables (add `PACK_PROJECT` only if the token isn't pinned).
-## Authentication
-You authenticate with a tenant-scoped **deploy token** (prefixed `oct_…`) — not a password and not
-an operator token. Generate it in the Octwin console (**your workspace → API tokens → Generate**).
-It is **least-privilege** (scope `pack:deploy`): it can deploy packs to your tenant but cannot
-manage members, billing, or other tenants, and it is revocable at any time.
-Add the optional **`media:generate`** scope to let a `--seed` deploy AI-generate seed images
-(for a demo record field like `photo: "generate:<prompt>"`); without it, such fields are seeded as
-text only.
-## What a pack may contain
-A pack is **pure declarative data** — `.yaml` / `.yml` / `.md` / `.sql` / `.json` only. Executable
-code (`.ts`/`.js`), HTTP routes, DB clients, and custom primitives are **not** allowed (this is what
-makes an external pack safe to run on a shared platform; the server enforces it on deploy). For
-domain records, use Octwin's first-class storage modules — **XRM** (records with stage pipelines),
-**catalog** (products), or **casework** (tickets) — declared in `xrm.yaml` and `worklist.yaml`, so a
-pack needs **no database of its own**. (Casework rides `worklist.yaml`'s `work.<entity>` block;
-there is no ~~`cases.yaml`~~ grammar. `octwin platform-kb pull` ships the authoritative list of
-declaration files — read its `INDEX.md` rather than this paragraph.)
-## Links
-- **npm:** <https://www.npmjs.com/package/octwin-cli>
-- **Command help:** `octwin help` (each subcommand also answers `--help`)
-- **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
-## License
-[MIT](./LICENSE) © CEQUENS
+# octwin-cli
+> The **Octwin** external-pack developer CLI — scaffold, validate, deploy, and manage pure-YAML packs on your own tenant. By **CEQUENS**.
+[![npm version](https://img.shields.io/npm/v/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
+[![license](https://img.shields.io/npm/l/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
+[![node](https://img.shields.io/node/v/octwin-cli.svg)](https://nodejs.org)
+Octwin is a pack-pluggable conversational-agent platform for WhatsApp and web. A **pack** is a
+self-contained bot domain — its agent, conversation flows, prompts, and data model — declared
+entirely in YAML. `octwin-cli` lets you build a **pure-YAML pack** in your own repo and deploy it
+to a running Octwin platform to test live on your own tenant: no platform checkout, no build step,
+and nothing untrusted to run (a pure-YAML pack is declarative data, so the platform can safely run
+it alongside other tenants).
+> The npm package is **`octwin-cli`**; the command it installs is **`octwin`**.
+## Requirements
+- **Node.js ≥ 20**
+- Access to an **Octwin platform** (its base URL), a **tenant** (your workspace) on it, and a
+  **deploy token** (generated in the Octwin console — see [Authentication](#authentication)).
+## Install
+```bash
+# zero-install — always the latest version
+npx octwin-cli@latest <command>
+# …or install the `octwin` command globally
+npm install -g octwin-cli
+octwin <command>
+```
+## Quick start
+```bash
+# 1. Scaffold a standalone pure-YAML pack (this is your repo)
+#    `--id` is a BARE name — the platform prefixes your workspace at deploy, so
+#    `my-pack` published by `acme` becomes `acme.my-pack` in the catalog. Take the
+#    obvious name; ids only collide within a workspace.
+octwin init ./my-pack --id my-pack --description "My business bot"
+cd ./my-pack
+git init && git add -A && git commit -m "init pack"
+# 2. Author it — edit manifest.yaml, flows/tools/main.flow.yaml (+ its locale),
+#    and prompts/identity.md. Everything is pure YAML.
+# 3. Point it at your platform — one command, no config file
+#    (Octwin console → your workspace → API tokens → Generate)
+octwin login --url https://your-octwin.example.com --token oct_…
+# 4. Validate → deploy → confirm it's live
+octwin validate
+octwin deploy --seed        # --seed also loads any demo data the pack declares
+octwin status               # "✓ live and current" once it's warm
+# 5. Chat with it on your tenant (web widget / console test page). Edit and
+#    `octwin deploy` again — a redeploy hot-loads with no restart.
+```
+## Commands
+| Command | What it does |
+| --- | --- |
+| `octwin init <dir>` | Scaffold a new pure-YAML pack into `<dir>` (writes a starter `manifest.yaml`, flow, prompt, `.gitignore` and `README.md` — pack content only). Options: `--id`, `--description`, `--display-name`. |
+| `octwin validate` | Check the pack locally (structure + pure-YAML rules). `--remote` runs **the same validation the platform runs to load your pack** — every declaration file (`xrm.yaml`, `scheduling.yaml`, `worklist.yaml`, `roles.yaml`, `automation.yaml`, `integrations.yaml`, `surveys.yaml`, `taps.yaml`, `commands.yaml`, `journeys/`, `messages.<lang>.yaml`), the cross-file checks between them, and the **flow lint** — conventions the schema can't express, like an `assign:` whose value is a quoted literal or a `$t()` key with no namespace. These need template expansion and the platform's own schemas, which only the server has, so a local ✓ does not cover them. A `--remote` ✓ and a successful deploy are now the same answer by construction, not by convention. |
+| `octwin login` | Save a deploy token for a platform URL **and make that URL the default target** (both stored in `~/.octwin/credentials.json`). `--url`, `--token`. |
+| `octwin whoami` | Verify the saved/passed token is valid for a tenant. `--url`, `--tenant`. |
+| `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. Reports the **marketplace-listing verdict** when the manifest carries `listing.public: true`. |
+| `octwin status` | Report what the platform has live for this pack — installed version, the **content sha** the instance loaded vs. the one the catalog holds (a redeploy of the *same* version changes it), its flows, and whether it is live on the public marketplace. |
+| `octwin pull <packId>` | Write a **deployed** pack's source back to disk — the inverse of `deploy`, and how a pack pushed from one machine is recovered. Defaults to the version installed on the target project; `--version` overrides, `--dir` defaults to `./<packId>`, a non-empty dir needs `--force`. You may pull a pack your tenant **owns**. |
+| `octwin chat "msg"` | Drive a turn through the dev web channel and print **every render with its tap ids**. `--as <handle>` picks the test user; `--tap "<tap-id>"` presses a rendered button/list row; `--json` dumps the raw envelopes. |
+| `octwin logs` | List recent conversations (handle, status, last activity; `--as` filters), or show one conversation's full event timeline — including what each turn rendered. `--json` for raw payloads. |
+| `octwin records` | Inspect the pack's XRM data (needs a `records:read` token). No args = list entities. |
+| `octwin cases` | Inspect casework (support tickets): the inbox, one case + its timeline and decisions, or `--queues` for queue keys + open counts. |
+| `octwin projects` | The `--project <slug>` values this token can name, with the plan's project cap. `--archived` includes archived ones. A `pack:deploy` token reaches it — it names a project in every other command, so this turns "guess the slug" into "read the list". |
+| `octwin agents` | The agent roster with each agent's **effective** model / history window and **which layer set it** (project override → platform default → pack manifest) — an operator platform default can override what your manifest declares. `--prompt` prints the exact system prompt the LLM sees. Needs `agents:read`. |
+| `octwin orders` | The orders a conversation produced. No args = the list; with a `reference_id` = line items, the subtotal/tax/shipping/discount/total breakdown, `payment_ref`, and the allowed transitions. Needs `orders:read` + the `orders` plan feature. |
+| `octwin analytics` | Stage-by-stage conversion for **any** entity declared with a `pipeline:` (`--overview` / `--milestones` / `--trends` / `--cost`; `--stage <id>` lists the records currently at a stage). Needs `records:read`. |
+| `octwin catalog` | Commerce products with price / availability / stock, plus the WhatsApp catalog binding. `--readiness` runs the Meta Graph checklist. Needs `catalog:read` + the `catalog` plan feature. |
+| `octwin scheduling` | The scheduling engine's state, or `--slots <resourceRecordId>` for the slots one bookable resource actually computes — how you verify the availability rules `deploy --seed` created. Needs `scheduling:read`. |
+| `octwin media generate "<prompt>"` | AI-generate an image, store it as a public asset, and print its `MEDIA-` handle + serve URL. `--out` downloads the bytes (WhatsApp renders only `.png`/`.jpg`); `--size`; `--json`. Pairs with `octwin chat --media` to drive media-collect flows. Needs `media:generate`. |
+| `octwin platform-kb pull` | Pull the platform's capability reference into `.octwin/platform-kb/` for the **`octwin-pack`** Claude Code authoring plugin: guides as markdown, plus **one JSON file per capability** (`primitives/record_list.json`, `render-intents/carousel.json`, `declarations/xrm.json`, …) and **three maps** — `INDEX.md` (the corpus, by family and size), `SYMBOLS.md` (every name → its exact file; grep this), `OUTLINE.md` (every heading with its line number). **No token needed** — the reference is served anonymously. `--if-stale` skips the download when your copy is current (cheap enough for every session); `--check` writes nothing and exits 0 current / 2 stale / 1 could-not-tell. |
+| `octwin test` | Alias for `octwin validate --remote` — the platform's full manifest + flow-DSL check. |
+| `octwin feedback` | Submit this pack's `FEEDBACK.md` to the platform team, with the pack version, your CLI version and the `content_hash` of the capability reference you pulled — the two facts that separate a real platform gap from something already fixed or a stale KB. |
+| `octwin help` | Show usage. Every subcommand also answers `--help`. |
+### Writing, not just reading
+Every read command above has a write half behind a **leading verb**, so `octwin cases` reads and
+`octwin cases note <id> "…"` writes. Each needs the matching `:write` scope — `octwin <cmd> --help`
+lists the verbs and their exact flags.
+| Command | Verbs |
+| --- | --- |
+| `octwin records` | `create <entity> --set k=v` · `patch <id> --entity <e>` · `stage <id> --to <s>` · `note <id> "…"` · `tasks` · `task complete <id>` |
+| `octwin cases` | `assign <id> --to user:<uuid>\|none` · `note` · `transition <id> --to <status>` · `decide <id> --action <a> [--dry-run]` |
+| `octwin orders` | `transition <ref> --to <status>` · `refund <ref> --force` |
+| `octwin catalog` | `availability <sku> --to "in stock"` · `stock <sku> [--set-on-hand n]` |
+| `octwin scheduling` | `rules --resource <id>` · `rule add\|rm` · `exception add\|rm` |
+| `octwin agents` | `set <ref> [--model m] [--enable-tool t] [--disable-tool t]` |
+`--set k=v` coerces JSON scalars (`--set rating=4.5` sends a number); `--fields-json` takes anything
+nested. Destructive verbs want `--force` rather than a prompt — the CLI is non-interactive by
+design. `cases decide --dry-run` previews the customer-facing copy and the resulting status without
+committing, and needs only `cases:read`.
+Every command that talks to the platform accepts `--dir <path>` (the pack directory; defaults to
+the current directory) plus the target overrides `--url` / `--tenant` / `--project` / `--token`.
+### Debugging a live conversation
+The platform keeps **one open conversation per `--as` handle**, so consecutive `octwin chat` calls
+with the same handle **continue the same conversation** — agent memory, suspended flows, and all:
+```bash
+octwin chat "hi" --as tester1                 # turn 1 — prints the menu with each row's tap id
+octwin chat --tap "t:invoke:my-flow:x=1" --as tester1   # turn 2 — press a rendered row
+octwin chat "3 bedrooms" --as tester1         # turn 3 — free text into the running flow
+octwin logs --as tester1                      # find the conversation, then:
+octwin logs <conversationId>                  # the full timeline (taps, renders, tool events)
+```
+### Reading back the state your pack created
+`chat`/`logs` show what the bot *said*; these show what it *did*. A 401/403 on any of them names the
+token scope (and plan feature) that command needs, so you can mint a wider token instead of guessing.
+```bash
+octwin agents                                 # effective model per agent + which layer set it
+octwin agents my-pack::assistant --prompt     # the exact system prompt the LLM sees
+octwin orders                                 # then: octwin orders <reference_id>
+octwin analytics                              # then: octwin analytics <entity> [--stage <id>]
+octwin catalog                                # products + stock + the WhatsApp binding
+octwin scheduling --slots <resourceRecordId>  # the slots your availability rules compute
+```
+Three things worth knowing when you read the output:
+- **A `pending` payment is usually correct.** The forward payment lifecycle is **webhook-owned**, and a
+  workspace with no gateway runs the credential-free `manual` driver — so `payment_request` takes its
+  `empty` port and your flow should confirm pay-on-delivery. `octwin orders <ref>` says this inline.
+- **Your declared model may not be the one running.** An operator platform default overrides the pack
+  manifest; `octwin agents` is where that becomes visible.
+- **An empty funnel has two causes** — the entity has no `pipeline:`, or your token's role has no `view`
+  grant on `record.<entity>`. The command prints both rather than a bare "no data".
+## Configuration
+**`octwin login` is the configuration.** There is no config file in your pack — a pack directory
+holds pack content and nothing else, so the same repo deploys from any machine:
+```bash
+octwin login --url https://your-octwin.example.com --token oct_…
+```
+That stores the token *and* makes the URL your default target, in `~/.octwin/credentials.json`:
+```jsonc
+{
+  "default_url": "https://your-octwin.example.com",  // set by the last `octwin login`
+  "https://your-octwin.example.com": "oct_…"          // token, keyed by platform url
+}
+```
+Tenant and project need no setting at all — the **token carries its own tenant**, plus an optional
+project pin. `--tenant` / `--project` exist only as overrides (a multi-workspace human, or an
+unpinned token that must name a project).
+Each setting resolves **flag → environment variable → saved login**:
+| Setting | Flag | Env var | Saved login |
+| --- | --- | --- | --- |
+| Platform URL | `--url` | `PACK_PLATFORM_URL` | `default_url` |
+| Deploy token | `--token` | `PACK_TOKEN` | token for that URL |
+| Tenant slug *(override)* | `--tenant` | `PACK_TENANT` | — *(from the token)* |
+| Project slug *(override)* | `--project` | `PACK_PROJECT` | — *(from the token's pin)* |
+For **CI**, skip `login` entirely and pass `PACK_PLATFORM_URL` + `PACK_TOKEN` as environment
+variables (add `PACK_PROJECT` only if the token isn't pinned).
+## Authentication
+You authenticate with a tenant-scoped **deploy token** (prefixed `oct_…`) — not a password and not
+an operator token. Generate it in the Octwin console (**your workspace → API tokens → Generate**).
+It is **least-privilege** (scope `pack:deploy`): it can deploy packs to your tenant but cannot
+manage members, billing, or other tenants, and it is revocable at any time.
+Add the optional **`media:generate`** scope to let a `--seed` deploy AI-generate seed images
+(for a demo record field like `photo: "generate:<prompt>"`); without it, such fields are seeded as
+text only.
+## What a pack may contain
+A pack is **pure declarative data** — `.yaml` / `.yml` / `.md` / `.json` only. Executable
+code (`.ts`/`.js`), HTTP routes, DB clients, custom primitives and **`.sql`** are **not** allowed
+(this is what makes an external pack safe to run on a shared platform; the server enforces it on
+deploy, and so does `octwin validate`). For
+domain records, use Octwin's first-class storage modules — **XRM** (records with stage pipelines),
+**catalog** (products), or **casework** (tickets) — declared in `xrm.yaml` and `worklist.yaml`, so a
+pack needs **no database of its own**. (Casework rides `worklist.yaml`'s `work.<entity>` block;
+there is no ~~`cases.yaml`~~ grammar. `octwin platform-kb pull` ships the authoritative list of
+declaration files — read its `INDEX.md` rather than this paragraph.)
+## Links
+- **npm:** <https://www.npmjs.com/package/octwin-cli>
+- **Command help:** `octwin help` (each subcommand also answers `--help`)
+- **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
+## License
+[MIT](./LICENSE) © CEQUENS