octwin-cli 0.8.10 → 0.8.12

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.
 
+## [Unreleased]
+
+## [0.8.12] - 2026-09-25
+
+### Changed
+- **The package pointed its `homepage` at npm — the page it is rendered on.** It is
+  <https://octwin.ai> now, and the README's Links section gains the platform, the guides and the
+  marketplace. The README describes Octwin at length and linked only to npm and nodejs.org.
+- **`octwin usage` with a project-pinned token reports that project.** The platform now treats a
+  token's project pin as a ceiling on every route, so a pinned token is refused on the
+  workspace-wide rollup. `usage` asks `whoami` for the pin and reads the project view instead of
+  printing a 403 — which is what its help text (`project if pinned, else workspace`) always said.
+
+### Fixed
+- **`octwin chat` sat out its whole 45-second wait on every message during a live handoff, and
+  read as hung.** While a person holds the conversation (or one has been asked for) the AI Agent
+  deliberately answers nothing, and the CLI could not tell that from a slow pack. The platform now
+  says so with a `held` event on the web stream; `chat` prints
+  *"⏸ a person is holding this conversation — the AI Agent will not reply…"* (or *"waiting for a
+  person to join…"*), still collects any operator line replayed by that message, and returns. A
+  held turn is not a failure: it exits 0, and `--script` carries on to the next line, so the
+  customer's side of a handoff can be scripted. Needs a platform that sends `held`; an older one
+  behaves as before. Reported in `xpeng-egypt/FEEDBACK.md`, session 3.
+
+## [0.8.11] - 2026-09-07
+
+### Fixed
+- **`octwin login` erased your own tooling report — the CLI was blanking what it had just
+  told the platform.** Two calls built their `authorization` header by hand instead of going
+  through `authHeaders`: `login`'s post-save "here's what your token reaches" echo, and
+  `chat`'s tenant/project derivation. Both authenticate, so both stamp the token's client
+  report (added in 0.8.9) — and a hand-built header stamps **NULL**, wiping the CLI version
+  and reference hash the platform had recorded.
+
+  Caught within an hour of 0.8.9 reaching staging: a workspace reported `0.8.9 · reference
+  current` at 12:16 and read `not reported` at 12:34. That looked exactly like the documented
+  "the column holds what ran LAST" behaviour and was really the CLI erasing its own row.
+  `cli-routes.test.ts` now fails on any hand-built bearer header, with a non-vacuity floor —
+  this package sits outside the repo's eslint scope, so a text guard is the only rung available.
+
 ## [0.8.10] - 2026-09-07
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@
 [![license](https://img.shields.io/npm/l/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
 [![node](https://img.shields.io/node/v/octwin-cli.svg)](https://nodejs.org)
 
-Octwin is a pack-pluggable conversational-agent platform for WhatsApp and web. A **pack** is a
+[Octwin](https://octwin.ai) is a pack-pluggable conversational-agent platform for WhatsApp and web. A **pack** is a
 self-contained bot domain — its agent, conversation flows, prompts, and data model — declared
 entirely in YAML. `octwin-cli` lets you build a **pure-YAML pack** in your own repo and deploy it
 to a running Octwin platform to test live on your own tenant: no platform checkout, no build step,
@@ -238,6 +238,9 @@ declaration files — read its `INDEX.md` rather than this paragraph.)
 
 ## Links
 
+- **Octwin:** <https://octwin.ai> — the platform this CLI deploys to
+- **Guides & playbooks:** <https://octwin.ai/artifacts> — how each capability works, end to end
+- **Marketplace:** <https://octwin.ai/packs> — published packs you can read before writing your own
 - **npm:** <https://www.npmjs.com/package/octwin-cli>
 - **Command help:** `octwin help` (each subcommand also answers `--help`)
 - **Changelog:** [CHANGELOG.md](./CHANGELOG.md)

package/dist/index.js

@@ -66,7 +66,7 @@ import { parse as parseYaml } from 'yaml';
 import { applyRenames } from './lib/rename.js';
 import { validatePackBundle, describePackNameProblem, asPackName } from './lib/validate.js';
 import { loadAllowedRenderKeys, findRenderKeyViolations, describeRenderFinding } from './lib/render-check.js';
-import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding } from './lib/args-check.js';
+import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding, findArgWarnings, describeArgWarning, } from './lib/args-check.js';
 import { yamlLineOf } from './lib/yaml-pos.js';
 import { localhostFamilyHint } from './lib/net-hint.js';
 import { authHeaders as buildAuthHeaders } from './lib/client-headers.js';
@@ -1049,13 +1049,33 @@ async function cmdValidate(flags) {
                 if (!args.specs)
                     return { kind: 'not-run', lookup: args.lookup };
                 const findings = withLines(yamlDocs().flatMap(([p, doc]) => findArgViolations(doc, p, args.specs)));
-                return findings.length
-                    ? {
+                if (findings.length) {
+                    return {
                         kind: 'findings', noun: 'primitive-argument error',
                         lines: findings.map(describeArgFinding),
                         hint: 'fix these before deploying — an undeclared argument is dropped with no error at runtime',
-                    }
-                    : { kind: 'passed', line: 'primitive arguments match their declared inputs' };
+                    };
+                }
+                /**
+                 * Errors first, and only then the warnings — a `findings` outcome exits, so a warning
+                 * printed above it would never be read, and one printed below it would never be reached.
+                 *
+                 * `warnsTogether` is the platform's own declaration (`record_save` with `record_id:` +
+                 * `stage:` refuses the whole write on an existing record). It has been enforced server-side
+                 * since 2026-09-06 and was reachable only through `--remote`; the author who lost a write
+                 * to it was on CLI 0.6.0, offline. Measured before shipping: **0 findings across all 48
+                 * `record_save` call sites in the 23 marketplace packs** — the check is silent on a clean
+                 * corpus, which is the bar a warning has to clear before it is worth printing at all.
+                 */
+                const warnings = withLines(yamlDocs().flatMap(([p, doc]) => findArgWarnings(doc, p, args.specs)));
+                if (warnings.length) {
+                    return {
+                        kind: 'warnings', noun: 'argument-combination warning',
+                        lines: warnings.map(describeArgWarning),
+                        hint: 'legal YAML, and usually not what you meant — read each one and decide.',
+                    };
+                }
+                return { kind: 'passed', line: 'primitive arguments match their declared inputs' };
             },
         },
         {
@@ -1297,7 +1317,11 @@ async function saveLogin(url, token) {
     // so a fresh token self-identifies without a second `octwin whoami`. A network
     // failure never fails the save — the token is stored regardless.
     try {
-        const res = await fetch(`${url}/api/self/t/whoami`, { headers: { authorization: `Bearer ${token}` } });
+        // `authHeaders`, not a hand-built `authorization` — this call authenticates, so it
+        // STAMPS the token's client report (migration 055), and a hand-built header stamps
+        // NULL. Measured 2026-09-07: that blanked a caller who was on a reporting CLI, so
+        // `octwin login` erased the author's own tooling row. Guarded in `cli-routes.test.ts`.
+        const res = await fetch(`${url}/api/self/t/whoami`, { headers: authHeaders({ url, token }) });
         if (res.ok) {
             const j = await res.json();
             const scopes = Array.isArray(j.scopes) && j.scopes.length ? ` · scopes: ${j.scopes.join(', ')}` : '';
@@ -1818,7 +1842,7 @@ async function cmdSeed(flags) {
         if (stepErrors.length) {
             // A kind failed but the rest ran — the reconcile softens each step. Say which,
             // and exit non-zero so a scripted `seed && chat` doesn't read as clean.
-            console.error(`
+            console.error(`
 ⚠ ${stepErrors.length} step${stepErrors.length === 1 ? '' : 's'} failed — data may be incomplete:`);
             for (const e of stepErrors)
                 console.error(`   • ${e}`);
@@ -2277,6 +2301,24 @@ async function apiGet(endpoint, t) {
     }
     return { status: res.status, json };
 }
+/**
+ * The project this token is pinned to, or null (unpinned, or the lookup failed). A pinned token
+ * cannot reach workspace-wide routes, so a command with a workspace view and a project view uses
+ * this to pick the one the token can actually read. `authHeaders`, never a hand-built header — an
+ * authenticating call without it stamps NULL over the token's client report.
+ */
+async function pinnedProjectOf(t) {
+    try {
+        const res = await fetch(`${t.url}/api/self/t/whoami`, { headers: authHeaders(t) });
+        if (!res.ok)
+            return null;
+        const j = await res.json();
+        return typeof j.project_slug === 'string' && j.project_slug ? j.project_slug : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Send a WRITE to an admin endpoint with the deploy token; returns `{ status, json }`.
  *
@@ -2772,9 +2814,25 @@ async function cmdLogs(flags) {
     console.log(`Timeline for ${convId} (${events.length} events):`);
     for (const e of events) {
         const isErr = e.type === 'tool' && e.subtype === 'platform_error';
-        const tag = isErr ? '⚠ ERROR' : `${e.type}${e.subtype ? `/${e.subtype}` : ''}`;
+        /**
+         * An ADVISORY is a turn that worked and that you probably did not mean.
+         *
+         * It reads differently from an error on purpose: nothing failed, so `⚠ ERROR` would be a lie
+         * and the plain `tool/platform_advisory` tag would be scrolled past. The platform raises these
+         * exactly where a silent-but-wrong result used to be invisible — a `record_list` scoped to a
+         * customer who owns none of a shared entity returns zero rows and the `empty` port, which
+         * prints identically to a real no-match. Three separate authors lost debugging sessions to
+         * that one before it had anywhere to appear.
+         */
+        const isAdvisory = e.type === 'tool' && e.subtype === 'platform_advisory';
+        const tag = isErr ? '⚠ ERROR' : isAdvisory ? '! CHECK' : `${e.type}${e.subtype ? `/${e.subtype}` : ''}`;
         const body = typeof e.content === 'string' ? e.content : JSON.stringify(e.content ?? '');
         console.log(`  ${e.ts ?? ''}  ${tag}: ${body ?? ''}`);
+        // The remedy, indented under its advisory. Printing the observation without the fix is what
+        // the envelope field and the server log already did, and neither reached an author.
+        if (isAdvisory && typeof e.metadata?.remedy === 'string' && e.metadata.remedy) {
+            console.log(`      → ${e.metadata.remedy}`);
+        }
         // The renders this turn actually sent (captured outbound payloads) — the
         // other half of the story next to the structured tap lines.
         const captured = Array.isArray(e.metadata?.raw) ? e.metadata.raw : [];
@@ -2934,19 +2992,12 @@ function parseChatScript(body) {
     }
     return turns;
 }
-/**
- * Send ONE turn and print everything it rendered. Returns the new frame boundary
- * (so the next turn only accepts frames newer than this turn's output) and how
- * many renders arrived.
- *
- * Splitting this out is what makes `--script` reliable. Driving a multi-step flow
- * by chaining shell invocations (`chat A && chat B`) races the agent loop: this
- * command ends a turn on a QUIET GAP, and the server-side loop can still be
- * running when the process exits, so the next invocation's inbound lands
- * mid-turn. The agent then fills required fields with placeholder text, or starts
- * a second workflow run. Inside one process the loop simply waits for the settle
- * before sending the next turn, over the same SSE connection.
- */
+/** The line printed for a held turn — what the author needs to know, not a failure. */
+function heldLine(voice) {
+    return voice === 'human'
+        ? '⏸ a person is holding this conversation — the AI Agent will not reply. The operator answers from Live chat in the console; nothing more comes back here for this turn.'
+        : '⏸ waiting for a person to join — the AI Agent will not reply until someone accepts in Live chat, or the wait runs out and the conversation returns to it.';
+}
 async function runChatTurn(args) {
     const { url, tenant, project, from, turn, frames, asJson } = args;
     let boundary = args.boundary;
@@ -2986,15 +3037,23 @@ async function runChatTurn(args) {
         console.log(`  … delivered — waiting for the reply (up to ${Math.round(REPLY_TIMEOUT_MS / 1000)}s)`);
     // Collect THIS turn's renders (id > boundary). A turn can send several
     // messages, so keep reading until a quiet gap after the last render.
+    //
+    // A HELD turn ends the wait too. While a person holds the conversation (or one has been
+    // asked for) the platform deliberately sends no AI Agent reply, and says so with a `held`
+    // envelope; before it did, this loop sat out the whole REPLY_TIMEOUT_MS on every held turn
+    // and the author read it as a hang. After `held` the loop still settles for TURN_SETTLE_MS,
+    // because the same customer message replays any operator line queued while they were away.
     const deadline = Date.now() + REPLY_TIMEOUT_MS;
     let rendersSeen = 0;
+    let held = null;
     for (;;) {
         const remaining = deadline - Date.now();
         if (remaining <= 0)
             break;
-        const f = await frames.next(rendersSeen > 0 ? TURN_SETTLE_MS : Math.min(remaining, REPLY_TIMEOUT_MS));
+        const settling = rendersSeen > 0 || held !== null;
+        const f = await frames.next(settling ? TURN_SETTLE_MS : Math.min(remaining, REPLY_TIMEOUT_MS));
         if (f === 'timeout') {
-            if (rendersSeen > 0)
+            if (settling)
                 break;
             else
                 continue;
@@ -3005,6 +3064,11 @@ async function runChatTurn(args) {
             continue; // late replay stragglers
         if (f.id != null)
             boundary = f.id;
+        if (f.ev?.kind === 'held' && held === null) {
+            held = f.ev.voice === 'human' ? 'human' : 'pending';
+            if (!asJson)
+                console.log(heldLine(held));
+        }
         if (asJson) {
             console.log(JSON.stringify(f.ev));
             if (f.ev?.kind === 'render')
@@ -3017,7 +3081,7 @@ async function runChatTurn(args) {
         console.log(`← ${f.ev.body ?? '(no text body)'}${f.ev.hint?.type && f.ev.hint.type !== 'text' ? `   (render: ${f.ev.hint.type})` : ''}`);
         printHint(f.ev.hint);
     }
-    return { boundary, rendersSeen };
+    return { boundary, rendersSeen, held };
 }
 /** `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--script <file>] [--json]`
  *  — drive a turn (or a whole scripted conversation) through the dev web channel
@@ -3053,8 +3117,11 @@ async function cmdChat(flags) {
         const token = raw.token;
         if (token) {
             try {
+                // `authHeaders` carries the tenant override itself, and — the reason this is not
+                // hand-built — it carries the client report. An authenticating call that skips it
+                // stamps NULL over the token's reported CLI + reference. See `cli-routes.test.ts`.
                 const who = await fetch(`${url}/api/self/t/whoami`, {
-                    headers: { authorization: `Bearer ${token}`, ...(tenant ? { 'x-octwin-tenant': tenant } : {}) },
+                    headers: authHeaders({ url, token, ...(tenant ? { tenant } : {}) }),
                 });
                 if (who.ok) {
                     const j = await who.json();
@@ -3115,13 +3182,18 @@ async function cmdChat(flags) {
     // Phase 2+3 — run each turn in order, over the SAME connection. One turn is
     // the normal case; `--script` drives a whole conversation.
     let totalRenders = 0;
+    let anyHeld = false;
     for (const [i, turn] of turns.entries()) {
         if (turns.length > 1)
             console.log(`\n── turn ${i + 1}/${turns.length} ──`);
         const r = await runChatTurn({ url, tenant, project, from, turn, frames, boundary, asJson });
         boundary = r.boundary;
         totalRenders += r.rendersSeen;
-        if (r.rendersSeen === 0 && turns.length > 1) {
+        if (r.held)
+            anyHeld = true;
+        // A held turn answered nothing BY DESIGN — the script goes on, so an author can script the
+        // customer's side of a handoff (their lines reach the operator's pane) without it stopping.
+        if (r.rendersSeen === 0 && !r.held && turns.length > 1) {
             // Stop rather than fire the rest of the script into a conversation that
             // isn't answering — the remaining turns would land out of context.
             await cancel();
@@ -3130,7 +3202,7 @@ async function cmdChat(flags) {
         }
     }
     await cancel();
-    if (totalRenders === 0) {
+    if (totalRenders === 0 && !anyHeld) {
         console.error(`  no reply after ${Math.round(REPLY_TIMEOUT_MS / 1000)}s — the pack may not be warm yet, or the turn produced no render.`);
         exitNow(1);
     }
@@ -5143,9 +5215,13 @@ async function cmdUsage(flags) {
     const t = resolveTarget(flags);
     const { url } = t;
     const asJson = flags.json === true;
-    const scoped = Boolean(t.project);
+    // A token pinned to one project is refused on the workspace rollup (the pin is a ceiling on
+    // every route), so for a pinned token the project view IS the answer — ask whoami rather
+    // than print a 403 at someone whose token can only ever see one project.
+    const pinned = t.project ? null : await pinnedProjectOf(t);
+    const scoped = Boolean(t.project || pinned);
     if (!asJson)
-        console.log(`→ Reading model usage for ${scoped ? targetLabel(t) : 'the whole workspace'} …`);
+        console.log(`→ Reading model usage for ${scoped ? (pinned ? `project '${pinned}'` : targetLabel(t)) : 'the whole workspace'} …`);
     // Both URLs written out in place, for the same reason as `performance` above: an
     // `endpoint` variable would leave BOTH invisible to `cli-routes.test.ts`.
     const { status, json } = scoped
@@ -5178,388 +5254,388 @@ async function cmdUsage(flags) {
     console.log('\nThis is MODEL spend. WhatsApp/Meta message billing is operator-only — not reachable by an API token.');
 }
 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] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
-  octwin login   --url <platformUrl>                    # approve in a browser; the CLI collects the token
-  octwin login   --url <platformUrl> --token oct_…      # or paste a deploy token from the console
-  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
-  octwin projects [--archived] [--json]                  # the --project slugs this token can name
-  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
-  octwin status  [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
-  octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
-  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
-  octwin work    [recordId] [--queues] [--unrouted] [--json]  # inspect the work inbox (worked records) + timelines
-                 #   --queues: per-queue open counts + an UNROUTED warning · --unrouted: only the items in no queue
-  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>] [--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 automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
-  octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
-  octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
-  octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
-  octwin performance [--detail] [--json]                 # the project's business indicators (value/conversion/duration)
-  octwin usage   [--json]                                # model calls, tokens and cost (project if pinned, else workspace)
-  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
-  octwin test    [--dir .]                               # = validate --remote (the full platform check)
-  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
-  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
-
-Writes — exercise the state your pack creates (each needs the matching :write scope):
-  octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
-  octwin records tasks | task complete <taskId> [--outcome done|cancelled]
-  octwin work    assign <id> --to user:<uuid>|none | note <id> "…" | stage <id> --to <stage>
-  octwin work    decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
-  octwin orders  transition <ref> --to <status> | refund <ref> --force
-  octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
-  octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
-  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
-  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
-  octwin integrations test <key>                         # a LIVE call to the connection's health: operation
-  octwin integrations retry|cancel|send-now <deliveryId>
-  (octwin integrations preflight <key> needs only integrations:read — it makes no call)
-
-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).
-Signing in: \`octwin login --url <u>\` prints a link + code to approve in a browser. To pick your own
-scopes instead, mint a 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 > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
+    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] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
+  octwin login   --url <platformUrl>                    # approve in a browser; the CLI collects the token
+  octwin login   --url <platformUrl> --token oct_…      # or paste a deploy token from the console
+  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
+  octwin projects [--archived] [--json]                  # the --project slugs this token can name
+  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
+  octwin status  [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
+  octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
+  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
+  octwin work    [recordId] [--queues] [--unrouted] [--json]  # inspect the work inbox (worked records) + timelines
+                 #   --queues: per-queue open counts + an UNROUTED warning · --unrouted: only the items in no queue
+  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>] [--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 automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
+  octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
+  octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
+  octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
+  octwin performance [--detail] [--json]                 # the project's business indicators (value/conversion/duration)
+  octwin usage   [--json]                                # model calls, tokens and cost (project if pinned, else workspace)
+  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
+  octwin test    [--dir .]                               # = validate --remote (the full platform check)
+  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
+  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
+
+Writes — exercise the state your pack creates (each needs the matching :write scope):
+  octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
+  octwin records tasks | task complete <taskId> [--outcome done|cancelled]
+  octwin work    assign <id> --to user:<uuid>|none | note <id> "…" | stage <id> --to <stage>
+  octwin work    decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
+  octwin orders  transition <ref> --to <status> | refund <ref> --force
+  octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
+  octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
+  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
+  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
+  octwin integrations test <key>                         # a LIVE call to the connection's health: operation
+  octwin integrations retry|cancel|send-now <deliveryId>
+  (octwin integrations preflight <key> needs only integrations:read — it makes no call)
+
+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).
+Signing in: \`octwin login --url <u>\` prints a link + code to approve in a browser. To pick your own
+scopes instead, mint a 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 > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
 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] [--require-kb] [--strict-primitives]
-  Offline structural check, plus two checks driven by the pulled capability
-  reference (render-intent fields, primitive arguments). Those two SKIP when the
-  reference is missing — the run says so, and --require-kb turns the skip into a
-  failure for CI. --remote additionally runs the platform's FULL manifest +
-  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.
-  --strict-primitives (with --remote) additionally type-checks LITERAL args:
-  values against each primitive's declared input schema; expression strings
+    validate: `octwin validate [--dir .] [--remote] [--require-kb] [--strict-primitives]
+  Offline structural check, plus two checks driven by the pulled capability
+  reference (render-intent fields, primitive arguments). Those two SKIP when the
+  reference is missing — the run says so, and --require-kb turns the skip into a
+  failure for CI. --remote additionally runs the platform's FULL manifest +
+  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.
+  --strict-primitives (with --remote) additionally type-checks LITERAL args:
+  values against each primitive's declared input schema; expression strings
   ('$found.id', '{$t(…)}') are always exempt.`,
-    login: `octwin login --url <platformUrl> [--token oct_…] [--wait <seconds>] [--json]
-  Sign in to a platform and make that url the DEFAULT deploy target for every
-  later command.
-
-  WITH --token: saves a token you minted yourself (console → Settings → API
-  tokens). Unchanged, and still the right answer for CI — there, skip login and
-  set PACK_PLATFORM_URL + PACK_TOKEN instead.
-
-  WITHOUT --token: prints a link to approve in a browser. A workspace admin opens
-  it, checks which machine is asking, and clicks Approve; the CLI then collects a
-  30-day token by itself, so no token is ever pasted between people. The code is
-  printed too — it is what the page shows, so you can tell it is your own request.
-  Approve only a link you opened because YOU ran this command: a link someone
-  sends you would connect THEIR machine to your workspace.
-
-  The wait is bounded (90s by default) and RESUMABLE: if nobody has approved yet
-  it exits 75 and keeps the request, so running \`octwin login\` again picks up the
+    login: `octwin login --url <platformUrl> [--token oct_…] [--wait <seconds>] [--json]
+  Sign in to a platform and make that url the DEFAULT deploy target for every
+  later command.
+
+  WITH --token: saves a token you minted yourself (console → Settings → API
+  tokens). Unchanged, and still the right answer for CI — there, skip login and
+  set PACK_PLATFORM_URL + PACK_TOKEN instead.
+
+  WITHOUT --token: prints a link to approve in a browser. A workspace admin opens
+  it, checks which machine is asking, and clicks Approve; the CLI then collects a
+  30-day token by itself, so no token is ever pasted between people. The code is
+  printed too — it is what the page shows, so you can tell it is your own request.
+  Approve only a link you opened because YOU ran this command: a link someone
+  sends you would connect THEIR machine to your workspace.
+
+  The wait is bounded (90s by default) and RESUMABLE: if nobody has approved yet
+  it exits 75 and keeps the request, so running \`octwin login\` again picks up the
   same code. --wait 0 prints the code and returns at once.`,
-    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
+    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
-    projects: `octwin projects [--archived] [--json]
-  List the workspace's projects — the slugs every --project flag takes, with the
-  plan's project cap. --archived includes archived ones. A pack:deploy token
-  reaches this (it names a project in every other command).
-
-octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
-  Create a project. The URL slug is derived from the name unless --slug pins one.
-  --pack installs an ALREADY-published pack; the usual next step is instead
-  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
-
-octwin projects rm <slug> [--yes]
-  HARD delete — the project and everything cascading from it (conversations,
-  contacts, records, installs). No undo, and not the same as archiving.
-  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
-  default. Together these make a disposable end-to-end environment:
-    octwin projects create "Scratch" && octwin deploy --project scratch --seed
-    octwin chat "hi" --project scratch
-    octwin projects rm scratch --yes
+    projects: `octwin projects [--archived] [--json]
+  List the workspace's projects — the slugs every --project flag takes, with the
+  plan's project cap. --archived includes archived ones. A pack:deploy token
+  reaches this (it names a project in every other command).
+
+octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
+  Create a project. The URL slug is derived from the name unless --slug pins one.
+  --pack installs an ALREADY-published pack; the usual next step is instead
+  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
+
+octwin projects rm <slug> [--yes]
+  HARD delete — the project and everything cascading from it (conversations,
+  contacts, records, installs). No undo, and not the same as archiving.
+  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
+  default. Together these make a disposable end-to-end environment:
+    octwin projects create "Scratch" && octwin deploy --project scratch --seed
+    octwin chat "hi" --project scratch
+    octwin projects rm scratch --yes
   Both verbs need the \`projects:write\` scope — a pack:deploy token does NOT confer it.`,
-    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-                [--request-listing | --withdraw-listing]
-  Upload the pack bundle, validate server-side, install onto the project.
-  --seed additionally applies the pack's demo seed (streams progress).
-
-  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
-  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
-
-  --request-listing    ask an operator to review this pack for the public marketplace
-                       (the pre-signup storefront at /packs). Requires 'public: true'
-                       under 'listing:' in manifest.yaml — the manifest states that the
-                       pack is a product, the flag is you choosing to ask.
-  --withdraw-listing   retract the request, including an approved listing.
-
-  An approval covers the CONTENT it was made against, so a later deploy that changes the
+    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+                [--request-listing | --withdraw-listing]
+  Upload the pack bundle, validate server-side, install onto the project.
+  --seed additionally applies the pack's demo seed (streams progress).
+
+  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
+  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
+
+  --request-listing    ask an operator to review this pack for the public marketplace
+                       (the pre-signup storefront at /packs). Requires 'public: true'
+                       under 'listing:' in manifest.yaml — the manifest states that the
+                       pack is a product, the flag is you choosing to ask.
+  --withdraw-listing   retract the request, including an approved listing.
+
+  An approval covers the CONTENT it was made against, so a later deploy that changes the
   pack returns it to the review queue on its own — no flag needed, and the CLI says so.`,
-    seed: `octwin seed [--pack <packId>]
-  Apply the pack's demo/reference data to the project it is installed on, without
-  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
-  and the demo operator topology. Reports what each kind produced.
-  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
-  than regenerated, so a second pass costs nothing. --pack is only needed when a
+    seed: `octwin seed [--pack <packId>]
+  Apply the pack's demo/reference data to the project it is installed on, without
+  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
+  and the demo operator topology. Reports what each kind produced.
+  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
+  than regenerated, so a second pass costs nothing. --pack is only needed when a
   project somehow runs more than one.`,
-    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
-  Show installed vs live version + the flow list for this pack.
-  The pack id is read from manifest.yaml and QUALIFIED with your workspace slug
-  (a manifest declares a bare name; the owner is attached when you publish). Pass
-  <packId> explicitly to skip that lookup — \`octwin agents\` and \`octwin projects\`
+    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
+  Show installed vs live version + the flow list for this pack.
+  The pack id is read from manifest.yaml and QUALIFIED with your workspace slug
+  (a manifest declares a bare name; the owner is attached when you publish). Pass
+  <packId> explicitly to skip that lookup — \`octwin agents\` and \`octwin projects\`
   both print the qualified form.`,
-    records: `octwin records [entity] [id] [--limit 50] [--offset n]
-  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
-  tickets, anything routed to a queue) read best through \`octwin work\`.
-
-  WRITES (need \`records:write\`; every one is re-checked by RBAC on the record):
-    octwin records create <entity> --set field=value [--set …] [--stage s] [--contact <id>]
-    octwin records patch  <recordId> --entity <entity> --set field=value
-    octwin records stage  <recordId> --to <stage> [--note "..."]
-    octwin records note   <recordId> "the note text"
-    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
-    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
-
-  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
-  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
-  \`patch\` needs --entity even though it has an id: the route resolves the field
-  validator from it. A leading \`create/patch/stage/note/tasks/task\` is read as a
+    records: `octwin records [entity] [id] [--limit 50] [--offset n]
+  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
+  tickets, anything routed to a queue) read best through \`octwin work\`.
+
+  WRITES (need \`records:write\`; every one is re-checked by RBAC on the record):
+    octwin records create <entity> --set field=value [--set …] [--stage s] [--contact <id>]
+    octwin records patch  <recordId> --entity <entity> --set field=value
+    octwin records stage  <recordId> --to <stage> [--note "..."]
+    octwin records note   <recordId> "the note text"
+    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
+    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
+
+  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
+  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
+  \`patch\` needs --entity even though it has an id: the route resolves the field
+  validator from it. A leading \`create/patch/stage/note/tasks/task\` is read as a
   VERB — to list an entity actually named one of those, use \`--entity <name>\`.`,
-    work: `octwin work [recordId] [--queues] [--unrouted] [--limit 50] [--offset n] [--json]
-  Inspect the work inbox — every entity the pack declares worked (cases, orders
-  needing review, applications, …): the inbox, one item + its timeline
-  (+ applicable actions), or --queues for queue keys + open counts.
-
-  WRITES (need \`work:write\`; \`stage\` needs \`records:write\`):
-    octwin work assign <recordId> --to user:<uuid>|team:<uuid>|none
-    octwin work note   <recordId> "the note text"
-    octwin work stage  <recordId> --to <stage> [--note "..."]
-    octwin work decide <recordId> --action <action> [--param k=v] [--note "..."] [--dry-run]
-
-  \`decide\` applies one of the entity's declared operator actions — \`octwin work <id>\`
-  lists them with their params. --dry-run previews the customer-facing copy and the
-  resulting stage WITHOUT committing (that route needs only \`work:read\`).
+    work: `octwin work [recordId] [--queues] [--unrouted] [--limit 50] [--offset n] [--json]
+  Inspect the work inbox — every entity the pack declares worked (cases, orders
+  needing review, applications, …): the inbox, one item + its timeline
+  (+ applicable actions), or --queues for queue keys + open counts.
+
+  WRITES (need \`work:write\`; \`stage\` needs \`records:write\`):
+    octwin work assign <recordId> --to user:<uuid>|team:<uuid>|none
+    octwin work note   <recordId> "the note text"
+    octwin work stage  <recordId> --to <stage> [--note "..."]
+    octwin work decide <recordId> --action <action> [--param k=v] [--note "..."] [--dry-run]
+
+  \`decide\` applies one of the entity's declared operator actions — \`octwin work <id>\`
+  lists them with their params. --dry-run previews the customer-facing copy and the
+  resulting stage WITHOUT committing (that route needs only \`work:read\`).
   \`stage\` is the XRM records verb (one transition spelling platform-wide).`,
-    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).`,
-    pull: `octwin pull <packId> [--dir <out>] [--version <v>] [--force]
-  Write a DEPLOYED pack's source back to disk — the inverse of deploy.
-  A pack pushed with 'octwin deploy' lives on the platform as an artifact the
-  runtime serves but nothing hands back, so its only source copy is the machine
-  that pushed it. Pull it, fix it, redeploy it.
-  Defaults to the version installed on the target project; --version overrides.
-  --dir defaults to ./<packId>; a non-empty dir needs --force.
-  The pulled dir redeploys where it came from — the target is your saved login.
+    pull: `octwin pull <packId> [--dir <out>] [--version <v>] [--force]
+  Write a DEPLOYED pack's source back to disk — the inverse of deploy.
+  A pack pushed with 'octwin deploy' lives on the platform as an artifact the
+  runtime serves but nothing hands back, so its only source copy is the machine
+  that pushed it. Pull it, fix it, redeploy it.
+  Defaults to the version installed on the target project; --version overrides.
+  --dir defaults to ./<packId>; a non-empty dir needs --force.
+  The pulled dir redeploys where it came from — the target is your saved login.
   You may pull a pack your tenant OWNS (deployed); an operator token pulls any.`,
-    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
-       octwin chat --script <file> [--as <handle>] [--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.
-
-  --script drives a WHOLE conversation from a file, ONE TURN PER LINE, in one
-  process over one connection — waiting for each turn to settle before sending
-  the next. Use this for any multi-step flow: chaining shell invocations races
-  the agent loop, because a turn ends on a quiet gap that can arrive while the
-  server is still working (the symptom is placeholder-filled fields or a second
-  workflow run). Blank lines and # comments are skipped:
-
-    # book an appointment end to end
-    احجز موعد
-    tap:t:invoke:book-appointment:doctor_id=D1
-    media:./licence.jpg | here is my licence
+    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
+       octwin chat --script <file> [--as <handle>] [--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.
+
+  --script drives a WHOLE conversation from a file, ONE TURN PER LINE, in one
+  process over one connection — waiting for each turn to settle before sending
+  the next. Use this for any multi-step flow: chaining shell invocations races
+  the agent loop, because a turn ends on a quiet gap that can arrive while the
+  server is still working (the symptom is placeholder-filled fields or a second
+  workflow run). Blank lines and # comments are skipped:
+
+    # book an appointment end to end
+    احجز موعد
+    tap:t:invoke:book-appointment:doctor_id=D1
+    media:./licence.jpg | here is my licence
     tap:t:resume:book-appointment:run_id=R1;_ctl_approved=true`,
-    media: `octwin media generate "<prompt>" [--out <file.png>] [--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>] [--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,
   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.
-
-  WRITES (need \`agents:write\`):
-    octwin agents set <ref> [--model <m>] [--enabled true|false] [--overlay "..."|none]
-                            [--enable-tool <toolId>] [--disable-tool <toolId>]
-
-  Only what you pass is changed. Tool flags read-modify-write \`config_json.tools\`
-  so a sibling decision isn't dropped; absent = enabled. A workspace that hides model
+    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.
+
+  WRITES (need \`agents:write\`):
+    octwin agents set <ref> [--model <m>] [--enabled true|false] [--overlay "..."|none]
+                            [--enable-tool <toolId>] [--disable-tool <toolId>]
+
+  Only what you pass is changed. Tool flags read-modify-write \`config_json.tools\`
+  so a sibling decision isn't dropped; absent = enabled. A workspace that hides model
   ids refuses --model with a 403 — the platform default governs there.`,
-    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.
-
-  WRITES (need \`orders:write\`):
-    octwin orders transition <reference_id> --to <status>
-    octwin orders refund     <reference_id> [--reason "..."] [--mark-returned] --force
-
-  Refund is irreversible and moves money, hence --force. The route answers 200 even
-  when the GATEWAY refuses, so the CLI reads the gateway verdict and exits non-zero
-  on a refusal rather than reporting a refund that never happened. Only a payment in
+    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.
+
+  WRITES (need \`orders:write\`):
+    octwin orders transition <reference_id> --to <status>
+    octwin orders refund     <reference_id> [--reason "..."] [--mark-returned] --force
+
+  Refund is irreversible and moves money, hence --force. The route answers 200 even
+  when the GATEWAY refuses, so the CLI reads the gateway verdict and exits non-zero
+  on a refusal rather than reporting a refund that never happened. Only a payment in
   \`captured\` state can be refunded; \`payment_status\` is never settable directly.`,
-    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
+    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.
-
-  WRITES (need \`catalog:write\`):
-    octwin catalog availability <retailerId> --to "in stock"|"out of stock"|…
-    octwin catalog stock        <retailerId> [--set-on-hand <n>]
-
-  \`stock\` with no --set-on-hand READS it; \`null\` means the SKU is not
-  inventory-tracked (always sellable), which is different from 0. Lowering on_hand
-  below the units already reserved for open carts is refused. Creating/deleting
+    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.
+
+  WRITES (need \`catalog:write\`):
+    octwin catalog availability <retailerId> --to "in stock"|"out of stock"|…
+    octwin catalog stock        <retailerId> [--set-on-hand <n>]
+
+  \`stock\` with no --set-on-hand READS it; \`null\` means the SKU is not
+  inventory-tracked (always sellable), which is different from 0. Lowering on_hand
+  below the units already reserved for open carts is refused. Creating/deleting
   products and the Meta catalog binding/sync stay in the console.`,
-    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.
-
-  RULES (list needs scheduling:read; add/rm need scheduling:write):
-    octwin scheduling rules --resource <resourceRecordId>
-    octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00
-                               [--slot-minutes 30] [--capacity 1]
-    octwin scheduling rule rm  <ruleId>
-    octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra
-                                    [--start 09:00 --end 13:00]
-    octwin scheduling exception rm  <exceptionId>
-
-  --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
+    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.
+
+  RULES (list needs scheduling:read; add/rm need scheduling:write):
+    octwin scheduling rules --resource <resourceRecordId>
+    octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00
+                               [--slot-minutes 30] [--capacity 1]
+    octwin scheduling rule rm  <ruleId>
+    octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra
+                                    [--start 09:00 --end 13:00]
+    octwin scheduling exception rm  <exceptionId>
+
+  --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
   \`--slots\` is how you check what a rule actually produces.`,
-    automation: `octwin automation [campaigns] [--limit n] [--offset n] [--json]
-  No args = every job the pack's automation declaration produced, with its status,
-  interval and LAST RESULT (matched / acted / errors), under a health line whose
-  counts come from SQL rather than from filtering the page — the job list is capped
-  server-side, so a client-side count would depend on the cap. Needs automation:read.
-
-  Jobs are DERIVED from declarations. There is no \`create\`: no automation block in
-  the pack means no jobs, and \`octwin deploy\` is what installs them.
-
-  WRITES (automation:write):
-    octwin automation run <jobId>          # run once, now — prints matched/acted/errors
-    octwin automation pause|resume <jobId>
-    octwin automation send <campaignId>    # enqueue a campaign; enqueued != delivered
-
-  <jobId> is the \`key\` the list shows (its uuid works too). The routes themselves
-  accept only a uuid — the CLI resolves the key for you, and names the keys that do
-  exist when it cannot. A 403 on a write can be an RBAC grant gap rather than a
+    automation: `octwin automation [campaigns] [--limit n] [--offset n] [--json]
+  No args = every job the pack's automation declaration produced, with its status,
+  interval and LAST RESULT (matched / acted / errors), under a health line whose
+  counts come from SQL rather than from filtering the page — the job list is capped
+  server-side, so a client-side count would depend on the cap. Needs automation:read.
+
+  Jobs are DERIVED from declarations. There is no \`create\`: no automation block in
+  the pack means no jobs, and \`octwin deploy\` is what installs them.
+
+  WRITES (automation:write):
+    octwin automation run <jobId>          # run once, now — prints matched/acted/errors
+    octwin automation pause|resume <jobId>
+    octwin automation send <campaignId>    # enqueue a campaign; enqueued != delivered
+
+  <jobId> is the \`key\` the list shows (its uuid works too). The routes themselves
+  accept only a uuid — the CLI resolves the key for you, and names the keys that do
+  exist when it cannot. A 403 on a write can be an RBAC grant gap rather than a
   missing scope: the action is re-checked against the job.`,
-    integrations: `octwin integrations [--json]
-  What the pack DECLARES beside what is actually CONFIGURED, in one view — because a
-  connection that is declared and never configured is the commonest reason an
-  integration silently never fires, and neither list alone can show it. Flags the
-  gap explicitly. Needs integrations:read.
-
-  DIAGNOSE ONE CONNECTION:
-    octwin integrations preflight <key>    # every check, with a fix hint. Makes NO
-                                           # outbound call — needs only integrations:read
-    octwin integrations test <key>         # a LIVE call to its health: operation
-                                           # (integrations:write). Exits 1 when it fails.
-
-  THE DELIVERY LOG:
-    octwin integrations deliveries [--status s] [--operation id] [--limit n]
-    octwin integrations deliveries <id>    # + the redacted request/response snapshots
-    octwin integrations retry|cancel|send-now <id>     # integrations:write
-    octwin integrations events             # INBOUND events (what arrived at your webhook)
-
-  retry/cancel answer 409 when the delivery is in the wrong state; the message
+    integrations: `octwin integrations [--json]
+  What the pack DECLARES beside what is actually CONFIGURED, in one view — because a
+  connection that is declared and never configured is the commonest reason an
+  integration silently never fires, and neither list alone can show it. Flags the
+  gap explicitly. Needs integrations:read.
+
+  DIAGNOSE ONE CONNECTION:
+    octwin integrations preflight <key>    # every check, with a fix hint. Makes NO
+                                           # outbound call — needs only integrations:read
+    octwin integrations test <key>         # a LIVE call to its health: operation
+                                           # (integrations:write). Exits 1 when it fails.
+
+  THE DELIVERY LOG:
+    octwin integrations deliveries [--status s] [--operation id] [--limit n]
+    octwin integrations deliveries <id>    # + the redacted request/response snapshots
+    octwin integrations retry|cancel|send-now <id>     # integrations:write
+    octwin integrations events             # INBOUND events (what arrived at your webhook)
+
+  retry/cancel answer 409 when the delivery is in the wrong state; the message
   carries the rule.`,
-    journeys: `octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]
-                  [--stage <stageId>] [--limit n] [--json]
-  No args = the journeys the pack declares. With an id, one of six views —
-  --funnel (default) stage-by-stage reach and drop-off · --overview entered vs
-  converted plus the biggest drop-off · --goals completions, contacts, value and
-  p50 time · --trends per-bucket activity · --cost tokens and dollars per goal ·
-  --definition what was DECLARED, unmeasured (the one view that works with no
-  traffic). Needs journeys:read.
-
-  --stage <stageId> lists the runs sitting at a stage right now (a live snapshot,
-  not the funnel's cumulative reached counts).
-
-  Same flag grammar as \`octwin analytics\` on purpose: a journey funnel and an
-  entity funnel are the same question about different subjects. Journeys carry RBAC
-  on top of the scope, so an empty answer can be a missing \`view\` grant rather
+    journeys: `octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]
+                  [--stage <stageId>] [--limit n] [--json]
+  No args = the journeys the pack declares. With an id, one of six views —
+  --funnel (default) stage-by-stage reach and drop-off · --overview entered vs
+  converted plus the biggest drop-off · --goals completions, contacts, value and
+  p50 time · --trends per-bucket activity · --cost tokens and dollars per goal ·
+  --definition what was DECLARED, unmeasured (the one view that works with no
+  traffic). Needs journeys:read.
+
+  --stage <stageId> lists the runs sitting at a stage right now (a live snapshot,
+  not the funnel's cumulative reached counts).
+
+  Same flag grammar as \`octwin analytics\` on purpose: a journey funnel and an
+  entity funnel are the same question about different subjects. Journeys carry RBAC
+  on top of the scope, so an empty answer can be a missing \`view\` grant rather
   than missing data — the output says which causes are possible.`,
-    performance: `octwin performance [--detail] [--json]
-  The project's business indicators — value produced, conversion, duration — each
-  with its delta against the previous window and a \`why\` naming the declaration it
-  came from. --detail adds the per-indicator breakdown.
-
-  Needs records:read, NOT a performance scope (there is none), so a read-only token
-  already reaches it. Indicators are DERIVED: a pack that declares no journey goal
+    performance: `octwin performance [--detail] [--json]
+  The project's business indicators — value produced, conversion, duration — each
+  with its delta against the previous window and a \`why\` naming the declaration it
+  came from. --detail adds the per-indicator breakdown.
+
+  Needs records:read, NOT a performance scope (there is none), so a read-only token
+  already reaches it. Indicators are DERIVED: a pack that declares no journey goal
   value and no pipelined entity produces none, which is a different thing from zero.`,
-    usage: `octwin usage [--json]
-  Model calls, tokens and cost for the resolved scope — project when one is pinned
-  or passed with --project, otherwise the whole workspace. Broken down by model,
-  kind, agent and channel.
-
-  Needs no particular scope: any valid token reaches it.
-
-  This is MODEL spend only. WhatsApp/Meta message billing is operator-only and
+    usage: `octwin usage [--json]
+  Model calls, tokens and cost for the resolved scope — project when one is pinned
+  or passed with --project, otherwise the whole workspace. Broken down by model,
+  kind, agent and channel.
+
+  Needs no particular scope: any valid token reaches it.
+
+  This is MODEL spend only. WhatsApp/Meta message billing is operator-only and
   deliberately outside the token scope registry — no API token can read it.`,
-    'platform-kb': `octwin platform-kb [pull] [--if-stale] [--check] [--dir .] [--url <url>] [--token <t>]
-  Pull the platform capability reference (markdown + JSON catalogs) into
-  .octwin/platform-kb/ for the octwin-pack authoring skill, plus three maps:
-  INDEX.md (the corpus) · SYMBOLS.md (every name -> its file; grep this) ·
-  OUTLINE.md (every heading with its line number).
-
-  NO TOKEN NEEDED — the reference is platform stdlib and is served anonymously,
-  and this command never sends one. --token is accepted and ignored, so an older
-  script that passes it keeps working.
-
-  --if-stale   poll the platform's content_hash first and skip the download when
-               nothing changed. Cheap enough to run at the start of every session.
-  --check      report only, write nothing. Exit 0 = current, 2 = stale or never
-               pulled, 1 = could not tell (offline / no reference served). For
+    'platform-kb': `octwin platform-kb [pull] [--if-stale] [--check] [--dir .] [--url <url>] [--token <t>]
+  Pull the platform capability reference (markdown + JSON catalogs) into
+  .octwin/platform-kb/ for the octwin-pack authoring skill, plus three maps:
+  INDEX.md (the corpus) · SYMBOLS.md (every name -> its file; grep this) ·
+  OUTLINE.md (every heading with its line number).
+
+  NO TOKEN NEEDED — the reference is platform stdlib and is served anonymously,
+  and this command never sends one. --token is accepted and ignored, so an older
+  script that passes it keeps working.
+
+  --if-stale   poll the platform's content_hash first and skip the download when
+               nothing changed. Cheap enough to run at the start of every session.
+  --check      report only, write nothing. Exit 0 = current, 2 = stale or never
+               pulled, 1 = could not tell (offline / no reference served). For
                scripts and agent loops that want to branch without parsing prose.`,
-    test: `octwin test [--dir .]
+    test: `octwin test [--dir .]
   Alias for \`octwin validate --remote\` — the full platform check.`,
-    memos: `octwin memos [--all] [--json]
-  Read what the platform has told you: a REPLY to a report you sent with
-  \`octwin feedback\`, or a NOTICE published to every author (a new capability,
-  a deprecation, a breaking change). Bodies are printed in full.
-  Reading marks them read, so the reminder stops. --all re-reads history and
-  acks nothing. --json to branch on \`severity\`
+    memos: `octwin memos [--all] [--json]
+  Read what the platform has told you: a REPLY to a report you sent with
+  \`octwin feedback\`, or a NOTICE published to every author (a new capability,
+  a deprecation, a breaking change). Bodies are printed in full.
+  Reading marks them read, so the reminder stops. --all re-reads history and
+  acks nothing. --json to branch on \`severity\`
   (info | action_required | breaking).`,
-    feedback: `octwin feedback [--dir .]
-  Submit this pack's FEEDBACK.md to the platform team.
-  The octwin-pack skill writes that file in its last step — findings grouped by
-  owner (A · CLI, B · Platform, C · Skill/KB). This delivers it instead of asking
-  you to paste it into a chat.
-  Attaches the pack id + version from manifest.yaml, this CLI's version, and the
-  content_hash of the capability reference in .octwin/platform-kb/ — triage needs
-  the last two to tell "the platform is wrong" from "that was already fixed" or
+    feedback: `octwin feedback [--dir .]
+  Submit this pack's FEEDBACK.md to the platform team.
+  The octwin-pack skill writes that file in its last step — findings grouped by
+  owner (A · CLI, B · Platform, C · Skill/KB). This delivers it instead of asking
+  you to paste it into a chat.
+  Attaches the pack id + version from manifest.yaml, this CLI's version, and the
+  content_hash of the capability reference in .octwin/platform-kb/ — triage needs
+  the last two to tell "the platform is wrong" from "that was already fixed" or
   "you were reading a stale reference". Needs the \`pack:deploy\` scope.`,
 };
 async function main() {

package/dist/lib/args-check.js

@@ -58,6 +58,11 @@ export function loadPrimitiveArgSpecs(packDir) {
                 required: Array.isArray(schema.required) ? schema.required : [],
                 open: ap !== undefined && ap !== false,
                 requiresOneOf: Array.isArray(entry.requiresOneOf) ? entry.requiresOneOf : [],
+                // Kept only when BOTH halves are present. A pair with no message would print a warning
+                // that names two argument keys and says nothing about why they are a trap — which is the
+                // sort of warning authors learn to scroll past.
+                warnsTogether: (entry.warnsTogether ?? [])
+                    .filter((w) => Array.isArray(w?.args) && w.args.length > 0 && typeof w?.message === 'string' && w.message.length > 0),
             });
         }
     }
@@ -74,6 +79,10 @@ export function loadPrimitiveArgSpecs(packDir) {
  * primitive's declared set. Walks the whole document rather than just `steps:`
  * — a `do:` is legal in a `foreach` body, a `collect` hook, an `outputs:` port
  * body and `require:`, and a dropped argument is just as invisible there.
+ *
+ * Warnings come back on their own list rather than mixed into `ArgFinding`. They have a different
+ * severity, a different exit code, and a different sentence — folding them together would have
+ * meant either failing a build over a warning or hiding an error inside a warning count.
  */
 export function findArgViolations(doc, file, specs) {
     const findings = [];
@@ -107,6 +116,52 @@ export function findArgViolations(doc, file, specs) {
     walk(doc, []);
     return findings;
 }
+/**
+ * Walk for `do:` nodes whose `args:` supply every member of a declared `warnsTogether` pair.
+ *
+ * A separate walk rather than a second output of `findArgViolations`, on purpose: that function
+ * skips a primitive whose schema is OPEN (`!spec.open`), because an open schema makes "unknown
+ * key" unanswerable. A `warnsTogether` pair is answerable either way — it names two keys that ARE
+ * declared — so gating it on closedness would silently drop the check for every passthrough
+ * primitive, which is exactly the shape of hole a scan grows without anyone noticing.
+ */
+export function findArgWarnings(doc, file, specs) {
+    const warnings = [];
+    const walk = (node, path) => {
+        if (Array.isArray(node)) {
+            node.forEach((v, i) => walk(v, [...path, i]));
+            return;
+        }
+        if (!node || typeof node !== 'object')
+            return;
+        const obj = node;
+        if (typeof obj.do === 'string') {
+            const spec = specs.get(obj.do);
+            if (spec?.warnsTogether.length) {
+                const args = (obj.args && typeof obj.args === 'object' && !Array.isArray(obj.args))
+                    ? obj.args
+                    : {};
+                for (const pair of spec.warnsTogether) {
+                    // KEY PRESENCE only, matching the platform's own `checkPrimitiveArgs`. The values are
+                    // almost always expressions (`record_id: '$found.record_id'`), so judging them would
+                    // mean judging a string — and the trap is about the combination, not the values.
+                    if (pair.args.every(k => k in args)) {
+                        warnings.push({ file, primitive: obj.do, path: [...path], args: [...pair.args], message: pair.message });
+                    }
+                }
+            }
+        }
+        for (const [k, v] of Object.entries(obj))
+            walk(v, [...path, k]);
+    };
+    walk(doc, []);
+    return warnings;
+}
+/** One line per warning: where, which pair, and the primitive's own reason. */
+export function describeArgWarning(w) {
+    const at = w.line ? `${w.file}:${w.line}` : w.file;
+    return `${at}: \`${w.primitive}\` passes ${w.args.map(a => `'${a}'`).join(' + ')} together — ${w.message}`;
+}
 /** One-line human message per finding. */
 export function describeArgFinding(f) {
     const parts = [];

package/dist/lib/outcome.js

@@ -56,6 +56,17 @@ export function reportChecks(checks, io) {
                 io.die(outcome.hint);
             }
             // eslint-disable-next-line no-fallthrough -- `die` returns never; the case above cannot exit.
+            case 'warnings': {
+                // On `log`, not `err`, and the run CONTINUES. A warning that stopped the run, or that
+                // arrived on the error stream, would be an error wearing a different word — and the next
+                // check is the one the author was actually waiting for.
+                const n = outcome.lines.length;
+                io.log(`⚠ ${n} ${outcome.noun}${n === 1 ? '' : 's'} — not fatal:`);
+                for (const line of outcome.lines)
+                    io.log(`  ⚠ ${line}`);
+                io.log(`  ${outcome.hint}`);
+                break;
+            }
             case 'not-run':
                 notRun.push({ label: check.label, lookup: outcome.lookup });
                 break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {
@@ -41,6 +41,6 @@
     "yaml"
   ],
   "author": "CEQUENS",
-  "homepage": "https://www.npmjs.com/package/octwin-cli",
+  "homepage": "https://octwin.ai",
   "license": "MIT"
 }