octwin-cli 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -5,6 +5,68 @@ 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.1.16] - 2026-07-26
+
+### Added
+- **A pack can ship committed images.** `jpg`/`jpeg`/`png`/`webp`/`gif`/`pdf` files in your pack
+  directory now travel as a separate `blobs` half of the bundle (base64 on the wire, `bytea` in
+  storage) instead of being rejected as "not an allowed pack file type". Declare each one under the
+  manifest's `static_assets: [{ file, key }]` and reference it from `config:` with the
+  `$pack_asset:<key>` sentinel — the platform uploads it to the media system at install and the
+  sentinel resolves to the served URL. `octwin validate` reports the image count alongside the file
+  count.
+- **The size ceilings fail locally, before upload** — 2 MB per file, 32 MB of binary per pack,
+  mirroring the server. `svg` stays rejected: it is script-capable and these assets are served to
+  browsers.
+
+### Fixed
+- **Committed images were silently corrupted.** `collectBundleFiles` read *every* file with
+  `readFileSync(full, 'utf8')`, so a JPEG went through a lossy UTF-8 decode and arrived mangled
+  server-side — a deploy that "succeeded" and rendered a broken image. Binary files now split off
+  into `blobs` and keep their bytes.
+- **`octwin status` reported `loaded=(none)` for every pack, always.** It printed a `loaded_version`
+  field that stopped existing when reload moved to content-sha keying, which also meant the
+  version-drift warning underneath it could never fire. It now prints the **content sha** the
+  instance has loaded and the one the catalog holds (with the artifact's `origin`), and warns off the
+  platform's own `up_to_date` flag. The sha is the more useful fact anyway: re-publishing the *same*
+  version changes it, which is exactly the author's inner loop. A pack that is live and current but
+  **withdrawn** from the catalog now says so, rather than reporting a clean bill of health.
+
+## [0.1.15] - 2026-07-25
+
+### Added
+- **`octwin agents [packId::agentId] [--prompt]` — see what your agent actually runs as.** The platform
+  gained *governed* agent settings: an operator platform default can override the `default_model`
+  (and history window / working-memory toggle) your manifest declares, and that override is invisible
+  from the pack source. The command prints each governed setting's **effective** value, **which layer
+  won** (project override → platform default → pack manifest), and warns explicitly when your pack's
+  declared value is *not* in force. `--prompt` prints the exact system prompt the LLM sees for this
+  project (pack instructions + platform protocol + any project overlay).
+- **`octwin orders [reference_id]` — the commerce a conversation produced.** The list (number,
+  status/payment, total, contact) or one order with its line items, the
+  subtotal/tax/shipping/discount/total breakdown, `payment_ref`, and the allowed transitions. On a
+  `pending`/`none` payment it explains *why that's expected*: the forward payment lifecycle is
+  **webhook-owned** (not patchable), and the default gateway-less `manual` driver makes
+  `payment_request` take its `empty` port — so the flow should confirm pay-on-delivery, not error.
+- **`octwin analytics [entity]` — stage conversion for any pipelined entity.** The funnel engine that
+  powered journeys is now generic, so any entity declared with a `pipeline:` charts conversion +
+  drop-off (`--overview` / `--milestones` / `--trends` / `--cost`, and `--stage <id>` for the records
+  currently at a stage). An empty result names **both** causes the platform folds into one response —
+  no `pipeline:`, or no `view` grant on `record.<entity>`.
+- **`octwin catalog [--readiness]`** — commerce products with price, availability and stock
+  (`untracked` when the SKU isn't inventory-tracked), plus the WhatsApp catalog binding.
+  `--readiness` runs the Meta Graph checklist with each failing item's suggested fix.
+- **`octwin scheduling [--slots <resourceRecordId>]`** — the engine state (bookable resource types,
+  upcoming slots, booked seats) or the computed slots for one resource. This is how you verify the
+  availability rules a `deploy --seed` created, which 0.1.14 could create but not read back.
+
+### Changed
+- **Auth failures now name the scope the command needs.** Every 401/403 appends the required scope
+  (and the plan feature, where the route is entitlement-gated) from one client-side mirror of the
+  platform's scope registry — replacing the per-command hardcoded strings, several of which named no
+  scope at all. It also spells out that `pack:deploy` / `media:generate` are direct-grant only, so a
+  `tenant:admin` preset token does **not** confer them (the most common "but my token is admin" dead end).
+
 ## [0.1.14] - 2026-07-23
 
 ### Fixed

package/README.md

@@ -65,11 +65,16 @@ octwin status               # "✓ live and current" once it's warm
 | `octwin login` | Save a deploy token for a platform URL (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. |
-| `octwin status` | Report what the platform has live for this pack — installed vs. loaded version, and its flows. |
+| `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), and its flows. |
 | `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 platform-kb pull` | Pull the platform's capability reference (built-ins, primitives, render intents, flow-DSL — as markdown + JSON) into `.octwin/platform-kb/`, for the **`octwin-pack`** Claude Code authoring plugin to consult. |
 | `octwin test` | Alias for `octwin validate --remote` — the platform's full manifest + flow-DSL check. |
 | `octwin help` | Show usage. Every subcommand also answers `--help`. |
@@ -90,6 +95,30 @@ 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
 
 The deploy target has four settings. Three live in a committed **`pack.json`** at the root of your

package/dist/index.js

@@ -19,6 +19,11 @@
  *   octwin logs    [conversationId] [--as h] [--json]  # list conversations / show one's timeline
  *   octwin chat    "msg" [--as h] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn via the web channel (+ send media)
  *   octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (media:generate scope)
+ *   octwin agents  [packId::agentId] [--prompt]   # effective model/memory + which layer won; --prompt = the resolved system prompt
+ *   octwin orders  [reference_id]    # the orders a conversation produced — money breakdown + payment state (orders:read)
+ *   octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion, any pipelined entity
+ *   octwin catalog [--readiness]     # commerce products + stock + the WhatsApp catalog binding (catalog:read)
+ *   octwin scheduling [--slots <resourceRecordId>]  # engine state / computed slots (scheduling:read)
  *   octwin platform-kb [pull] [--dir .]  # pull the platform capability reference for the authoring skill
  *   octwin test    [--dir .]        # = validate --remote (the full platform check)
  *
@@ -99,12 +104,66 @@ function authFailureHint(status, url) {
         ? `the token was rejected — invalid / expired / revoked. If it JUST worked, this can be a one-off platform hiccup: retry once before re-logging in (octwin login --url ${url} --token oct_…)`
         : `the token is valid but not authorized here (missing scope, plan feature, or role)`;
 }
-/** Print the auth-scope hint below an HTTP-failure line when it's a 401/403 —
- *  so every command explains a token problem, not just the inspect family
- *  (author-feedback A7). No-op for other statuses. */
+/**
+ * The scope (and plan feature, where the route is entitlement-gated) each command's
+ * endpoints require — a client-side mirror of the platform's scope registry
+ * (`src/platform/core/identity/scopes.ts` `SCOPE_REGISTRY`) narrowed to what the CLI
+ * calls. A 403 that names the missing scope is the difference between a two-minute
+ * fix (mint a wider token) and a support thread.
+ *
+ * `pack:deploy` and `media:generate` have access `special`: they match by DIRECT
+ * grant only, so even a `tenant:admin` preset token does NOT confer them
+ * (`scopeSatisfies` — the preset branches only reach `:read`/`:write`). That is the
+ * single most common "but my token is admin" confusion, hence the explicit note below.
+ */
+const COMMAND_REQUIREMENTS = {
+    deploy: { scope: 'pack:deploy' },
+    validate: { scope: 'pack:deploy' },
+    status: { scope: 'pack:deploy' },
+    test: { scope: 'pack:deploy' },
+    'platform-kb': { scope: 'pack:deploy' },
+    media: { scope: 'media:generate' },
+    records: { scope: 'records:read', feature: 'records' },
+    analytics: { scope: 'records:read', feature: 'records' },
+    cases: { scope: 'cases:read', feature: 'cases' },
+    logs: { scope: 'conversations:read' },
+    orders: { scope: 'orders:read', feature: 'orders' },
+    catalog: { scope: 'catalog:read', feature: 'catalog' },
+    scheduling: { scope: 'scheduling:read' },
+    agents: { scope: 'agents:read' },
+};
+/** The command currently running — set once in `main()` so any failure printer can
+ *  name the scope that command needs without threading it through every call. */
+let CURRENT_COMMAND;
+/** `→ needs the \`orders:read\` scope …` — the requirement line for the running
+ *  command, or '' when the command has no declared requirement. */
+function scopeRequirementHint() {
+    const req = CURRENT_COMMAND ? COMMAND_REQUIREMENTS[CURRENT_COMMAND] : undefined;
+    if (!req)
+        return '';
+    const special = req.scope === 'pack:deploy' || req.scope === 'media:generate';
+    return `needs the \`${req.scope}\` scope`
+        + (special ? ' (granted DIRECTLY only — a `tenant:admin` token does not confer it)' : '')
+        + (req.feature ? `, and the \`${req.feature}\` plan feature on this workspace` : '');
+}
+/** Print the auth hints below an HTTP-failure line when it's a 401/403 — so every
+ *  command explains a token problem, not just the inspect family (author-feedback A7):
+ *  WHY it failed, then WHAT the command needs. No-op for other statuses. */
 function printAuthHint(status, url) {
-    if (status === 401 || status === 403)
-        console.error(`  → ${authFailureHint(status, url)}`);
+    if (status !== 401 && status !== 403)
+        return;
+    console.error(`  → ${authFailureHint(status, url)}`);
+    const req = scopeRequirementHint();
+    if (req)
+        console.error(`  → ${req}`);
+}
+/** The same two hints folded into ONE line, for the `die(...)` call sites that
+ *  report an auth failure inline instead of via `printAuthHint`. */
+function authFailureDetail(status, url) {
+    if (status !== 401 && status !== 403)
+        return '';
+    const req = scopeRequirementHint();
+    return ` — ${authFailureHint(status, url)}${req ? `; ${req}` : ''}`;
 }
 /** Pretty-print a JSON error body (or raw text) for an HTTP failure line. */
 function errDetail(json) {
@@ -159,9 +218,27 @@ async function resolveMediaPart(url, arg) {
 }
 // ── bundle collection ───────────────────────────────────────────────────────
 const SKIP_DIRS = new Set(['.git', 'node_modules', '.pack-bundles', 'dist', '.mastra']);
-/** Collect every text file under `packDir` into a `{ relPath: content }` map. */
+/**
+ * Binary extensions the platform accepts as artifact BLOBS (mirrors
+ * `ALLOWED_BINARY_EXT` server-side). Deliberately no `svg` — script-capable.
+ */
+const BINARY_EXT = new Set(['jpg', 'jpeg', 'png', 'webp', 'gif', 'pdf']);
+/** Per-blob / total ceilings, mirroring the server so oversize fails LOCALLY. */
+const MAX_BLOB_BYTES = 2 * 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
+/**
+ * Collect a pack directory into its two halves: `files` (`{ relPath: utf8 }`) and
+ * `blobs` (`{ relPath: base64 }`).
+ *
+ * Every file used to be read with `readFileSync(full, 'utf8')`, which silently
+ * MANGLED any committed image — the bytes went through a lossy UTF-8 decode and
+ * arrived corrupt. Binary files now split off into `blobs`, transported as base64
+ * (transport only; they land in `bytea` server-side).
+ */
 function collectBundleFiles(packDir) {
     const files = {};
+    const blobs = {};
+    let totalBlobBytes = 0;
     const walk = (dir, prefix) => {
         for (const name of readdirSync(dir)) {
             const full = join(dir, name);
@@ -176,11 +253,24 @@ function collectBundleFiles(packDir) {
                 continue; // deploy config, not part of the pack
             if (name.startsWith('.'))
                 continue; // .gitignore etc. — not pack content
+            const ext = name.slice(name.lastIndexOf('.') + 1).toLowerCase();
+            if (BINARY_EXT.has(ext)) {
+                const buf = readFileSync(full);
+                if (buf.byteLength > MAX_BLOB_BYTES) {
+                    die(`'${rel}' is ${(buf.byteLength / 1024 / 1024).toFixed(1)} MB — the per-file limit is ${MAX_BLOB_BYTES / 1024 / 1024} MB`);
+                }
+                totalBlobBytes += buf.byteLength;
+                blobs[rel] = buf.toString('base64');
+                continue;
+            }
             files[rel] = readFileSync(full, 'utf8');
         }
     };
     walk(packDir, '');
-    return files;
+    if (totalBlobBytes > MAX_ARTIFACT_BYTES) {
+        die(`binary payload is ${(totalBlobBytes / 1024 / 1024).toFixed(1)} MB — the per-pack limit is ${MAX_ARTIFACT_BYTES / 1024 / 1024} MB`);
+    }
+    return { files, blobs };
 }
 function readManifestIdVersion(files) {
     const raw = files['manifest.yaml'];
@@ -376,7 +466,12 @@ function commandTouchesPlatform(command, flags) {
         case 'records':
         case 'cases':
         case 'logs':
-        case 'whoami': return true;
+        case 'whoami':
+        case 'agents':
+        case 'orders':
+        case 'analytics':
+        case 'catalog':
+        case 'scheduling': return true;
         default: return false;
     }
 }
@@ -423,20 +518,20 @@ function cmdInit(flags) {
     console.log('  octwin deploy');
 }
 function localValidate(packDir) {
-    const files = collectBundleFiles(packDir);
+    const { files, blobs } = collectBundleFiles(packDir);
     const { id, version } = readManifestIdVersion(files);
-    const r = validatePackBundle(id, files);
+    const r = validatePackBundle(id, files, blobs);
     if (!r.ok) {
         for (const e of r.errors)
             console.error(`  ✗ ${e}`);
         die(`bundle validation failed (${r.errors.length} error${r.errors.length === 1 ? '' : 's'})`);
     }
-    return { id, version, files };
+    return { id, version, files, blobs };
 }
 async function cmdValidate(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const { id, version, files } = localValidate(packDir); // offline structural gate first (fast, no server/token)
-    console.log(`✓ ${id}@${version} passes the offline structural check (${Object.keys(files).length} files)`);
+    const { id, version, files, blobs } = localValidate(packDir); // offline structural gate first (fast, no server/token)
+    console.log(`✓ ${id}@${version} passes the offline structural check (${Object.keys(files).length} files, ${Object.keys(blobs).length} image(s))`);
     if (flags.remote !== true) {
         console.log('  Run `octwin validate --remote` to run the platform\'s FULL manifest + flow-DSL validation');
         console.log('  (all errors at once) before you deploy.');
@@ -450,7 +545,7 @@ async function cmdValidate(flags) {
     const res = await fetchOrDie(`${url}/api/self/p/packs/validate`, {
         method: 'POST',
         headers: { 'content-type': 'application/json', ...authHeaders(t) },
-        body: JSON.stringify({ files }),
+        body: JSON.stringify({ files, blobs }),
     }, 'remote validate');
     const text = await res.text();
     let json;
@@ -645,7 +740,7 @@ async function cmdDeploy(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const t = resolveTarget(flags, packDir);
     const { url } = t;
-    const { id, version, files } = localValidate(packDir);
+    const { id, version, files, blobs } = localValidate(packDir);
     const endpoint = `${url}/api/self/p/packs/deploy`;
     const seed = flags.seed === true;
     console.log(`→ Deploying ${id}@${version} (${Object.keys(files).length} files) to ${targetLabel(t)}${seed ? ' — with demo seed' : ''} …`);
@@ -654,7 +749,7 @@ async function cmdDeploy(flags) {
         // Ask for a progress stream; the platform falls back to plain JSON if it
         // (or an error before any progress) can't stream — handled below.
         headers: { 'content-type': 'application/json', accept: 'text/event-stream', ...authHeaders(t) },
-        body: JSON.stringify({ files, seed }),
+        body: JSON.stringify({ files, blobs, seed }),
     }, 'deploy');
     // Streaming path — live install + seed progress (image generation can take a
     // while, so `--seed` prints per-record / per-image lines as they happen).
@@ -726,13 +821,22 @@ async function cmdStatus(flags) {
     }
     console.log(`${id} on ${targetLabel(t)} @ ${url}`);
     console.log(`  installed version : ${json.installed_version}`);
-    console.log(`  live on instance  : registered=${json.registered}  source=${json.source}  loaded=${json.loaded_version ?? '(none)'}`);
+    // Reads the CONTENT SHA, not a version string. It printed `loaded=${json.loaded_version}` — a
+    // field that stopped existing when reload moved to sha keying, so this line always said
+    // `(none)` and the drift warning below could never fire. The sha is also the more useful fact:
+    // re-publishing the SAME version changes it, which is exactly the author's inner loop.
+    const shortSha = (s) => (typeof s === 'string' && s ? s.slice(0, 12) + '…' : '(none)');
+    console.log(`  live on instance  : registered=${json.registered}  loaded=${shortSha(json.loaded_content_sha)}`);
+    console.log(`  catalog artifact  : ${shortSha(json.catalog_content_sha)}${json.origin ? `  origin=${json.origin}` : ''}`);
     console.log(`  flows             : ${(json.flows ?? []).join(', ') || '(none)'}`);
     if (!json.registered) {
         console.log('\n… not warm on the instance you hit yet — it loads on the next inbound (chat once, then re-check).');
     }
-    else if (json.loaded_version && json.installed_version && json.loaded_version !== json.installed_version) {
-        console.log(`\n⚠ instance has ${json.loaded_version} but the project is bound to ${json.installed_version} — a redeploy lands on the next turn.`);
+    else if (json.up_to_date === false) {
+        console.log('\n⚠ this instance is running an OLDER artifact than the catalog holds — it picks up the current one on the next inbound turn (chat once, then re-check).');
+    }
+    else if (json.catalog_status === 'withdrawn') {
+        console.log('\n⚠ live and current, but the pack is WITHDRAWN from the catalog — existing installs keep running; new installs are refused.');
     }
     else {
         console.log('\n✓ live and current.');
@@ -860,15 +964,13 @@ async function cmdRecords(flags) {
     if (!recordId) {
         const limit = flags.limit ?? '50';
         const { status, json } = await apiGet(`${base}/xrm/records?entity=${encodeURIComponent(entity)}&limit=${limit}`, t);
-        if (status === 403)
-            die('forbidden — the paged record list needs the `records` plan feature on this tenant');
         if (status !== 200) {
             // Always show the server's reason (it names the unknown entity). Cases are
             // casework (worklist), not pack-declared XRM — point at the right command.
             if (entity === 'case' || entity === 'cases') {
                 console.error(`  '${entity}' is casework (worklist), not a pack-declared XRM entity — inspect tickets with: octwin cases`);
             }
-            die(`could not read records (HTTP ${status})${errDetail(json)}${status === 401 ? ` — ${authFailureHint(status, url)}` : ''}`);
+            die(`could not read records (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
         }
         const rows = (json?.records ?? []);
         console.log(`${entity}: ${json?.total ?? rows.length} record(s)`);
@@ -879,14 +981,10 @@ async function cmdRecords(flags) {
         return;
     }
     const { status, json } = await apiGet(`${base}/xrm/records/${encodeURIComponent(recordId)}`, t);
-    if (status === 403)
-        die('forbidden — mint a token with the `records:read` scope');
     if (status === 404)
         die(`record '${recordId}' not found`);
-    if (status === 401)
-        die(`could not read record — ${authFailureHint(401, url)}`);
     if (status !== 200)
-        die(`could not read record (HTTP ${status})`);
+        die(`could not read record (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     console.log(JSON.stringify(json?.record ?? json, null, 2));
 }
 /** `octwin logs [conversationId] [--as <handle>] [--json]` — list conversations
@@ -904,7 +1002,7 @@ async function cmdLogs(flags) {
     if (!convId) {
         const { status, json } = await apiGet(`${base}/conversations?limit=50`, t);
         if (status !== 200)
-            die(`could not read conversations (HTTP ${status})${errDetail(json)} — ${authFailureHint(status, url)}`);
+            die(`could not read conversations (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
         let convs = (json?.conversations ?? []);
         if (asHandle)
             convs = convs.filter((c) => c.contact?.channel_contact_handle === asHandle);
@@ -930,7 +1028,7 @@ async function cmdLogs(flags) {
     if (status === 404)
         die(`conversation '${convId}' not found`);
     if (status !== 200)
-        die(`could not read conversation (HTTP ${status})${errDetail(json)} — ${authFailureHint(status, url)}`);
+        die(`could not read conversation (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     const events = (json?.events ?? []);
     if (asJson) {
         console.log(JSON.stringify(events, null, 2));
@@ -1285,9 +1383,11 @@ async function cmdCases(flags) {
     if (!asJson)
         console.log(`→ Reading ${flags.queues === true ? 'case queues' : caseId ? `case ${caseId}` : 'the case inbox'} from ${targetLabel(t)} …`);
     const caseFail = (what, status, json) => {
+        // A 403 here can also be an RBAC gap the scope hint can't see — a role whose
+        // grants don't reach the queue passes the scope gate and still gets nothing.
         if (status === 403)
-            die(`forbidden — casework needs the 'cases' plan feature on this tenant, and a role whose grants reach the queue`);
-        die(`could not read ${what} (HTTP ${status})${errDetail(json)}${status === 401 ? ` — ${authFailureHint(status, url)}` : ''}`);
+            console.error('  → (a role whose grants reach the queue is also required)');
+        die(`could not read ${what} (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     };
     if (flags.queues === true) {
         const { status, json } = await apiGet(`${base}/case-queues`, t);
@@ -1356,82 +1456,594 @@ async function cmdCases(flags) {
         console.log(`  Decisions: ${dispositions.map((d) => `${d.action}${d.next_status ? `→${d.next_status}` : ''}`).join(', ')}`);
     }
 }
+// ── money formatting (orders / catalog) ─────────────────────────────────────
+/** Format a MAJOR-unit decimal amount as currency — the catalog's `price` shape.
+ *  Mirrors the console's `fmtAmount` (console/src/lib/money.ts) so an amount reads
+ *  the same in the terminal as on the page. */
+function fmtAmount(value, currency) {
+    if (value == null)
+        return '—';
+    if (!currency)
+        return value.toFixed(2);
+    try {
+        return new Intl.NumberFormat('en', { style: 'currency', currency }).format(value);
+    }
+    catch {
+        return `${value.toFixed(2)} ${currency}`;
+    }
+}
+/** Format MINOR units (the offset-100 `*_minor` ints every order field is projected
+ *  to on the wire — see `toOrderView`) as currency. `fmtAmount(minor / 100, …)`. */
+function fmtMinor(minor, currency) {
+    if (minor == null)
+        return '—';
+    return fmtAmount(minor / 100, currency);
+}
+/** Human wording for a governed `source` — the layer that won the cascade
+ *  (per-project override > platform default > pack manifest default). The four
+ *  values mirror the platform's `GovernedSource` union exactly. */
+const GOVERNED_SOURCE_LABEL = {
+    project: 'this project overrides it',
+    platform: 'a PLATFORM default overrides the pack',
+    pack: 'the pack manifest value is in force',
+    unset: 'no value at any layer',
+};
+function showValue(v) {
+    if (v === undefined || v === null)
+        return '(unset)';
+    return typeof v === 'string' ? v : JSON.stringify(v);
+}
+/** Print one governed setting as `key: <effective>  [why]`, and — when the pack's
+ *  own declared value is NOT what runs — an explicit second line naming what the
+ *  pack asked for. That override is invisible from the pack source, which is the
+ *  whole reason this command exists. */
+function printGoverned(label, g) {
+    if (!g)
+        return;
+    const source = typeof g.source === 'string' ? g.source : '';
+    console.log(`    ${label.padEnd(22)} ${showValue(g.effective)}   [${GOVERNED_SOURCE_LABEL[source] ?? source ?? '?'}]`);
+    // Warn only when a higher layer displaced the pack's declared value with a
+    // DIFFERENT one. A platform default that happens to equal the pack's value has
+    // changed nothing an author needs to know about.
+    const displaced = (source === 'project' || source === 'platform')
+        && g.pack_default !== undefined
+        && JSON.stringify(g.pack_default) !== JSON.stringify(g.effective);
+    if (displaced)
+        console.log(`      ⚠ your pack declares ${showValue(g.pack_default)} — it is NOT in force`);
+    if (g.opted_out)
+        console.log('      (this workspace is opted OUT of the platform default for this key)');
+}
+/** `octwin agents [agentRef] [--prompt] [--json]` — the agent roster with the
+ *  EFFECTIVE model/memory settings and which layer won, plus (`--prompt`) the exact
+ *  system prompt the LLM sees for this project. Needs an `agents:read` token. */
+async function cmdAgents(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/agents`;
+    const ref = flags._[0];
+    const asJson = flags.json === true;
+    const wantPrompt = flags.prompt === true;
+    if (wantPrompt && !ref)
+        die('usage: octwin agents <packId::agentId> --prompt   (name the agent — `octwin agents` lists them)');
+    if (!asJson)
+        console.log(`→ Reading ${ref ? `agent ${ref}` : 'the agent roster'} from ${targetLabel(t)} …`);
+    // --prompt — the resolved system prompt (pack instructions + platform protocol +
+    // the per-project overlay). No LLM call; pure resolution server-side.
+    if (wantPrompt) {
+        const { status, json } = await apiGet(`${base}/${encodeURIComponent(ref)}/preview-prompt`, t);
+        if (status === 404)
+            die(`agent '${ref}' not found — run \`octwin agents\` for the roster`);
+        // 503 = the pack is installed but not warm on this instance yet (same trap
+        // `octwin status` explains): the agent loads on the next inbound.
+        if (status === 503)
+            die(`'${ref}' is not registered with Mastra on the instance you hit yet — it loads on the next inbound (chat once, then retry)`);
+        if (status !== 200)
+            die(`could not resolve the prompt (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        console.log(`Resolved system prompt for ${json?.agent?.pack_id}::${json?.agent?.pack_agent_id} (${json?.bytes ?? '?'} bytes`
+            + `${json?.has_overlay ? ', includes this project\'s overlay' : ', no project overlay'}):\n`);
+        console.log(json?.resolved_prompt ?? '(empty)');
+        return;
+    }
+    if (!ref) {
+        const { status, json } = await apiGet(base, t);
+        if (status !== 200)
+            die(`could not read agents (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const agents = (json?.agents ?? []);
+        if (agents.length === 0) {
+            console.log('No agents — is a pack installed on this project? (`octwin status`)');
+            return;
+        }
+        console.log(`Agents in ${targetLabel(t)}:`);
+        for (const a of agents) {
+            console.log(`  ${a.pack_id}::${a.pack_agent_id}  "${a.display_name}"${a.enabled === false ? '  [DISABLED]' : ''}`);
+            printGoverned('model', a.governed?.model);
+            if (a.last_error_at)
+                console.log(`    last error: ${a.last_error_at} — ${a.last_error_reason ?? '(no reason)'}`);
+        }
+        console.log('\nOne agent + its full settings:  octwin agents <packId::agentId>');
+        console.log('The prompt the LLM sees:         octwin agents <packId::agentId> --prompt');
+        return;
+    }
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(ref)}`, t);
+    if (status === 404)
+        die(`agent '${ref}' not found — run \`octwin agents\` for the roster`);
+    if (status !== 200)
+        die(`could not read agent (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    console.log(`${json.pack_id}::${json.pack_agent_id}  "${json.display_name}"${json.enabled === false ? '  [DISABLED]' : ''}`);
+    console.log('  Governed settings (project override > platform default > pack manifest):');
+    printGoverned('model', json.governed?.model);
+    printGoverned('memory.last_messages', json.governed?.last_messages);
+    printGoverned('working_memory', json.governed?.working_memory_enabled);
+    console.log(`  tools: ${(json.available_tools ?? []).join(', ') || '(none)'}`);
+    console.log(`  instructions overlay: ${json.instructions_overlay ? `${String(json.instructions_overlay).length} chars (project-specific)` : '(none)'}`);
+    if (json.last_invoked_at)
+        console.log(`  last invoked: ${json.last_invoked_at}`);
+    if (json.last_error_at)
+        console.log(`  last error:   ${json.last_error_at} — ${json.last_error_reason ?? '(no reason)'}`);
+    console.log(`\nThe prompt the LLM actually sees: octwin agents ${ref} --prompt`);
+}
+// ── orders: the commerce lifecycle a conversation produces ───────────────────
+/** Why a `pending` / `none` payment is usually CORRECT, not a bug. The forward
+ *  payment lifecycle is webhook-owned (`payment_status` is deliberately not
+ *  patchable — only `refund` is an operator move), and the default driver is the
+ *  gateway-less `ManualPaymentAdapter`, on which `payment_request` takes its `empty`
+ *  port and mutates nothing. Settling a payment headlessly has no path today — see
+ *  docs/BACKLOG.md → "Headless payment settle" (a `--settle` flag lands here once
+ *  the platform grows a manual-driver-only reconcile endpoint). */
+function printPaymentNote(paymentStatus) {
+    if (paymentStatus !== 'pending' && paymentStatus !== 'none')
+        return;
+    console.log(`  → payment_status '${paymentStatus}' is expected without a live gateway: the forward payment`);
+    console.log('    lifecycle is WEBHOOK-owned (not patchable), and the default `manual` driver has no hosted');
+    console.log('    checkout — so `payment_request` takes its `empty` port and the flow should offer');
+    console.log('    pay-on-delivery. Refund is the one operator-driven move.');
+}
+/** `octwin orders [referenceId] [--status s] [--payment p] [--limit n] [--json]` —
+ *  the orders a conversation created: money breakdown, payment state, allowed
+ *  transitions. Needs an `orders:read` token + the `orders` plan feature. */
+async function cmdOrders(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/orders`;
+    const referenceId = flags._[0];
+    const asJson = flags.json === true;
+    if (!asJson)
+        console.log(`→ Reading ${referenceId ? `order ${referenceId}` : 'orders'} from ${targetLabel(t)} …`);
+    if (!referenceId) {
+        const q = new URLSearchParams({ limit: flags.limit ?? '50' });
+        if (typeof flags.status === 'string')
+            q.set('status', flags.status);
+        if (typeof flags.payment === 'string')
+            q.set('payment', flags.payment);
+        const { status, json } = await apiGet(`${base}?${q.toString()}`, t);
+        if (status !== 200)
+            die(`could not read orders (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const rows = (json?.orders ?? []);
+        console.log(`Orders in ${targetLabel(t)}: ${json?.total ?? rows.length} total`);
+        if (rows.length === 0)
+            console.log('  (none — drive a cart to `cart_submit` with `octwin chat`, or seed demo data)');
+        for (const o of rows) {
+            const who = o.contact?.channel_contact_handle ?? o.contact?.display_name ?? '—';
+            console.log(`  #${o.record_number}  ${o.status}/${o.payment_status}  ${fmtMinor(o.total_minor, o.currency)}  ${who}  ${o.reference_id}`);
+        }
+        console.log('\nOne order + its money breakdown:  octwin orders <reference_id>');
+        return;
+    }
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(referenceId)}`, t);
+    if (status === 404)
+        die(`order '${referenceId}' not found (pass the opaque reference_id, not the #number)`);
+    if (status !== 200)
+        die(`could not read order (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    const o = json?.order ?? {};
+    const cur = o.currency;
+    console.log(`Order #${o.record_number}  ${o.status}  payment: ${o.payment_status}`);
+    console.log(`  reference: ${o.reference_id}${o.payment_ref ? `   payment_ref: ${o.payment_ref}` : ''}`);
+    for (const it of (o.items ?? [])) {
+        console.log(`    ${it.quantity} × ${it.name ?? it.retailer_id}  @ ${fmtMinor(it.amount_minor, it.currency || cur)}`);
+    }
+    console.log(`  subtotal ${fmtMinor(o.subtotal_minor, cur)}`
+        + `   tax ${fmtMinor(o.tax_minor, cur)}`
+        + `   shipping ${fmtMinor(o.shipping_minor, cur)}`
+        + `   discount ${fmtMinor(o.discount_minor, cur)}`);
+    console.log(`  TOTAL    ${fmtMinor(o.total_minor, cur)}`);
+    if (o.note)
+        console.log(`  note: ${o.note}`);
+    const transitions = (json?.transitions ?? []);
+    console.log(`  allowed transitions: ${transitions.join(', ') || '(none — terminal)'}`);
+    printPaymentNote(String(o.payment_status ?? ''));
+}
+// ── analytics: the generic per-entity funnel (any pipelined entity) ──────────
+const ANALYTICS_MODES = ['funnel', 'overview', 'milestones', 'trends', 'cost'];
+/** Both "unknown/non-pipelined entity" and "your role lacks the grant" answer
+ *  200 + `has_data:false` (a deliberate empty state, never a 403) — so a bare
+ *  "no data" would hide the real cause. Name both. */
+function printNoAnalyticsData(entity) {
+    console.log(`No analytics for '${entity}'. Either:`);
+    console.log(`  • '${entity}' isn't declared with a \`pipeline:\` (a funnel needs stages), or`);
+    console.log(`  • your token's role has no \`view\` grant on \`record.${entity}\`.`);
+    console.log('Run `octwin analytics` for the entities that DO carry a pipeline.');
+}
+/** `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost]
+ *  [--stage <id>] [--json]` — stage conversion over ANY pipelined XRM entity
+ *  (orders, carts, cases, bookings, or a pack's own). Needs `records:read`. */
+async function cmdAnalytics(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/xrm/analytics`;
+    const entity = flags._[0];
+    const asJson = flags.json === true;
+    const stage = typeof flags.stage === 'string' ? flags.stage : undefined;
+    const mode = ANALYTICS_MODES.find(m => flags[m] === true) ?? 'funnel';
+    if (stage && !entity)
+        die('usage: octwin analytics <entity> --stage <stageId>   (a stage belongs to an entity)');
+    if (!entity) {
+        if (!asJson)
+            console.log(`→ Reading the analytics entity list from ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}/entities`, t);
+        if (status !== 200)
+            die(`could not read analytics entities (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const ents = (json?.entities ?? []);
+        if (ents.length === 0) {
+            console.log('No pipelined entities visible — a funnel needs an entity declared with a `pipeline:`,');
+            console.log('and your role needs a `view` grant on it. (Journeys have their own analytics surface.)');
+            return;
+        }
+        console.log(`Entities with a funnel in ${targetLabel(t)}:`);
+        for (const e of ents) {
+            console.log(`  ${e.entity}  (${e.stage_count} stage(s), ${e.milestone_count} milestone(s))`);
+        }
+        console.log('\nStage conversion:  octwin analytics <entity>            (add --overview / --milestones / --trends / --cost)');
+        console.log('Who is at a stage: octwin analytics <entity> --stage <stageId>');
+        return;
+    }
+    // Stage drill-down — records CURRENTLY at a stage. A live snapshot, deliberately
+    // NOT range-filtered like the funnel's cumulative reached-≥ counts.
+    if (stage) {
+        if (!asJson)
+            console.log(`→ Reading ${entity} records at stage '${stage}' from ${targetLabel(t)} …`);
+        const limit = flags.limit ?? '50';
+        const { status, json } = await apiGet(`${base}/${encodeURIComponent(entity)}/stages/${encodeURIComponent(stage)}/records?limit=${limit}`, t);
+        if (status === 404)
+            die(`unknown stage '${stage}' for '${entity}'${errDetail(json)}`);
+        if (status !== 200)
+            die(`could not read stage records (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        if (json?.has_data === false) {
+            printNoAnalyticsData(entity);
+            return;
+        }
+        const rows = (json?.records ?? []);
+        console.log(`${entity} at '${stage}' (live snapshot): ${json?.total ?? rows.length} record(s)`);
+        for (const r of rows) {
+            const who = r.channel_contact_handle ?? r.display_name ?? '—';
+            console.log(`  #${r.record_number ?? '?'}  ${r.title ?? '(untitled)'}  ${who}${r.completed ? '  [completed]' : ''}  ${r.record_id}`);
+        }
+        return;
+    }
+    if (!asJson)
+        console.log(`→ Reading ${entity} ${mode} from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(entity)}/${mode}`, t);
+    if (status !== 200)
+        die(`could not read ${mode} (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    if (json?.has_data === false) {
+        printNoAnalyticsData(entity);
+        return;
+    }
+    const range = json?.range ? ` (${json.range.from} → ${json.range.to})` : '';
+    console.log(`${entity} — ${mode}${range}:`);
+    switch (mode) {
+        case 'funnel':
+            for (const s of (json?.funnel ?? [])) {
+                const conv = s.conversion_from_prev_pct == null ? '' : `  ${s.conversion_from_prev_pct}% of prev`;
+                const lost = s.drop_off_from_prev ? `  (−${s.drop_off_from_prev})` : '';
+                console.log(`  ${String(s.rank).padStart(2)}. ${String(s.stage).padEnd(24)} ${String(s.reached).padStart(6)}${conv}${lost}`);
+            }
+            break;
+        case 'overview': {
+            const s = json?.summary ?? {};
+            console.log(`  entered ${s.entered}  →  converted ${s.converted}${s.conversion_pct == null ? '' : `  (${s.conversion_pct}%)`}`);
+            if (s.biggest_dropoff)
+                console.log(`  biggest drop-off: ${s.biggest_dropoff.from} → ${s.biggest_dropoff.to}  (lost ${s.biggest_dropoff.lost})`);
+            if (s.top_milestone)
+                console.log(`  top milestone: ${s.top_milestone.milestone} (${s.top_milestone.completions})`);
+            break;
+        }
+        case 'milestones':
+            for (const m of (json?.milestones ?? [])) {
+                console.log(`  ${String(m.milestone).padEnd(28)} ${String(m.completions).padStart(6)} completion(s), ${m.unique_contacts} contact(s)`);
+            }
+            break;
+        case 'trends':
+            for (const b of (json?.buckets ?? [])) {
+                console.log(`  ${b.bucket}  active ${b.active_contacts}  milestones ${b.milestone_completions}`);
+            }
+            for (const c of (json?.cohorts ?? [])) {
+                console.log(`  cohort ${c.bucket}  entered ${c.entered}  converted ${c.converted}`);
+            }
+            break;
+        case 'cost':
+            if (json?.cost_partial)
+                console.log('  ⚠ partial — some token-usage rows carry no cost');
+            for (const r of (json?.by_milestone ?? [])) {
+                console.log(`  ${String(r.id).padEnd(28)} ${r.conversations} conv, ${r.total_tokens} tokens, $${r.cost_usd}`);
+            }
+            for (const d of (json?.drivers ?? [])) {
+                console.log(`  driver flow=${d.source_flow_id ?? '—'} agent=${d.source_agent_id ?? '—'}  conversions ${d.conversions}`);
+            }
+            break;
+    }
+}
+// ── catalog: the commerce products + their WhatsApp binding ──────────────────
+/** `octwin catalog [--readiness] [--json]` — the `product` records a commerce pack
+ *  sells, their stock, and the WhatsApp catalog binding. Needs `catalog:read` + the
+ *  `catalog` plan feature. */
+async function cmdCatalog(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/catalog`;
+    const asJson = flags.json === true;
+    // --readiness makes LIVE Meta Graph calls (and 409s with no bound access token),
+    // so it's opt-in rather than part of the default read.
+    if (flags.readiness === true) {
+        if (!asJson)
+            console.log(`→ Checking WhatsApp commerce readiness for ${targetLabel(t)} (live Meta Graph calls) …`);
+        const { status, json } = await apiGet(`${base}/readiness`, t);
+        if (status === 409)
+            die(`no Meta access token on this project's WhatsApp channel — readiness needs one${errDetail(json)}`);
+        if (status !== 200)
+            die(`could not read readiness (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const r = json?.readiness ?? {};
+        console.log(`WhatsApp commerce readiness: ${r.summary ?? '?'}`);
+        for (const c of (r.checks ?? [])) {
+            const mark = c.status === 'ok' ? '✓' : c.status === 'warn' ? '⚠' : c.status === 'skip' ? '·' : '✗';
+            console.log(`  ${mark} ${c.label}${c.detail ? ` — ${c.detail}` : ''}`);
+            if (c.solution)
+                console.log(`      → ${c.solution}`);
+        }
+        return;
+    }
+    if (!asJson)
+        console.log(`→ Reading the product catalog from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(base, t);
+    if (status !== 200)
+        die(`could not read the catalog (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    const products = (json?.products ?? []);
+    console.log(`Products in ${targetLabel(t)}: ${products.length}`);
+    if (products.length === 0)
+        console.log('  (none — a commerce pack seeds `product` records, or add them in the console Catalog)');
+    for (const p of products) {
+        // `available: null` = the SKU isn't inventory-tracked (always sellable).
+        const stock = p.available == null ? 'untracked' : `${p.available}`;
+        console.log(`  ${String(p.retailer_id).padEnd(20)} ${String(p.name ?? '').padEnd(28)} ${fmtAmount(p.price, p.currency)}`
+            + `  avail=${p.availability}  stock=${stock}  sync=${p.sync_status ?? '—'}`);
+    }
+    // A binding row can exist with no catalog_id yet (a WABA is configured but no Meta
+    // catalog picked) — that is "not bound" for selling purposes, so say so.
+    const b = json?.binding;
+    console.log(b?.catalog_id
+        ? `\nWhatsApp catalog binding: catalog ${b.catalog_id} (waba ${b.waba_id ?? '—'}), sync=${b.sync_status ?? '—'}, last=${b.last_sync_at ?? 'never'}`
+        : `\nWhatsApp catalog binding: no Meta catalog bound${b?.waba_id ? ` (waba ${b.waba_id} is configured — pick a catalog)` : ''}`
+            + ' — the catalog works web-only (`--readiness` explains what Meta needs).');
+}
+// ── scheduling: the availability engine + a slot preview ─────────────────────
+/** `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]`
+ *  — the scheduling engine's state, or the computed slots for one bookable resource
+ *  (the verification the `--seed` availability fan-out was missing). `scheduling:read`. */
+async function cmdScheduling(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/scheduling`;
+    const asJson = flags.json === true;
+    const resourceId = typeof flags.slots === 'string' ? flags.slots : undefined;
+    if (flags.slots === true)
+        die('usage: octwin scheduling --slots <resourceRecordId>   (the record id of a bookable resource)');
+    if (resourceId) {
+        const q = new URLSearchParams({ include_booked: '1' }); // full occupancy, as the operator preview does
+        if (typeof flags.from === 'string')
+            q.set('from', flags.from);
+        if (typeof flags.days === 'string')
+            q.set('days', flags.days); // server-clamped to 1–31
+        if (!asJson)
+            console.log(`→ Computing slots for resource ${resourceId} in ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}/resources/${encodeURIComponent(resourceId)}/slots?${q.toString()}`, t);
+        if (status === 404)
+            die(`resource '${resourceId}' not found (pass an XRM record id — \`octwin records <entity>\` lists them)`);
+        if (status === 400)
+            die(`that record isn't a bookable resource${errDetail(json)}`);
+        if (status !== 200)
+            die(`could not compute slots (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        if (json?.has_scheduling === false) {
+            console.log('This pack declares no `scheduling.yaml` — nothing to schedule.');
+            return;
+        }
+        const slots = (json?.slots ?? []);
+        console.log(`Slots for ${resourceId} (timezone ${json?.timezone ?? '?'}): ${slots.length}`);
+        if (slots.length === 0)
+            console.log('  (none — no availability rules cover this window; `octwin deploy --seed` seeds the demo rules)');
+        for (const s of slots) {
+            console.log(`  ${s.slot_start} → ${s.slot_end}   ${s.remaining}/${s.capacity} free`);
+        }
+        return;
+    }
+    if (!asJson)
+        console.log(`→ Reading the scheduling engine state from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(base, t);
+    if (status !== 200)
+        die(`could not read scheduling (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    if (json?.has_scheduling === false) {
+        console.log('This pack declares no `scheduling.yaml` — nothing to schedule.');
+        return;
+    }
+    console.log(`Scheduling in ${targetLabel(t)} — bookings land as '${json?.booking_entity}'`);
+    for (const rt of (json?.resource_types ?? [])) {
+        console.log(`  ${rt.entity}  ${rt.resources} resource(s), ${rt.window_days}-day booking window`);
+    }
+    console.log(`  upcoming slots: ${json?.upcoming_slots ?? 0}   booked seats: ${json?.booked_seats ?? 0}`);
+    console.log('\nSlots for one resource:  octwin scheduling --slots <resourceRecordId>   (ids: octwin records <entity>)');
+}
 function help() {
-    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
-
-  octwin --version                                      # print the CLI version (+ any upgrade notice)
-  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
-  octwin validate [--dir .] [--remote]                  # --remote runs the platform's FULL schema check (all errors at once)
-  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
-  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
-  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-  octwin status  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
-  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
-  octwin cases   [caseId] [--queues] [--json]            # inspect casework (support tickets) + timelines
-  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
-  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
-  octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
-  octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
-  octwin test    [--dir .]                               # = validate --remote (the full platform check)
-
-Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
-\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
-button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
-Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
-octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
-Config (deploy): flags > pack.json > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login.
+    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
+
+  octwin --version                                      # print the CLI version (+ any upgrade notice)
+  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+  octwin validate [--dir .] [--remote]                  # --remote runs the platform's FULL schema check (all errors at once)
+  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
+  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
+  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+  octwin status  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
+  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
+  octwin cases   [caseId] [--queues] [--json]            # inspect casework (support tickets) + timelines
+  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
+  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
+  octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
+  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
+  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
+  octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
+  octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
+  octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
+  octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
+  octwin test    [--dir .]                               # = validate --remote (the full platform check)
+
+Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
+\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
+button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
+Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
+octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
+Config (deploy): flags > pack.json > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login.
 Per-command usage: octwin <command> --help`);
 }
 /** Per-subcommand usage — printed for `octwin <cmd> --help|-h` BEFORE any
  *  network/auth work (a --help that 401s is worse than no help at all). */
 const COMMAND_HELP = {
-    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   Scaffold a pure-YAML starter pack into <dir>.`,
-    validate: `octwin validate [--dir .] [--remote]
-  Offline structural check; --remote additionally runs the platform's FULL
+    validate: `octwin validate [--dir .] [--remote]
+  Offline structural check; --remote additionally runs the platform's FULL
   manifest + flow-DSL validation (all errors at once) — same check as deploy.`,
-    login: `octwin login --url <platformUrl> --token oct_…
-  Save a deploy token (console → Settings → API tokens) for that platform url,
+    login: `octwin login --url <platformUrl> --token oct_…
+  Save a deploy token (console → Settings → API tokens) for that platform url,
   and echo the workspace + project pin + scopes the token reaches.`,
-    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
+    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
-    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-  Upload the pack bundle, validate server-side, install onto the project.
+    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).`,
-    status: `octwin status [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
+    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]
-  Inspect the pack's XRM data. No args = list entities. Cases/tickets are
+    records: `octwin records [entity] [id] [--limit 50]
+  Inspect the pack's XRM data. No args = list entities. Cases/tickets are
   casework, not XRM — use \`octwin cases\` for those.`,
-    cases: `octwin cases [caseId] [--queues] [--limit 50] [--json]
-  Inspect casework (support tickets): the inbox, one case + its timeline
+    cases: `octwin cases [caseId] [--queues] [--limit 50] [--json]
+  Inspect casework (support tickets): the inbox, one case + its timeline
   (+ applicable decisions), or --queues for queue keys + open counts.`,
-    logs: `octwin logs [conversationId] [--as <handle>] [--json]
-  No id = recent conversations (handle, status, last activity; --as filters).
-  With id = the full event timeline including what each turn rendered.
+    logs: `octwin logs [conversationId] [--as <handle>] [--json]
+  No id = recent conversations (handle, status, last activity; --as filters).
+  With id = the full event timeline including what each turn rendered.
   --json = raw events (verbatim payloads).`,
-    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
-  Drive one turn through the dev web channel and print every render with its
-  tap ids. Same --as handle = same conversation (multi-turn works).
-  --tap presses a rendered button/list row instead of sending text.
-  --media uploads a local file (or a media id from 'media generate --json') as
-  an image/document/audio inbound — any "message" rides as its caption; feeds a
-  running media-collect flow (e.g. activate-app).
+    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
+  Drive one turn through the dev web channel and print every render with its
+  tap ids. Same --as handle = same conversation (multi-turn works).
+  --tap presses a rendered button/list row instead of sending text.
+  --media uploads a local file (or a media id from 'media generate --json') as
+  an image/document/audio inbound — any "message" rides as its caption; feeds a
+  running media-collect flow (e.g. activate-app).
   --json dumps the raw SSE envelopes for the turn.`,
-    media: `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]
-  AI-generate an image (needs a media:generate-scoped token), store it as a
-  public asset, and print its MEDIA- handle + serve URL. --out downloads the
-  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
+    media: `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]
+  AI-generate an image (needs a media:generate-scoped token), store it as a
+  public asset, and print its MEDIA- handle + serve URL. --out downloads the
+  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
   width, height, bytes }. Pair with 'octwin chat --media' to drive media flows.`,
-    'platform-kb': `octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
-  Pull the platform capability reference (markdown + JSON catalogs) into
+    agents: `octwin agents [packId::agentId] [--prompt] [--json]
+  No args = the roster with each agent's EFFECTIVE model and which layer set it.
+  With an agent = every governed setting (model / memory.last_messages /
+  working_memory) plus the layer that won — an operator PLATFORM default can
+  override what your manifest declares, and this is where you see that.
+  --prompt = the exact system prompt the LLM sees for this project (pack
+  instructions + platform protocol + any project overlay). Needs agents:read.
+  The agent ref is the compound \`<packId>::<agentId>\` key or the override-row UUID.`,
+    orders: `octwin orders [reference_id] [--status s] [--payment p] [--limit 50] [--json]
+  No args = the order list (#number, status/payment, total, contact). With a
+  reference_id = line items, the subtotal/tax/shipping/discount/total breakdown,
+  payment_ref, and the allowed status transitions. Needs orders:read + the
+  \`orders\` plan feature. Note: the forward payment lifecycle is webhook-owned,
+  so \`pending\` on a gateway-less workspace is expected, not a bug.`,
+    analytics: `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>] [--json]
+  No args = the entities that carry a \`pipeline:\` (a funnel needs stages).
+  With an entity = stage-by-stage conversion (default --funnel) over the last 30
+  days. --stage <id> lists the records CURRENTLY at a stage (a live snapshot, not
+  range-filtered). Needs records:read + a \`view\` grant on \`record.<entity>\`.`,
+    catalog: `octwin catalog [--readiness] [--json]
+  The commerce \`product\` records + price, availability, stock (null = not
+  inventory-tracked) and the WhatsApp catalog binding. --readiness runs the Meta
+  Graph checklist (LIVE Graph calls; needs a bound access token). Needs
+  catalog:read + the \`catalog\` plan feature.`,
+    scheduling: `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]
+  No args = the engine state (bookable resource types, upcoming slots, booked
+  seats). --slots <recordId> computes the slots for one bookable resource
+  (occupancy included; --days is clamped to 1-31 server-side) — the way to verify
+  the availability rules a \`deploy --seed\` created. Needs scheduling:read.`,
+    'platform-kb': `octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
+  Pull the platform capability reference (markdown + JSON catalogs) into
   .octwin/platform-kb/ for the octwin-pack authoring skill.`,
-    test: `octwin test [--dir .]
+    test: `octwin test [--dir .]
   Alias for \`octwin validate --remote\` — the full platform check.`,
 };
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
+    CURRENT_COMMAND = command; // so an auth failure can name the scope THIS command needs
     // Per-subcommand --help/-h — intercepted BEFORE the command runs, so help can
     // never hit the network or die on auth (author-feedback A8).
     if (command && command in COMMAND_HELP && (flags.help === true || flags._.includes('-h'))) {
@@ -1472,6 +2084,21 @@ async function main() {
         case 'media':
             await cmdMedia(flags);
             break;
+        case 'agents':
+            await cmdAgents(flags);
+            break;
+        case 'orders':
+            await cmdOrders(flags);
+            break;
+        case 'analytics':
+            await cmdAnalytics(flags);
+            break;
+        case 'catalog':
+            await cmdCatalog(flags);
+            break;
+        case 'scheduling':
+            await cmdScheduling(flags);
+            break;
         case 'platform-kb':
             await cmdPlatformKb(flags);
             break;

package/dist/lib/validate.js

@@ -8,9 +8,20 @@
  * uploading. The **server re-validates authoritatively** on deploy — this local
  * copy is a fast pre-check, not the source of truth — and it omits the server's
  * in-repo shadow check (there is no `src/packs` in a developer's own repo).
+ *
+ * The duplication is deliberate: `octwin-cli` is published to npm and must not
+ * import the platform. `validate-parity.test.ts` asserts the two copies agree on
+ * every rule, so a divergence fails the build rather than surfacing as "it passed
+ * locally but the deploy rejected it".
  */
-/** Declarative file extensions a pure-YAML pack may contain. */
+/** Declarative TEXT extensions a pure-YAML pack may contain. */
 const ALLOWED_EXT = new Set(['yaml', 'yml', 'md', 'sql', 'json']);
+/** Binary extensions that travel as artifact BLOBS (base64 on the wire, bytea in
+ *  storage). No `svg` — it is script-capable and these are served to browsers. */
+const ALLOWED_BINARY_EXT = new Set(['jpg', 'jpeg', 'png', 'webp', 'gif', 'pdf']);
+/** Ceilings, mirrored from the server so oversize fails LOCALLY before upload. */
+const MAX_BLOB_BYTES = 2 * 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
 /** Extensions/paths that mean executable code or a non-YAML capability — rejected. */
 const CODE_EXT = new Set(['ts', 'js', 'mjs', 'cjs', 'jsx', 'tsx', 'node', 'wasm', 'sh', 'bash', 'exe', 'py', 'rb']);
 /** Normalize to forward slashes + strip a leading `./`. */
@@ -28,13 +39,15 @@ function ext(p) {
  * no path traversal or absolute paths, declarative extensions only. Returns all
  * violations at once.
  */
-export function validatePackBundle(packId, files) {
+export function validatePackBundle(packId, files, 
+/** `{ relPath: base64 }` — the binary half, as the CLI collects it. */
+blobs = {}) {
     const errors = [];
     if (!/^[a-z][a-z0-9-]*$/.test(packId)) {
         errors.push(`pack id '${packId}' must be lowercase ASCII with hyphens (e.g. 'my-pack')`);
     }
     const paths = Object.keys(files);
-    if (paths.length === 0)
+    if (paths.length === 0 && Object.keys(blobs).length === 0)
         errors.push('bundle is empty');
     if (!paths.some(p => norm(p) === 'manifest.yaml')) {
         errors.push('bundle is missing manifest.yaml at its root');
@@ -62,10 +75,43 @@ export function validatePackBundle(packId, files) {
             errors.push(`'${p}': executable code is not allowed (pure-YAML packs only)`);
             continue;
         }
+        if (ALLOWED_BINARY_EXT.has(e)) {
+            errors.push(`'${p}': binary files travel as blobs, not in the text file map`);
+            continue;
+        }
         if (!ALLOWED_EXT.has(e)) {
-            errors.push(`'${p}': not an allowed pack file type (.yaml/.yml/.md/.sql only)`);
+            errors.push(`'${p}': not an allowed pack file type (.yaml/.yml/.md/.sql/.json, or an image: ${[...ALLOWED_BINARY_EXT].join('/')})`);
+            continue;
+        }
+    }
+    // Blobs — same rules the server applies to the decoded bytes. Sizes are derived
+    // from the base64 length (3 bytes per 4 chars, minus padding) so this needs no
+    // Buffer and stays platform-free.
+    let totalBlobBytes = 0;
+    for (const raw of Object.keys(blobs)) {
+        const p = norm(raw);
+        if (p.startsWith('/') || /^[a-zA-Z]:/.test(p) || p.split('/').includes('..')) {
+            errors.push(`unsafe blob path '${raw}' (absolute or traversal)`);
+            continue;
+        }
+        const e = ext(p);
+        if (!ALLOWED_BINARY_EXT.has(e)) {
+            errors.push(`'${p}': not an allowed image type (${[...ALLOWED_BINARY_EXT].join('/')}; SVG is rejected — it is script-capable)`);
             continue;
         }
+        const b64 = blobs[raw];
+        const size = Math.floor(b64.replace(/=+$/, '').length * 3 / 4);
+        totalBlobBytes += size;
+        if (size > MAX_BLOB_BYTES) {
+            errors.push(`'${p}': ${(size / 1024 / 1024).toFixed(1)} MB exceeds the ${MAX_BLOB_BYTES / 1024 / 1024} MB per-file limit`);
+        }
+        if (files[raw] !== undefined) {
+            errors.push(`'${p}': present as BOTH a text file and a blob — pick one`);
+        }
+    }
+    if (totalBlobBytes > MAX_ARTIFACT_BYTES) {
+        errors.push(`binary payload ${(totalBlobBytes / 1024 / 1024).toFixed(1)} MB exceeds the ` +
+            `${MAX_ARTIFACT_BYTES / 1024 / 1024} MB per-pack limit`);
     }
     return { ok: errors.length === 0, errors };
 }

package/package.json

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