octwin-cli 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.8.5] - 2026-09-02
+
+### Added
+- **`octwin work --unrouted`** — the inbox filtered to items in NO queue. The route has always
+  supported the filter; the CLI never passed it, so `--queues` could tell you a count and not
+  show you the items behind it.
+
+### Changed
+- **`octwin work --queues` leads with the unrouted count.** It was already printed, as
+  `(unrouted: N open)` tucked under the queue list. A routed item sits in a list someone works;
+  an unrouted one sits in nobody's, so it is the only line on that screen that means "these are
+  lost". It is now a warning block that names the likely cause and points at `--unrouted`. Still
+  silent at zero — a clean project stays quiet, or the warning stops meaning anything.
+
 ## [0.8.4] - 2026-09-02
 
 ### Fixed

package/dist/index.js

@@ -18,7 +18,7 @@
  *   octwin pull    <packId> [--dir <out>] [--version v] [--force]  # write a DEPLOYED pack's source back to disk
  *   octwin status  [<packId>]       # did my deploy land? which version is live?
  *   octwin records [entity] [id]    # inspect the pack's XRM data (records:read token)
- *   octwin work    [recordId] [--queues]   # inspect the work inbox (worked records) — list / one item + timeline
+ *   octwin work    [recordId] [--queues] [--unrouted]   # inspect the work inbox (worked records) — list / one item + timeline
  *   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 chat    --script <file> [--as h]   # drive a WHOLE conversation, one turn per line (the reliable way to test a flow)
@@ -1622,7 +1622,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}`);
@@ -3155,12 +3155,36 @@ async function cmdWork(flags) {
             const name = pickLabel(q.name);
             console.log(`  ${q.key}${name ? `  (${name})` : ''}  ${q.open_count} open`);
         }
-        if (json?.unrouted_open_count)
-            console.log(`  (unrouted: ${json.unrouted_open_count} open)`);
+        /**
+         * UNROUTED LEADS, because it is the finding — not a footnote to the list.
+         *
+         * The count was already here, as `(unrouted: N open)` tucked under the queues. That
+         * is the wrong weight: a routed item is in a list someone works, and an unrouted one
+         * is in NOBODY's list — it is the only line on this screen that means "these are
+         * lost". A pack author spent five deploys cornering exactly that state in 2026-09
+         * and reported `--queues` as the tool that finally showed it, which is the argument
+         * for making it unmissable rather than for adding it.
+         *
+         * Still silent at zero: a clean project must stay quiet, or the warning stops
+         * meaning anything.
+         */
+        const unrouted = Number(json?.unrouted_open_count ?? 0);
+        if (unrouted > 0) {
+            console.log(`\n⚠ ${unrouted} open item(s) are UNROUTED — in no queue, so nobody sees them.`);
+            console.log(`   Usually a routing declaration that resolves to nothing: check the item's`);
+            console.log(`   type against \`work.<entity>.types\` in worklist.yaml, and that the entity`);
+            console.log(`   has a \`queue:\`/\`route_by\` default for types that declare none.`);
+            console.log(`   List them:  octwin work --unrouted`);
+        }
         return;
     }
     if (!recordId) {
-        const { status, json } = await apiGet(`${base}/work?${pagingQs(flags)}`, t);
+        // `--unrouted` narrows the inbox to the items in NO queue. The route has always
+        // supported the filter; the CLI never passed it, so the count on `--queues` named a
+        // problem it could not then show you. A number you cannot drill into is a dead end.
+        const onlyUnrouted = flags.unrouted === true;
+        const qs = `${pagingQs(flags)}${onlyUnrouted ? '&unrouted=true' : ''}`;
+        const { status, json } = await apiGet(`${base}/work?${qs}`, t);
         if (status !== 200)
             workFail('the work inbox', status, json);
         if (asJson) {
@@ -3168,9 +3192,9 @@ async function cmdWork(flags) {
             return;
         }
         const page = readPage(json);
-        console.log(`Work items in ${targetLabel(t)}: ${page.total ?? page.rows.length} total`);
+        console.log(`${onlyUnrouted ? 'UNROUTED work items' : 'Work items'} in ${targetLabel(t)}: ${page.total ?? page.rows.length} total`);
         if (page.rows.length === 0)
-            console.log('  (none)');
+            console.log(onlyUnrouted ? '  (none — everything is routed)' : '  (none)');
         for (const w of page.rows) {
             const sla = w.sla_due_at ? `  sla:${w.sla_due_at}` : '';
             console.log(`  #${w.record_number ?? '?'}  ${w.entity}${w.type ? `/${w.type}` : ''}  [${w.stage ?? '?'}]  ${w.priority}${w.queue_key ? `  q:${w.queue_key}` : ''}${sla}  ${w.record_id}`);
@@ -4956,371 +4980,372 @@ 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> --token oct_…      # 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] [--json]          # inspect the work inbox (worked records) + timelines
-  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
-  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
-  octwin media   generate "<prompt>" [--out <file.png>] [--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).
-Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
-octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
-Config (deploy): flags > 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> --token oct_…      # 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).
+Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
+octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
+Config (deploy): flags > 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_…
-  Save a deploy token (console → Settings → API tokens) for that platform url,
-  make that url the DEFAULT deploy target for every later command, and echo the
+    login: `octwin login --url <platformUrl> --token oct_…
+  Save a deploy token (console → Settings → API tokens) for that platform url,
+  make that url the DEFAULT deploy target for every later command, and echo the
   workspace + project pin + scopes the token reaches.`,
-    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
+    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
-    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] [--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/package.json

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