octwin-cli 0.6.0 → 0.7.0

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
@@ -618,6 +620,54 @@ async function notifyIfKbStale(flags) {
     }
     catch { /* a KB check must never break the CLI */ }
 }
+/**
+ * Nudge (to stderr) when the platform has memos this workspace has not read — a reply to
+ * a `octwin feedback` report, or a notice we published (new capability, deprecation,
+ * breaking change).
+ *
+ * The sibling of `notifyIfKbStale`, and the same three decisions apply for the same
+ * reasons: it rides commands that ALREADY hit the platform so it costs one tiny GET on
+ * top of networked work; it never throws, because observing must not break a command;
+ * and it is **deliberately not TTY-gated**, because the primary reader of this CLI is an
+ * authoring agent whose output is piped — the one reader that cannot notice an unread
+ * reply on its own would otherwise be the only one never told.
+ *
+ * WHY THIS EXISTS AT ALL. `octwin feedback` was one-way. Measured 2026-08-18: four
+ * reports sat unread for nine days, and one author hardcoded English across 16 flows to
+ * work around a bug that had been fixed two days earlier, because nothing could tell
+ * them. A nudge that does not name the command to run does not motivate an agent, so the
+ * line always ends in `octwin memos`.
+ *
+ * Unlike the KB check there is NO local state to compare: read state is per-tenant on the
+ * platform, so an agent on a fresh machine or in a fresh container still learns about an
+ * unread memo. That is the whole reason it is not a local marker file.
+ */
+async function notifyIfMemosWaiting(flags) {
+    try {
+        const t = resolveTargetOrNull(flags);
+        if (!t)
+            return;
+        const { status, json } = await apiGet(`${t.url}/api/self/p/memos?meta=1`, t);
+        // Silent on ANY failure — an older platform has no such route, and a nudge is never
+        // worth a diagnostic of its own. Unlike the KB poll there is no scope to explain: the
+        // route is gated on tenant access precisely so every token can answer it.
+        if (status !== 200 || !json || typeof json !== 'object')
+            return;
+        const unread = Number(json.unread ?? 0);
+        if (!Number.isFinite(unread) || unread <= 0)
+            return;
+        const actionable = Number(json.unread_actionable ?? 0);
+        const what = unread === 1 ? '1 memo' : `${unread} memos`;
+        const tail = actionable > 0 ? ` (${actionable} needing action)` : '';
+        console.error(`\n✉ ${what} from the platform${tail} — read them: octwin memos`);
+        if (actionable > 0) {
+            // Said separately, because the whole point of the severity axis is that an agent
+            // mid-build should stop and read rather than finish first.
+            console.error('  One or more may change what you are building — read before continuing.');
+        }
+    }
+    catch { /* a memo check must never break the CLI */ }
+}
 /** Which commands already made a platform call, so the trailing KB-drift poll
  *  rides on existing network work (never on offline `validate` / `init`;
  *  `platform-kb` refreshes the reference itself, so it needs no nudge). */
@@ -630,6 +680,9 @@ function commandTouchesPlatform(command, flags) {
         case 'chat':
         case 'media':
         case 'pull':
+        // `memos` is networked but needs NO memo nudge — it just read them. It still gets the
+        // KB drift check, which is a different question.
+        case 'memos': return true;
         case 'records':
         case 'work':
         case 'logs':
@@ -748,7 +801,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 +949,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 +1316,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 +1404,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 +1441,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 +1459,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));
@@ -2012,6 +2109,60 @@ async function cmdFeedback(flags) {
         console.log('  ⓘ no local capability reference found, so the report carries no KB version.');
         console.log('    Pull it before your next session: octwin platform-kb');
     }
+    console.log('  A reply arrives as a memo — this CLI will tell you when one is waiting.');
+}
+/**
+ * `octwin memos [--json] [--all]` — read what the platform has told you.
+ *
+ * The other half of `octwin feedback`. Two kinds arrive here: a REPLY to a report you
+ * sent, and a NOTICE we published to every author (a new capability, a deprecation, a
+ * breaking change). Both are markdown, printed in full — this is a channel for reading,
+ * not a list to page through, so there is no `show <id>`.
+ *
+ * Reading ACKS: the default prints unread memos and marks them read, so the nudge stops.
+ * `--all` re-reads history and acks nothing, which is also the escape hatch if a piped
+ * `--json` consumer crashed halfway through.
+ */
+async function cmdMemos(flags) {
+    const t = resolveTarget(flags);
+    const all = flags.all === true;
+    const { status, json } = await apiGet(`${t.url}/api/self/p/memos${all ? '?all=1' : ''}`, t);
+    if (status !== 200) {
+        die(`could not read memos (HTTP ${status})${errDetail(json)}${authFailureDetail(status, t.url)}`);
+    }
+    const rows = (json?.rows ?? []);
+    if (flags.json === true) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log(all ? 'No memos yet.' : 'No unread memos.  (History: octwin memos --all)');
+        return;
+    }
+    const mark = (s) => s === 'breaking' ? '⛔ BREAKING' : s === 'action_required' ? '⚠ ACTION' : 'ⓘ';
+    for (const m of rows) {
+        const when = String(m.published_at ?? '').slice(0, 10);
+        const about = m.pack_id ? ` · ${m.pack_id}` : '';
+        const seen = m.read_at ? ' · (already read)' : '';
+        console.log(`\n${'─'.repeat(72)}`);
+        console.log(`${mark(m.severity)}  ${m.title}`);
+        console.log(`${m.kind === 'reply' ? 'reply to your report' : 'platform notice'} · ${when}${about}${seen}`);
+        console.log(`${'─'.repeat(72)}\n`);
+        console.log(m.body_md.trimEnd());
+    }
+    console.log();
+    // Ack only what we just showed as unread, and only on the default path — `--all`
+    // deliberately leaves read state alone so history can be re-read any number of times.
+    if (!all) {
+        const ids = rows.filter(m => !m.read_at).map(m => m.id);
+        if (ids.length > 0) {
+            const res = await apiSend('POST', `${t.url}/api/self/p/memos/read`, { ids }, t);
+            // A failed ack is not a failed command — the author HAS read them. Say so rather
+            // than dying after printing everything, and the nudge simply fires again.
+            if (res.status !== 200)
+                console.error(`ⓘ could not mark them read (HTTP ${res.status}) — they will be offered again.`);
+        }
+    }
 }
 /** `octwin logs [conversationId] [--as <handle>] [--json]` — list conversations
  *  or show one's event timeline (full text + the renders each turn produced). */
@@ -2028,7 +2179,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 +2581,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 +2635,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 +3672,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 +3747,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 +3768,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 +3820,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 +3832,275 @@ 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
+  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]
+
+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
+    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
   "you were reading a stale reference". Needs the \`pack:deploy\` scope.`,
 };
 async function main() {
@@ -3998,6 +4183,9 @@ async function main() {
         case 'feedback':
             await cmdFeedback(flags);
             break;
+        case 'memos':
+            await cmdMemos(flags);
+            break;
         case 'test':
             await cmdValidate({ ...flags, remote: true });
             break; // A6: `test` = the full remote validate, not a validate-clone
@@ -4019,6 +4207,8 @@ async function main() {
     // offline paths); CLI-upgrade always.
     if (commandTouchesPlatform(command, flags))
         await notifyIfKbStale(flags);
+    if (commandTouchesPlatform(command, flags))
+        await notifyIfMemosWaiting(flags);
     await notifyIfOutdated();
 }
 main().catch((err) => die(err?.message ?? String(err)));