octwin-cli 0.1.21 → 0.3.0

package/README.md

@@ -1,188 +1,210 @@
-# 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). The platform re-validates the full manifest/flow schema on deploy. |
-| `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 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 help` | Show usage. Every subcommand also answers `--help`. |
-
-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)
+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