octwin-cli 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.6.1] - 2026-08-18
+
+### Fixed
+- **`octwin status` worked for no pack at all, and had not since 2026-08-01.** It sent the manifest's
+  **bare** id (`clinic`) to a route that requires the qualified `<owner>.<name>` — and a manifest
+  cannot legally declare the qualified form, because the owner segment is attached at publish time
+  from the authenticated publisher (both the platform and this CLI reject a `.` in it). So the route
+  answered 404 for every pack, every time. It now resolves the owner from `whoami`'s `tenant_slug`,
+  and takes an explicit `octwin status <packId>` when you already know it (from `octwin agents` or
+  `octwin projects`, both of which print qualified ids). Reported by two pack authors, who lost time
+  to a command that said their pack was missing seconds after a deploy the platform had accepted.
+- **A 404 from `octwin status` no longer always reads "not installed".** That one branch covered four
+  different failures — a malformed pack id, an unknown tenant, an unknown/pinned-elsewhere project,
+  and the genuine no-active-install — so the message named the *least* likely cause and sent an author
+  chasing a deploy that had already succeeded. The route says which; the CLI now relays it, and adds
+  the "run `octwin deploy` first" hint only to the case it fits.
+- **`octwin logs` always reported "No conversations"**, including immediately after an `octwin chat`
+  that had plainly worked. It read `conversations` off the response; the platform moved that endpoint
+  to the shared page envelope on 2026-08-09 and answers `rows`, which every other list command here
+  already reads. Both authors filed this as replica lag or a cache gap — nothing lagged, the payload
+  was simply never read. `octwin logs <conversationId>` was unaffected.
+
 ## [0.6.0] - 2026-08-09
 
 ### Changed

package/README.md

@@ -80,7 +80,7 @@ octwin status               # "✓ live and current" once it's warm
 | `octwin analytics` | Stage-by-stage conversion for **any** entity declared with a `pipeline:` (`--overview` / `--milestones` / `--trends` / `--cost`; `--stage <id>` lists the records currently at a stage). Needs `records:read`. |
 | `octwin catalog` | Commerce products with price / availability / stock, plus the WhatsApp catalog binding. `--readiness` runs the Meta Graph checklist. Needs `catalog:read` + the `catalog` plan feature. |
 | `octwin scheduling` | The scheduling engine's state, or `--slots <resourceRecordId>` for the slots one bookable resource actually computes — how you verify the availability rules `deploy --seed` created. Needs `scheduling:read`. |
-| `octwin media generate "<prompt>"` | AI-generate an image, store it as a public asset, and print its `MEDIA-` handle + serve URL. `--out` downloads the bytes (WhatsApp renders only `.png`/`.jpg`); `--size`; `--json`. Pairs with `octwin chat --media` to drive media-collect flows. Needs `media:generate`. |
+| `octwin media generate "<prompt>"` | AI-generate an image, store it as a public asset, and print its `MEDIA-` handle + serve URL. `--out` downloads the bytes (WhatsApp renders only `.png`/`.jpg`); `--json`. Pairs with `octwin chat --media` to drive media-collect flows. Needs `media:generate`. |
 | `octwin platform-kb pull` | Pull the platform's capability reference into `.octwin/platform-kb/` for the **`octwin-pack`** Claude Code authoring plugin: guides as markdown, plus **one JSON file per capability** (`primitives/record_list.json`, `render-intents/carousel.json`, `declarations/xrm.json`, …) and **three maps** — `INDEX.md` (the corpus, by family and size), `SYMBOLS.md` (every name → its exact file; grep this), `OUTLINE.md` (every heading with its line number). **No token needed** — the reference is served anonymously. `--if-stale` skips the download when your copy is current (cheap enough for every session); `--check` writes nothing and exits 0 current / 2 stale / 1 could-not-tell. |
 | `octwin test` | Alias for `octwin validate --remote` — the platform's full manifest + flow-DSL check. |
 | `octwin feedback` | Submit this pack's `FEEDBACK.md` to the platform team, with the pack version, your CLI version and the `content_hash` of the capability reference you pulled — the two facts that separate a real platform gap from something already fixed or a stale KB. |

package/dist/index.js

@@ -15,13 +15,13 @@
  *   octwin projects [--archived]    # the --project slugs this token can name
  *   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
  *   octwin pull    <packId> [--dir <out>] [--version v] [--force]  # write a DEPLOYED pack's source back to disk
- *   octwin status  [--dir .]        # did my deploy land? which version is live?
+ *   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 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)
- *   octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (media:generate scope)
+ *   octwin media   generate "<prompt>" [--out <file.png>] [--json]  # AI-generate an image → MEDIA- handle (media:generate scope)
  *   octwin agents  [packId::agentId] [--prompt]   # effective model/memory + which layer won; --prompt = the resolved system prompt
  *   octwin orders  [reference_id]    # the orders a conversation produced — money breakdown + payment state (orders:read)
  *   octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion, any pipelined entity
@@ -62,6 +62,7 @@ import { validatePackBundle, describePackNameProblem, asPackName } from './lib/v
 import { loadAllowedRenderKeys, findRenderKeyViolations, describeRenderFinding } from './lib/render-check.js';
 import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding } from './lib/args-check.js';
 import { yamlLineOf } from './lib/yaml-pos.js';
+import { localhostFamilyHint } from './lib/net-hint.js';
 import { loadBuiltinNames, findBuiltinViolations, describeBuiltinFinding } from './lib/builtin-check.js';
 import { loadTemplateSpecs, findTemplateViolations, describeTemplateFinding } from './lib/template-check.js';
 import { loadSystemEntities, findEntityViolations, describeEntityFinding } from './lib/entity-check.js';
@@ -164,7 +165,8 @@ async function fetchOrDie(url, init, what) {
         return await fetch(url, init);
     }
     catch (err) {
-        die(`${what} — platform unreachable at ${url} (${err?.message ?? err})`);
+        const hint = localhostFamilyHint(url, err);
+        die(`${what} — platform unreachable at ${url} (${err?.message ?? err})${hint ? `\n  ${hint}` : ''}`);
     }
 }
 /** One consistent explanation for auth failures on admin reads. A 401 can also
@@ -748,7 +750,7 @@ async function cmdValidate(flags) {
     const withLines = (fs) => fs.map(f => ({ ...f, line: files[f.file] ? yamlLineOf(files[f.file], f.path) : null }));
     const render = loadAllowedRenderKeys(packDir);
     if (render.keys) {
-        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findRenderKeyViolations(doc, p, render.keys)));
+        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findRenderKeyViolations(doc, p, render.keys, render.nested)));
         if (findings.length) {
             console.error(`✗ ${findings.length} render-intent field error${findings.length === 1 ? '' : 's'}:`);
             for (const f of findings)
@@ -896,10 +898,16 @@ async function cmdValidate(flags) {
     const t = resolveTarget(flags);
     const { url } = t;
     console.log(`→ Validating against ${targetLabel(t)} @ ${url} …`);
+    // `--strict-primitives` (opt-in): the server additionally type-checks LITERAL
+    // `args:` values against each primitive's per-key input schema. Expression
+    // strings are always exempt — this judges only plain YAML scalars.
     const res = await fetchOrDie(`${url}/api/self/p/packs/validate`, {
         method: 'POST',
         headers: { 'content-type': 'application/json', ...authHeaders(t) },
-        body: JSON.stringify({ files, blobs }),
+        body: JSON.stringify({
+            files, blobs,
+            ...(flags['strict-primitives'] === true ? { strict_primitives: true } : {}),
+        }),
     }, 'remote validate');
     const text = await res.text();
     let json;
@@ -1257,13 +1265,13 @@ async function cmdSeed(flags) {
         const { terminal: final, stepErrors } = await readDeployProgress(res.body);
         if (!final || final.stage === 'error')
             die(`seed failed${final?.message ? `: ${final.message}` : ' (stream ended early)'}`);
-        console.log(`
+        console.log(`
 ✓ ${final.message ?? 'seed complete'}`);
         printSeedCounts(final.result?.seeded);
         if (stepErrors.length) {
             // A kind failed but the rest ran — the reconcile softens each step. Say which,
             // and exit non-zero so a scripted `seed && chat` doesn't read as clean.
-            console.error(`
+            console.error(`
 ⚠ ${stepErrors.length} step${stepErrors.length === 1 ? '' : 's'} failed — data may be incomplete:`);
             for (const e of stepErrors)
                 console.error(`   • ${e}`);
@@ -1345,6 +1353,33 @@ async function cmdDeploy(flags) {
     }
     printDeploySuccess(id, version, t, json);
 }
+/**
+ * The QUALIFIED pack id (`<owner>.<name>`) for a manifest's bare name.
+ *
+ * A manifest declares a bare name and cannot legally declare anything else — the platform
+ * and this CLI both reject a `.` in it, because the owner segment is attached at publish
+ * time from the authenticated publisher. Every route that takes a pack id in its PATH
+ * requires the qualified form, so a command holding only a manifest has to ask who it is.
+ *
+ * `whoami`'s `tenant_slug` IS the owner segment. Without this, `octwin status` sent the bare
+ * name, `asPackId` rejected it, and the route's 404 was reported as "not installed" — so the
+ * command was structurally broken for every pack from the day ids gained owners
+ * (2026-08-01) until this was fixed, while the KB still taught it as step 4 of the loop.
+ */
+async function qualifiedPackId(t, bareName) {
+    if (bareName.includes('.'))
+        return bareName; // already qualified (explicit override)
+    const res = await fetchOrDie(`${t.url}/api/self/t/whoami`, { headers: authHeaders(t) }, 'workspace lookup');
+    if (!res.ok) {
+        printAuthHint(res.status, t.url);
+        die(`could not resolve your workspace to qualify the pack id (HTTP ${res.status}) — pass the full '<owner>.${bareName}' instead`);
+    }
+    const j = await res.json();
+    if (typeof j.tenant_slug !== 'string' || !j.tenant_slug) {
+        die(`the platform did not report a workspace slug — pass the full '<owner>.${bareName}' instead`);
+    }
+    return `${j.tenant_slug}.${bareName}`;
+}
 async function cmdStatus(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const t = resolveTarget(flags);
@@ -1355,8 +1390,11 @@ async function cmdStatus(flags) {
     const doc = parseYaml(readFileSync(manifestPath, 'utf8'));
     if (typeof doc?.id !== 'string')
         die('manifest.yaml must declare a string `id`');
-    const id = doc.id;
+    const bare = doc.id;
     const localVersion = typeof doc?.version === 'string' ? doc.version : '?';
+    // An explicit `octwin status <packId>` wins, so an author who already knows the qualified
+    // id (from `octwin agents` / `octwin projects`) can skip the lookup.
+    const id = await qualifiedPackId(t, flags._[1] ?? bare);
     console.log(`→ Checking ${id}@${localVersion} on ${targetLabel(t)} @ ${url} …`);
     const res = await fetchOrDie(`${url}/api/self/p/packs/${id}/runtime`, {
         headers: authHeaders(t),
@@ -1370,8 +1408,16 @@ async function cmdStatus(flags) {
         json = text;
     }
     if (!res.ok) {
-        if (res.status === 404)
-            die(`'${id}' is not installed on ${targetLabel(t)} yet — run \`octwin deploy\` first`);
+        // A 404 here means one of four different things, and collapsing them into "not
+        // installed" sent one author chasing a deploy that had already succeeded. The route
+        // says which; relay it and only add the deploy hint to the case it fits.
+        if (res.status === 404) {
+            const why = typeof json === 'object' && json !== null && typeof json.error === 'string' ? json.error : text;
+            const notInstalled = /no active install|not installed/i.test(why);
+            die(notInstalled
+                ? `${why}\n  Run \`octwin deploy\` first.`
+                : `status check failed (HTTP 404) — ${why}`);
+        }
         console.error(`✗ status check failed (HTTP ${res.status})`);
         printAuthHint(res.status, url);
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
@@ -2028,7 +2074,11 @@ async function cmdLogs(flags) {
         const { status, json } = await apiGet(`${base}/conversations?limit=50`, t);
         if (status !== 200)
             die(`could not read conversations (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
-        let convs = (json?.conversations ?? []);
+        // `rows` — the shared `makePage` envelope every other list command here reads. This one
+        // read `json.conversations`, a noun the route stopped emitting on 2026-08-09, so `convs`
+        // was ALWAYS empty and the command reported "No conversations yet" seconds after a chat
+        // that had plainly worked. Two pack authors filed it as a replica-lag bug; nothing lagged.
+        let convs = (json?.rows ?? []);
         if (asHandle)
             convs = convs.filter((c) => c.contact?.channel_contact_handle === asHandle);
         if (convs.length === 0) {
@@ -2426,29 +2476,32 @@ async function cmdChat(flags) {
     }
     console.log(`\n(same --as '${from}' continues this conversation — timeline: octwin logs --as ${from})`);
 }
-/** `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]`
+/** `octwin media generate "<prompt>" [--out <file.png>] [--json]`
  *  — AI-generate an image on the platform (needs a `media:generate`-scoped token),
  *  store it as a public asset, and return its `MEDIA-` handle + serve URL. `--out`
  *  downloads the bytes to a file (WhatsApp renders only `.png`/`.jpg`); the paired
- *  `octwin chat --media <file|id>` feeds it into a running media-collect flow. */
+ *  `octwin chat --media <file|id>` feeds it into a running media-collect flow.
+ *
+ *  A `--size` flag was accepted until 2026-08-10. The platform never forwarded it
+ *  to the provider, and stored resolution is decided at ingest regardless, so it
+ *  only ever changed the (fabricated) width/height the command printed back. */
 async function cmdMedia(flags) {
     const sub = flags._[0];
     if (sub !== 'generate')
-        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]');
+        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--json]');
     const t = resolveTarget(flags);
     const { url } = t;
     const prompt = flags._[1];
     if (!prompt)
-        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]');
+        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--json]');
     const asJson = flags.json === true;
-    const size = typeof flags.size === 'string' ? flags.size : undefined;
     const out = typeof flags.out === 'string' ? flags.out : undefined;
     if (!asJson)
         console.log(`→ Generating an image on ${targetLabel(t)} @ ${url} …`);
     const res = await fetchOrDie(`${url}/api/self/p/media/generate`, {
         method: 'POST',
         headers: { 'content-type': 'application/json', ...authHeaders(t) },
-        body: JSON.stringify({ prompt, ...(size ? { size } : {}) }),
+        body: JSON.stringify({ prompt }),
     }, 'media generate');
     const text = await res.text();
     if (!res.ok) {
@@ -2477,10 +2530,10 @@ async function cmdMedia(flags) {
         }
     }
     if (asJson) {
-        console.log(JSON.stringify({ media_id: r.media_id, url: absUrl, mime: r.mime, width: r.width, height: r.height, bytes: r.bytes }));
+        console.log(JSON.stringify({ media_id: r.media_id, url: absUrl, mime: r.mime, bytes: r.bytes }));
         return;
     }
-    console.log(`✓ Generated ${r.media_ref} (${r.width}×${r.height}, ${r.mime}, ${r.bytes} bytes)`);
+    console.log(`✓ Generated ${r.media_ref} (${r.mime}, ${r.bytes} bytes)`);
     console.log(`  id:  ${r.media_id}`);
     console.log(`  url: ${absUrl}`);
     if (out)
@@ -3514,7 +3567,7 @@ async function cmdSchedulingWrite(flags) {
             console.log(JSON.stringify(json, null, 2));
             return;
         }
-        if (json?.has_scheduling === false) {
+        if (json?.has_data === false) {
             console.log('This pack declares no scheduling.');
             return;
         }
@@ -3589,7 +3642,7 @@ async function cmdSchedulingWrite(flags) {
     const { status, json } = await apiSend('POST', `${base}/availability/${path}`, body, t);
     if (status !== 201 && status !== 200)
         writeFail(`add the ${noun}`, status, json, url);
-    if (json?.has_scheduling === false)
+    if (json?.has_data === false)
         die('this pack declares no scheduling');
     const created = json?.rule ?? json?.exception ?? {};
     console.log(`✓ ${noun[0].toUpperCase()}${noun.slice(1)} added — ${created.id ?? '(no id returned)'}`);
@@ -3610,30 +3663,42 @@ async function cmdScheduling(flags) {
     if (flags.slots === true)
         die('usage: octwin scheduling --slots <resourceRecordId>   (the record id of a bookable resource)');
     if (resourceId) {
-        const q = new URLSearchParams({ include_booked: '1' }); // full occupancy, as the operator preview does
-        if (typeof flags.from === 'string')
-            q.set('from', flags.from);
-        if (typeof flags.days === 'string')
-            q.set('days', flags.days); // server-clamped to 1–31
+        // The range is `from`/`to`; `--days` is kept as the ergonomic flag and converted
+        // here, since a CLI user thinks in "the next 7 days".
+        const from = typeof flags.from === 'string' ? flags.from : new Date().toISOString().slice(0, 10);
+        const days = typeof flags.days === 'string' ? Math.max(Number(flags.days) || 1, 1) : 7;
+        const to = new Date(Date.parse(`${from}T00:00:00Z`) + (days - 1) * 86_400_000).toISOString().slice(0, 10);
+        const q = new URLSearchParams({ include_booked: '1', from, to }); // full occupancy, as the operator preview does
+        q.append('resource_id', resourceId);
         if (!asJson)
             console.log(`→ Computing slots for resource ${resourceId} in ${targetLabel(t)} …`);
-        const { status, json } = await apiGet(`${base}/resources/${encodeURIComponent(resourceId)}/slots?${q.toString()}`, t);
-        if (status === 404)
-            die(`resource '${resourceId}' not found (pass an XRM record id — \`octwin records <entity>\` lists them)`);
+        const { status, json } = await apiGet(`${base}/slots?${q.toString()}`, t);
         if (status === 400)
-            die(`that record isn't a bookable resource${errDetail(json)}`);
+            die(`could not compute slots${errDetail(json)}`);
         if (status !== 200)
             die(`could not compute slots (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
         if (asJson) {
             console.log(JSON.stringify(json, null, 2));
             return;
         }
-        if (json?.has_scheduling === false) {
+        if (json?.has_data === false) {
             console.log('This pack declares no `scheduling.yaml` — nothing to schedule.');
             return;
         }
-        const slots = (json?.slots ?? []);
-        console.log(`Slots for ${resourceId} (timezone ${json?.timezone ?? '?'}): ${slots.length}`);
+        // A resource the server could not use comes back named, with a reason, rather
+        // than as an HTTP status — one call may carry several resources.
+        const bad = (json?.unresolved ?? []).find((u) => u.resource_id === resourceId);
+        if (bad?.reason === 'not_found') {
+            die(`resource '${resourceId}' not found (pass an XRM record id — \`octwin records <entity>\` lists them)`);
+        }
+        if (bad?.reason === 'not_bookable')
+            die(`that record isn't a bookable resource`);
+        const res = (json?.resources ?? [])[0];
+        const slots = (res?.slots ?? []);
+        console.log(`Slots for ${resourceId} (timezone ${res?.timezone ?? '?'} — from ${res?.timezone_source ?? '?'}): ${slots.length}`);
+        if (res?.timezone_source === 'pack_default' && json?.pack_timezone_declared === false) {
+            console.log('  ⚠ The pack declares no `timezone:`, so these are UTC — a clock nobody chose.');
+        }
         if (slots.length === 0)
             console.log('  (none — no availability rules cover this window; `octwin deploy --seed` seeds the demo rules)');
         for (const s of slots) {
@@ -3650,7 +3715,7 @@ async function cmdScheduling(flags) {
         console.log(JSON.stringify(json, null, 2));
         return;
     }
-    if (json?.has_scheduling === false) {
+    if (json?.has_data === false) {
         console.log('This pack declares no `scheduling.yaml` — nothing to schedule.');
         return;
     }
@@ -3662,260 +3727,267 @@ async function cmdScheduling(flags) {
     console.log('\nSlots for one resource:  octwin scheduling --slots <resourceRecordId>   (ids: octwin records <entity>)');
 }
 function help() {
-    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
-
-  octwin --version                                      # print the CLI version (+ any upgrade notice)
-  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
-  octwin validate [--dir .] [--remote] [--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]
-  octwin status  [--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>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
-  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
-  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
-  octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
-  octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
-  octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
-  octwin platform-kb [pull] [--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
-
-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]
-
-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]
+  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 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
+
+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]
+
+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]
-  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.`,
-    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
+    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
   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]
-  Upload the pack bundle, validate server-side, install onto the project.
+    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+  Upload the pack bundle, validate server-side, install onto the project.
   --seed additionally applies the pack's demo seed (streams progress).`,
-    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 [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
-  Show installed vs live version + the flow list for this pack.`,
-    records: `octwin records [entity] [id] [--limit 50] [--offset n]
-  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
+    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
   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] [--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>] [--size 1024x1024] [--json]
-  AI-generate an image (needs a media:generate-scoped token), store it as a
-  public asset, and print its MEDIA- handle + serve URL. --out downloads the
-  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
-  width, height, bytes }. Pair with 'octwin chat --media' to drive media flows.`,
-    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
+    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
   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.`,
-    '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.
-  A token is used when you have one (it also works against older platforms).
-
-  --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 / refused). For scripts and
+    '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.
+  A token is used when you have one (it also works against older platforms).
+
+  --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 / refused). 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.`,
-    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/net-hint.js

@@ -0,0 +1,57 @@
+/**
+ * Turn "the platform is unreachable" into a hint the author can act on.
+ *
+ * ## Why this exists
+ *
+ * `fetch('http://localhost:3000')` can be refused while the platform is running
+ * and answering. The server binds IPv4-only (`host: '0.0.0.0'` in `src/server.ts`),
+ * Node resolves `localhost` to `::1` first, and whether the connection then falls
+ * back to `127.0.0.1` is decided by Node's `autoSelectFamily`, NOT by our code.
+ *
+ * Measured on node v24.12.0, fetching an IPv4-only bind over `localhost`:
+ *
+ *   autoSelectFamily=true  (the default here) -> 200
+ *   autoSelectFamily=false                    -> fetch failed / ECONNREFUSED
+ *
+ * So on a runtime where that default is off — or with
+ * `--no-network-family-autoselection` / that flag in `NODE_OPTIONS` — every command
+ * reports the platform as down while `--url http://127.0.0.1:3000` and `curl` both
+ * work. That reading is what costs the time: a pack author's first act is to run the
+ * platform locally, and "unreachable" sends them to look at the server.
+ *
+ * This module only explains; it changes no addresses. Rewriting the host inside
+ * `readTarget` would also change the key saved credentials are stored under, and
+ * moving the server to `host: '::'` can fail to bind where IPv6 is disabled — so
+ * neither belongs in a diagnostic path.
+ */
+/** A `localhost` HTTP(S) origin — the only case where the IPv4/IPv6 split applies. */
+function isLocalhostUrl(url) {
+    try {
+        return new URL(url).hostname.toLowerCase() === 'localhost';
+    }
+    catch {
+        return false; // not a URL we can reason about; no hint to give
+    }
+}
+/** Did the connection get refused, as opposed to timing out / DNS / TLS? */
+function isConnectionRefused(err) {
+    const seen = new Set();
+    for (let e = err; e && !seen.has(e); e = e.cause) {
+        seen.add(e);
+        if (e.code === 'ECONNREFUSED' || e.code === 'ECONNRESET')
+            return true;
+    }
+    return false;
+}
+/**
+ * The extra sentence to append when a failure looks like the IPv6-`localhost`
+ * trap, or `null` when it does not — a hint printed on unrelated failures (a
+ * genuinely stopped server, a wrong port) is worse than none, because it sends
+ * the author to fix an address that was never the problem.
+ */
+export function localhostFamilyHint(url, err) {
+    if (!isLocalhostUrl(url) || !isConnectionRefused(err))
+        return null;
+    const ipv4 = url.replace(/(^https?:\/\/)localhost\b/i, '$1127.0.0.1');
+    return `if the platform IS running, this is the IPv6 'localhost' trap — Node tried ::1 and the server binds IPv4 only. Retry with --url ${ipv4}`;
+}

package/dist/lib/render-check.js

@@ -30,9 +30,10 @@ import { lookupKbSubdir, isEntryFile } from './kb-path.js';
  * "checked, nothing wrong" from "could not check". See `kb-path.ts`.
  */
 export function loadAllowedRenderKeys(packDir) {
+    const nested = new Map();
     const lookup = lookupKbSubdir(packDir, 'render-intents', dir => readdirSync(dir).some(isEntryFile));
     if (lookup.state !== 'ok')
-        return { lookup, keys: null };
+        return { lookup, keys: null, nested };
     const dir = lookup.dir;
     const out = new Map();
     try {
@@ -42,16 +43,20 @@ export function loadAllowedRenderKeys(packDir) {
             const entry = JSON.parse(readFileSync(join(dir, file), 'utf8'));
             if (entry.render_intent && Array.isArray(entry.allowed_keys)) {
                 out.set(entry.render_intent, entry.allowed_keys);
+                // Optional: a KB pulled before 2026-08-09 has no nested sets, and the nested check simply
+                // does not run for that intent. Absent is skipped, never treated as "nothing is allowed".
+                if (entry.nested_allowed_keys)
+                    nested.set(entry.render_intent, entry.nested_allowed_keys);
             }
         }
     }
     catch (err) {
-        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, keys: null };
+        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, keys: null, nested };
     }
     if (out.size === 0) {
-        return { lookup: { state: 'malformed', dir, reason: 'no render-intent entries parsed' }, keys: null };
+        return { lookup: { state: 'malformed', dir, reason: 'no render-intent entries parsed' }, keys: null, nested };
     }
-    return { lookup, keys: out };
+    return { lookup, keys: out, nested };
 }
 /**
  * Walk parsed YAML for objects carrying `render_intent` and report keys outside
@@ -59,8 +64,32 @@ export function loadAllowedRenderKeys(packDir) {
  * nodes: intents nest (an `auto_collection` carries `empty`/`single`/`multi`
  * sub-intents), and a stray key is just as invisible there.
  */
-export function findRenderKeyViolations(doc, file, allowedByIntent) {
+export function findRenderKeyViolations(doc, file, allowedByIntent, nestedByIntent = new Map()) {
     const findings = [];
+    /**
+     * Descend a declared nested path, mirroring the platform's `checkNested`.
+     *
+     * Descends only where the KB DECLARES a shape, and skips non-objects — so an expression string
+     * (`item_template: '$tpl'`) and an undeclared bag (`items:`, pack-supplied records) are both left
+     * alone, exactly as at load time.
+     */
+    const walkNested = (value, intent, at, sets, path) => {
+        if (Array.isArray(value)) {
+            value.forEach((v, i) => walkNested(v, intent, `${at}[]`, sets, [...path, i]));
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const obj = value;
+        const allowed = sets[at];
+        if (allowed) {
+            const bad = Object.keys(obj).filter(k => !allowed.includes(k));
+            if (bad.length)
+                findings.push({ file, path: [...path], intent, keys: bad, allowed, nestedAt: at });
+        }
+        for (const [k, v] of Object.entries(obj))
+            walkNested(v, intent, `${at}.${k}`, sets, [...path, k]);
+    };
     const walk = (node, path) => {
         if (Array.isArray(node)) {
             node.forEach((v, i) => walk(v, [...path, i]));
@@ -78,6 +107,14 @@ export function findRenderKeyViolations(doc, file, allowedByIntent) {
                 const bad = Object.keys(obj).filter(k => !allowed.includes(k));
                 if (bad.length)
                     findings.push({ file, path: [...path], intent: obj.render_intent, keys: bad, allowed });
+                const sets = nestedByIntent.get(obj.render_intent);
+                if (sets) {
+                    for (const [k, v] of Object.entries(obj)) {
+                        if (k === 'render_intent' || !allowed.includes(k))
+                            continue;
+                        walkNested(v, obj.render_intent, k, sets, [...path, k]);
+                    }
+                }
             }
         }
         for (const [k, v] of Object.entries(obj))
@@ -93,6 +130,7 @@ export function describeRenderFinding(f) {
         return `${f.file}${at}: unknown render_intent '${f.intent}' — known intents: ${f.allowed.join(', ')}`;
     }
     const plural = f.keys.length === 1 ? 'field' : 'fields';
-    return `${f.file}${at}: render_intent '${f.intent}' has unknown ${plural} ${f.keys.map(k => `'${k}'`).join(', ')} ` +
+    const where = f.nestedAt ? `'${f.intent}' at '${f.nestedAt}'` : `'${f.intent}'`;
+    return `${f.file}${at}: render_intent ${where} has unknown ${plural} ${f.keys.map(k => `'${k}'`).join(', ')} ` +
         `— silently dropped at render. Allowed: ${f.allowed.join(', ')}`;
 }

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "octwin-cli",
-  "version": "0.6.0",
-  "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
-  "type": "module",
-  "bin": {
-    "octwin": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "templates",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "yaml": "^2.6.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack", "conversational-ai", "yaml"],
-  "author": "CEQUENS",
-  "homepage": "https://www.npmjs.com/package/octwin-cli",
-  "license": "MIT"
-}
+{
+  "name": "octwin-cli",
+  "version": "0.6.1",
+  "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
+  "type": "module",
+  "bin": {
+    "octwin": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack", "conversational-ai", "yaml"],
+  "author": "CEQUENS",
+  "homepage": "https://www.npmjs.com/package/octwin-cli",
+  "license": "MIT"
+}

package/templates/starter/manifest.yaml

@@ -14,6 +14,16 @@ description: 'A hello bot — edit this to build your pack.'
 supported_channels: [whatsapp, web]
 required_adapters:  [messaging]
 
+# What to do with a VOICE NOTE. WhatsApp cannot stop customers sending them, and an
+# ABSENT block is not "nothing happens" — it means `passthrough`, i.e. no
+# speech-to-text, so the agent gets "a voice message arrived, no transcript" and has
+# to improvise. `transcribe` is the right default for a conversational pack; use
+# `passthrough` when you handle the audio ref yourself, or `decline` (with a
+# `notice:`) to ask for text instead.
+inbound_preprocessing:
+  voicenote:
+    mode: transcribe
+
 # Default locale for platform-emitted copy + this pack's `$t()` lookups.
 default_settings:
   locale: ar