octwin-cli 0.3.0 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.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

package/README.md

@@ -1,210 +1,211 @@
-# 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)
+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` / `.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

package/dist/index.js

@@ -197,9 +197,15 @@ const VERB_REQUIREMENTS = {
     'scheduling rule': { scope: 'scheduling:write' },
     'scheduling exception': { scope: 'scheduling:write' },
     'agents set': { scope: 'agents:write' },
+    // Creating and destroying a project are the same scope as editing one. Worth
+    // spelling out because the natural token for the deploy loop is `pack:deploy`,
+    // which does NOT confer this — that 403 is otherwise baffling.
+    'projects create': { scope: 'projects:write' },
+    'projects rm': { scope: 'projects:write' },
 };
 const COMMAND_REQUIREMENTS = {
     deploy: { scope: 'pack:deploy' },
+    seed: { scope: 'pack:deploy' },
     validate: { scope: 'pack:deploy' },
     status: { scope: 'pack:deploy' },
     test: { scope: 'pack:deploy' },
@@ -587,7 +593,8 @@ function commandTouchesPlatform(command, flags) {
         case 'analytics':
         case 'catalog':
         case 'scheduling':
-        case 'projects': return true;
+        case 'projects':
+        case 'seed': return true;
         default: return false;
     }
 }
@@ -730,9 +737,25 @@ async function cmdValidate(flags) {
         json = text;
     }
     if (!res.ok) {
-        // 404 → older platform without the endpoint.
-        if (res.status === 404)
-            die('this platform has no /packs/validate endpoint yet (older version) — deploy runs the full check');
+        // A 404 here is AMBIGUOUS and must not be collapsed. The route resolves the
+        // tenant and the project BEFORE it validates anything, so a 404 is usually an
+        // unknown `--tenant`/`--project` — and a token's project PIN answers 404 by
+        // design (an out-of-pin project is deliberately indistinguishable from one that
+        // does not exist). Reporting all of those as "older platform" sends the author
+        // hunting for a version mismatch that does not exist.
+        //
+        // The two are told apart by the BODY, not the status: the platform has no
+        // custom not-found handler, so a missing route is Fastify's default
+        // `{ statusCode, error: 'Not Found', message: 'Route … not found' }`, whereas
+        // `resolveTenantOr404`/`resolveProjectOr404` send a bare `{ error: "<what> not
+        // found" }`. The server's own message already names the slug it tried, so the
+        // hint carries the fix rather than repeating the target.
+        if (res.status === 404) {
+            const routeMissing = typeof json !== 'object' || json === null || json.error === 'Not Found';
+            if (routeMissing)
+                die('this platform has no /packs/validate endpoint yet (older version) — deploy runs the full check');
+            die(`remote validate${errDetail(json)} — check --tenant/--project (or PACK_TENANT/PACK_PROJECT); \`octwin projects\` lists what this token can reach`);
+        }
         console.error(`✗ remote validate failed (HTTP ${res.status})`);
         printAuthHint(res.status, url);
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
@@ -1015,6 +1038,71 @@ function printDeploySuccess(id, version, t, r) {
     printPublicListing(r?.public_listing, r?.public_review_note);
     console.log(`\nChat with it: octwin chat "hi" --as tester   (or the web widget / console test page).`);
 }
+/**
+ * `octwin seed [--pack <id>]` — apply the pack's demo/reference data to the project it
+ * is installed on, without redeploying.
+ *
+ * Exists because seeding used to be reachable only as `deploy --seed`: the platform's
+ * seed endpoint was keyed on an install id, guarded `requirePlatformAdmin`, and carried
+ * no tenant/project segments — so the `/api/self/**` rewrite could not reach it and a
+ * `pack:deploy` token never could. Re-seeding meant a full redeploy, or asking an
+ * operator.
+ *
+ * Reuses `readDeployProgress` verbatim: the platform emits ONE seed-progress vocabulary
+ * now (`stage:'seed'` with a `kind`), so a second reader would only be a second thing to
+ * keep in step.
+ */
+async function cmdSeed(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const packId = typeof flags.pack === 'string' ? flags.pack : undefined;
+    console.log(`→ Seeding ${packId ?? 'the installed pack'} on ${targetLabel(t)} …`);
+    const res = await fetchOrDie(`${url}/api/self/p/packs/seed`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'text/event-stream', ...authHeaders(t) },
+        body: JSON.stringify(packId ? { pack_id: packId } : {}),
+    }, 'seed');
+    if (res.ok && (res.headers.get('content-type') ?? '').includes('text/event-stream') && res.body) {
+        const { terminal: final, stepErrors } = await readDeployProgress(res.body);
+        if (!final || final.stage === 'error')
+            die(`seed failed${final?.message ? `: ${final.message}` : ' (stream ended early)'}`);
+        console.log(`
+✓ ${final.message ?? 'seed complete'}`);
+        printSeedCounts(final.result?.seeded);
+        if (stepErrors.length) {
+            // A kind failed but the rest ran — the reconcile softens each step. Say which,
+            // and exit non-zero so a scripted `seed && chat` doesn't read as clean.
+            console.error(`
+⚠ ${stepErrors.length} step${stepErrors.length === 1 ? '' : 's'} failed — data may be incomplete:`);
+            for (const e of stepErrors)
+                console.error(`   • ${e}`);
+            process.exit(1);
+        }
+        return;
+    }
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        json = text;
+    }
+    if (!res.ok) {
+        console.error(`✗ seed failed (HTTP ${res.status})${errDetail(json)}`);
+        printAuthHint(res.status, url);
+        process.exit(1);
+    }
+    console.log('✓ seed complete');
+    printSeedCounts(json?.seeded);
+}
+/** Per-kind counts, one line each. Prints nothing when the pack declared nothing. */
+function printSeedCounts(seeded) {
+    for (const [kind, counts] of Object.entries(seeded ?? {})) {
+        const detail = Object.entries(counts).filter(([, v]) => v > 0).map(([k, v]) => `${v} ${k}`).join(' · ');
+        console.log(`  ${kind.padEnd(11)} ${detail || '—'}`);
+    }
+}
 async function cmdDeploy(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const t = resolveTarget(flags);
@@ -2523,6 +2611,10 @@ async function cmdAgentsWrite(flags) {
  * (`/api/self/t/`), unlike `agents` — the list is a property of the workspace.
  */
 async function cmdProjects(flags) {
+    if (flags._[0] === 'create')
+        return cmdProjectsCreate(flags);
+    if (flags._[0] === 'rm')
+        return cmdProjectsRm(flags);
     const t = resolveTarget(flags);
     const { url } = t;
     const asJson = flags.json === true;
@@ -2558,6 +2650,128 @@ async function cmdProjects(flags) {
     console.log('\nUse one as:  octwin deploy --project <slug>');
     if (!archived)
         console.log('Archived too: octwin projects --archived');
+    console.log('New one:     octwin projects create "<name>"');
+}
+/**
+ * `octwin projects create "<name>" [--slug <slug>] [--pack <packId>]`
+ *
+ * The missing half of the deploy loop. `octwin deploy` has always needed a project
+ * that already exists, and the CLI could only LIST them — so standing up a throwaway
+ * end-to-end deployment meant opening the console or asking an operator. With this,
+ * a full disposable environment is two commands:
+ *
+ *     octwin projects create "Scratch"        # → slug `scratch`
+ *     octwin deploy --project scratch --seed  # publish + install + demo data
+ *     octwin chat "hi" --project scratch      # talk to it
+ *     octwin projects rm scratch --yes        # throw it away
+ *
+ * A demo is deliberately NOT a special kind of thing — it is an ordinary project in
+ * the developer's own workspace, so it inherits their plan, entitlements, RBAC and
+ * teardown with no bespoke lifecycle to keep honest.
+ *
+ * `packs: []` is the default because the very next step is normally `octwin deploy`,
+ * which publishes the working tree AND installs it. `--pack` is for an ALREADY
+ * published pack (it resolves through `pack_registry` and fails fast if absent).
+ */
+async function cmdProjectsCreate(flags) {
+    // Argument check BEFORE `resolveTarget`, so a missing name reports the usage line
+    // rather than "no platform url" — an argument mistake must not be masked by a
+    // config one the author may not even have.
+    const name = flags._[1];
+    if (!name)
+        die('usage: octwin projects create "<name>" [--slug <slug>] [--pack <packId>]');
+    const t = resolveTarget(flags);
+    const { url } = t;
+    // The Project URL is DERIVED from the name and uniquified server-side unless the
+    // caller pins one — same contract the console's create form uses, so the two
+    // cannot disagree about what slug a given name produces.
+    const body = { name, packs: flags.pack ? [flags.pack] : [] };
+    if (typeof flags.slug === 'string')
+        body.slug = flags.slug;
+    console.log(`→ Creating project "${name}" in ${targetLabel(t)} …`);
+    const { status, json } = await apiSend('POST', `${url}/api/self/t/projects`, body, t);
+    // 402 is the plan cap, and it is the ONE failure here with a non-obvious fix, so it
+    // gets the server's own sentence rather than a generic write failure.
+    if (status === 402)
+        die(`${json?.error ?? 'project limit reached'} — free the slot with \`octwin projects rm <slug> --yes\`, or upgrade the plan.`);
+    if (status !== 200 && status !== 201)
+        writeFail(`create project "${name}"`, status, json, url);
+    if (flags.json === true) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    const slug = json?.slug ?? flags.slug ?? '(unknown)';
+    const installed = (json?.installed_packs ?? []);
+    console.log(`✓ Project created — ${slug}`);
+    for (const p of installed)
+        console.log(`  installed ${p.pack_id}@${p.version}`);
+    console.log('\nNext:');
+    console.log(`  octwin deploy --project ${slug} --seed`);
+    console.log(`  octwin chat "hi" --project ${slug}`);
+}
+/**
+ * `octwin projects rm <slug> --yes`
+ *
+ * HARD delete — the row and everything the FK graph cascades from it (conversations,
+ * contacts, records, installs, webhooks). Not the archive verb; there is no undo.
+ *
+ * `--yes` is required rather than prompted because the CLI is non-interactive by
+ * design (it runs under `npx`, in scripts and in CI, where a prompt reads EOF and a
+ * "safe" default would be a lie). Without it this prints the same impact preview the
+ * console's confirm dialog shows — derived from `pg_constraint`, not a hand-written
+ * list — and stops. That makes the dry run the DEFAULT, which is the right way round
+ * for an irreversible verb.
+ */
+async function cmdProjectsRm(flags) {
+    const slug = flags._[1];
+    if (!slug)
+        die('usage: octwin projects rm <slug> --yes   (omit --yes to preview what it destroys)');
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const preview = await apiGet(`${url}/api/self/t/projects/${encodeURIComponent(slug)}/preview-hard-delete`, t);
+    if (preview.status === 404)
+        die(`no project '${slug}' in ${targetLabel(t)} — \`octwin projects\` lists them`);
+    if (preview.status !== 200)
+        die(`could not preview the delete (HTTP ${preview.status})${errDetail(preview.json)}${authFailureDetail(preview.status, url)}`);
+    if (flags.json === true && flags.yes !== true) {
+        console.log(JSON.stringify(preview.json, null, 2));
+        return;
+    }
+    // Shapes come from `HardDeletePreview` (routes/_hard-delete-preview.ts) — the same
+    // payload the console's confirm dialog renders, so the two can't disagree about
+    // what a delete costs.
+    const tables = (preview.json?.tables ?? []);
+    const hits = tables.filter(r => r.count > 0);
+    const totals = preview.json?.totals ?? {};
+    console.log(`Deleting project ${slug} from ${targetLabel(t)} destroys:`);
+    if (hits.length === 0)
+        console.log('  (nothing — the project has no rows yet)');
+    for (const r of hits) {
+        const mark = r.disposition === 'cascade' ? '' : `  [${r.disposition}]`;
+        console.log(`  ${r.count}${r.capped ? '+' : ''}\t${r.schema}.${r.table}${mark}`);
+    }
+    if (hits.length > 0) {
+        console.log(`  — ${totals.rows_deleted}${totals.rows_deleted_capped ? '+' : ''} rows across ${totals.tables_affected} tables`);
+    }
+    // Side effects no FK walk can see (storage blobs, agent memory, Meta registrations).
+    // Anything not `deleted` is what SURVIVES the delete — the part worth reading.
+    const residue = (preview.json?.residue ?? []);
+    const surviving = residue.filter(r => r.disposition !== 'deleted');
+    if (surviving.length > 0) {
+        console.log('\nNot removed by the cascade:');
+        for (const r of surviving)
+            console.log(`  [${r.disposition}] ${r.label}${r.count != null ? ` (${r.count})` : ''} — ${r.detail}`);
+    }
+    if (totals.blocked > 0)
+        console.log(`\n! ${totals.blocked} table(s) would BLOCK this delete.`);
+    if (flags.yes !== true) {
+        console.log('\nNothing was deleted. Re-run with --yes to go through with it.');
+        return;
+    }
+    const { status, json } = await apiSend('DELETE', `${url}/api/self/t/projects/${encodeURIComponent(slug)}/hard`, undefined, t);
+    if (status !== 200 && status !== 204)
+        writeFail(`delete project '${slug}'`, status, json, url);
+    console.log(`\n✓ Deleted ${slug}.`);
 }
 async function cmdAgents(flags) {
     if (flags._[0] === 'set')
@@ -3287,10 +3501,32 @@ const COMMAND_HELP = {
     projects: `octwin projects [--archived] [--json]
   List the workspace's projects — the slugs every --project flag takes, with the
   plan's project cap. --archived includes archived ones. A pack:deploy token
-  reaches this (it names a project in every other command).`,
+  reaches this (it names a project in every other command).
+
+octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
+  Create a project. The URL slug is derived from the name unless --slug pins one.
+  --pack installs an ALREADY-published pack; the usual next step is instead
+  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
+
+octwin projects rm <slug> [--yes]
+  HARD delete — the project and everything cascading from it (conversations,
+  contacts, records, installs). No undo, and not the same as archiving.
+  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
+  default. Together these make a disposable end-to-end environment:
+    octwin projects create "Scratch" && octwin deploy --project scratch --seed
+    octwin chat "hi" --project scratch
+    octwin projects rm scratch --yes
+  Both verbs need the \`projects:write\` scope — a pack:deploy token does NOT confer it.`,
     deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
   Upload the pack bundle, validate server-side, install onto the project.
   --seed additionally applies the pack's demo seed (streams progress).`,
+    seed: `octwin seed [--pack <packId>]
+  Apply the pack's demo/reference data to the project it is installed on, without
+  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
+  and the demo operator topology. Reports what each kind produced.
+  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
+  than regenerated, so a second pass costs nothing. --pack is only needed when a
+  project somehow runs more than one.`,
     status: `octwin status [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
   Show installed vs live version + the flow list for this pack.`,
     records: `octwin records [entity] [id] [--limit 50] [--offset n]
@@ -3498,6 +3734,9 @@ async function main() {
         case 'media':
             await cmdMedia(flags);
             break;
+        case 'seed':
+            await cmdSeed(flags);
+            break;
         case 'projects':
             await cmdProjects(flags);
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {