octwin-cli 0.1.14 → 0.1.15

package/CHANGELOG.md

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

@@ -70,6 +70,11 @@ octwin status               # "✓ live and current" once it's warm
 | `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) {
@@ -376,7 +435,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;
     }
 }
@@ -860,15 +924,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 +941,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 +962,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 +988,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 +1343,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,6 +1416,483 @@ 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)
 
@@ -1371,6 +1908,11 @@ function help() {
   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)
 
@@ -1423,6 +1965,35 @@ const COMMAND_HELP = {
   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.`,
+    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.`,
@@ -1432,6 +2003,7 @@ const COMMAND_HELP = {
 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 +2044,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/package.json

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