octwin-cli 0.8.11 → 0.8.13

package/dist/index.js

@@ -9,7 +9,7 @@
  *
  *   octwin --version | -v           # print the CLI version (+ any upgrade notice)
  *   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
- *   octwin validate [--dir .] [--remote] [--require-kb]   # --remote → the platform's FULL schema check + lint, all errors at once
+ *   octwin validate [--dir .] [--remote | --offline] [--require-kb]   # the platform's FULL check by default (no login needed); --offline = the partial subset
  *   octwin login   --url <platformUrl> [--token oct_…]   # no token → approve in a browser
  *   octwin whoami  [--url <url>] [--tenant <slug>]
  *   octwin projects [--archived]    # the --project slugs this token can name
@@ -66,10 +66,10 @@ import { parse as parseYaml } from 'yaml';
 import { applyRenames } from './lib/rename.js';
 import { validatePackBundle, describePackNameProblem, asPackName } from './lib/validate.js';
 import { loadAllowedRenderKeys, findRenderKeyViolations, describeRenderFinding } from './lib/render-check.js';
-import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding } from './lib/args-check.js';
+import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding, findArgWarnings, describeArgWarning, } from './lib/args-check.js';
 import { yamlLineOf } from './lib/yaml-pos.js';
 import { localhostFamilyHint } from './lib/net-hint.js';
-import { authHeaders as buildAuthHeaders } from './lib/client-headers.js';
+import { authHeaders as buildAuthHeaders, clientReportHeaders } from './lib/client-headers.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';
@@ -78,6 +78,7 @@ import { findPlatformKbDir } from './lib/kb-path.js';
 import { reportChecks } from './lib/outcome.js';
 import { classifyPackPath, isSkippedDir } from './lib/pack-source.js';
 import { readPage, morePageHint } from './lib/page.js';
+import { chatLabel, answersTheTurn } from './lib/chat-line.js';
 import { kbOneLiner, buildKbIndexMarkdown, buildKbOutlineMarkdown, } from './lib/kb-index.js';
 import { buildSymbols, linkExplainers, renderSymbolsMarkdown } from './lib/kb-symbols.js';
 import { readPending, writePending, clearPending, isPendingExpired, secondsLeft, interpretPoll, clientLabel, EXIT_STILL_PENDING, } from './lib/device-login.js';
@@ -199,6 +200,8 @@ const VERB_REQUIREMENTS = {
     'records patch': { scope: 'records:write', feature: 'records' },
     'records stage': { scope: 'records:write', feature: 'records' },
     'records note': { scope: 'records:write', feature: 'records' },
+    'records archive': { scope: 'records:write', feature: 'records' },
+    'records restore': { scope: 'records:write', feature: 'records' },
     'records tasks': { scope: 'records:read', feature: 'tasks' },
     'records task': { scope: 'records:write', feature: 'tasks' },
     'work assign': { scope: 'work:write', feature: 'work' },
@@ -872,7 +875,8 @@ function exitNow(code) {
  *  `platform-kb` refreshes the reference itself, so it needs no nudge). */
 function commandTouchesPlatform(command, flags) {
     switch (command) {
-        case 'validate': return flags.remote === true; // offline validate stays offline
+        // `validate` runs the FULL check against the platform by default now; only `--offline` stays offline.
+        case 'validate': return flags.offline !== true;
         case 'deploy':
         case 'status':
         case 'test':
@@ -1049,13 +1053,33 @@ async function cmdValidate(flags) {
                 if (!args.specs)
                     return { kind: 'not-run', lookup: args.lookup };
                 const findings = withLines(yamlDocs().flatMap(([p, doc]) => findArgViolations(doc, p, args.specs)));
-                return findings.length
-                    ? {
+                if (findings.length) {
+                    return {
                         kind: 'findings', noun: 'primitive-argument error',
                         lines: findings.map(describeArgFinding),
                         hint: 'fix these before deploying — an undeclared argument is dropped with no error at runtime',
-                    }
-                    : { kind: 'passed', line: 'primitive arguments match their declared inputs' };
+                    };
+                }
+                /**
+                 * Errors first, and only then the warnings — a `findings` outcome exits, so a warning
+                 * printed above it would never be read, and one printed below it would never be reached.
+                 *
+                 * `warnsTogether` is the platform's own declaration (`record_save` with `record_id:` +
+                 * `stage:` refuses the whole write on an existing record). It has been enforced server-side
+                 * since 2026-09-06 and was reachable only through `--remote`; the author who lost a write
+                 * to it was on CLI 0.6.0, offline. Measured before shipping: **0 findings across all 48
+                 * `record_save` call sites in the 23 marketplace packs** — the check is silent on a clean
+                 * corpus, which is the bar a warning has to clear before it is worth printing at all.
+                 */
+                const warnings = withLines(yamlDocs().flatMap(([p, doc]) => findArgWarnings(doc, p, args.specs)));
+                if (warnings.length) {
+                    return {
+                        kind: 'warnings', noun: 'argument-combination warning',
+                        lines: warnings.map(describeArgWarning),
+                        hint: 'legal YAML, and usually not what you meant — read each one and decide.',
+                    };
+                }
+                return { kind: 'passed', line: 'primitive arguments match their declared inputs' };
             },
         },
         {
@@ -1172,36 +1196,62 @@ async function cmdValidate(flags) {
     if (skipped.length && flags['require-kb'] === true) {
         die(`--require-kb: ${skipped.length} check${skipped.length === 1 ? '' : 's'} could not run (${skipped.join(', ')})`);
     }
-    if (flags.remote !== true) {
-        // The LAST line carries the skip. A reader who sees a ✓ and stops there is the
-        // failure mode; a caveat printed ABOVE the ✓ does not fix it.
-        if (skipped.length) {
-            console.log(`\n⚠ ${id}@${version} passed the checks that RAN — ${skipped.length} skipped: ${skipped.join(', ')}.`);
-            console.log('  Run `octwin platform-kb pull` (once, at your repo root — it covers every pack under it),');
-            console.log('  or `octwin validate --remote` to have the platform run everything server-side.');
-        }
-        else {
-            console.log('  Run `octwin validate --remote` to run the platform\'s FULL manifest + flow-DSL validation');
-            console.log('  (all errors at once) before you deploy.');
-        }
-        return;
-    }
-    // Remote: the SAME validation the deploy route runs — manifest `.strict()` +
-    // every flow (schema/expression/structure) — returning ALL errors at once.
-    const t = resolveTarget(flags);
-    const { url } = t;
-    console.log(`→ Validating against ${targetLabel(t)} @ ${url} …`);
+    /**
+     * ── The FULL check is the DEFAULT — the one deploy runs ─────────────────────────
+     *
+     * The checks above are a SUBSET: they replay what the KB publishes, file by file. On
+     * 2026-09-25 they passed a pack the platform refused — a starter flow left behind with
+     * Arabic copy only, in a pack that ships English — and "the offline check passed" had read
+     * as "deploy will pass". So `validate` now asks the platform unless told not to, and says
+     * PARTIAL, on its last line, whenever it could not.
+     *
+     * Two doors, one check (`routes/packs/_validate-bundle.ts` on the platform):
+     *   • a token AND a named project (`--project` / `PACK_PROJECT`) → the logged-in door,
+     *     which also confirms the project exists — the right pre-flight right before a deploy;
+     *   • anything else → `POST /api/public/packs/validate`, which needs no login and no
+     *     project. An unpinned token with no project would get a 400 on the other door, and a
+     *     default must not fail for a config gap the check itself does not care about.
+     *
+     * `--remote` REQUIRES the full check (a failure to reach it is an error); `--offline` skips it.
+     */
+    if (flags.offline === true)
+        return printPartialTrailer(id, version, skipped, 'you passed --offline');
+    const t = readTarget(flags);
+    if (!t.url) {
+        if (flags.remote === true)
+            die('--remote needs a platform url — pass --url, set PACK_PLATFORM_URL, or `octwin login --url <url>`');
+        return printPartialTrailer(id, version, skipped, 'no platform url is set — pass --url, set PACK_PLATFORM_URL, or `octwin login --url <url>`');
+    }
+    const loggedInDoor = !!t.token && !!t.project;
+    const endpoint = loggedInDoor ? `${t.url}/api/self/p/packs/validate` : `${t.url}/api/public/packs/validate`;
+    const headers = loggedInDoor
+        ? authHeaders(t)
+        // The public door takes no credential — but it still gets this run's client report, so a
+        // stale reference is flagged exactly as it is for a logged-in author.
+        : clientReportHeaders({ cliVersion: VERSION, kbContentHash: LOCAL_KB?.content_hash ?? null });
+    console.log(`→ Running the platform's full check${loggedInDoor ? ` against ${targetLabel(t)}` : ' (no login needed)'} @ ${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,
-            ...(flags['strict-primitives'] === true ? { strict_primitives: true } : {}),
-        }),
-    }, 'remote validate');
+    let res;
+    try {
+        res = await fetch(endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...headers },
+            body: JSON.stringify({
+                files, blobs,
+                ...(flags['strict-primitives'] === true ? { strict_primitives: true } : {}),
+            }),
+        });
+    }
+    catch (err) {
+        const why = `platform unreachable at ${t.url} (${err?.message ?? err})`;
+        if (flags.remote === true) {
+            const hint = localhostFamilyHint(t.url, err);
+            die(`full check — ${why}${hint ? `\n  ${hint}` : ''}`);
+        }
+        return printPartialTrailer(id, version, skipped, why);
+    }
     const text = await res.text();
     let json;
     try {
@@ -1210,6 +1260,14 @@ async function cmdValidate(flags) {
     catch {
         json = text;
     }
+    // A platform older than the public door answers Fastify's default 404 — degrade to the
+    // subset (loudly), or fail when the full check was REQUIRED.
+    if (!loggedInDoor && res.status === 404 && (typeof json !== 'object' || json === null || json.error === 'Not Found')) {
+        const why = `the platform at ${t.url} has no public validate yet — log in and pass --project for the full check`;
+        if (flags.remote === true)
+            die(why);
+        return printPartialTrailer(id, version, skipped, why);
+    }
     if (!res.ok) {
         // A 404 here is AMBIGUOUS and must not be collapsed. The route resolves the
         // tenant and the project BEFORE it validates anything, so a 404 is usually an
@@ -1230,8 +1288,13 @@ async function cmdValidate(flags) {
                 die('this platform has no /packs/validate endpoint yet (older version) — deploy runs the full check');
             die(`remote validate${errDetail(json)} — check --tenant/--project (or PACK_TENANT/PACK_PROJECT); \`octwin projects\` lists what this token can reach`);
         }
-        console.error(`✗ remote validate failed (HTTP ${res.status})`);
-        printAuthHint(res.status, url);
+        // The public door is rate-limited per caller. Hitting it is not a verdict on the pack.
+        if (res.status === 429 && flags.remote !== true) {
+            return printPartialTrailer(id, version, skipped, `the platform's no-login check is rate-limited right now — retry shortly, or log in and pass --project`);
+        }
+        console.error(`✗ full check failed (HTTP ${res.status})`);
+        if (loggedInDoor)
+            printAuthHint(res.status, t.url);
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
         exitNow(1);
     }
@@ -1260,6 +1323,19 @@ async function cmdValidate(flags) {
     }
     exitNow(1);
 }
+/**
+ * The LAST lines when only the offline SUBSET ran. A reader who sees a ✓ and stops there is the
+ * failure mode, and a caveat printed ABOVE the ✓ does not fix it — so the word is PARTIAL, it is
+ * last, and it says why. Exit 0, as offline `validate` always has: the subset found nothing, and
+ * a config gap is not a finding (`--remote` is for when the full check must not be skipped).
+ */
+function printPartialTrailer(id, version, skipped, why) {
+    console.log(`\n⚠ ${id}@${version}: only the OFFLINE check ran — a PARTIAL check. Deploy runs more, and can still refuse this pack.`);
+    console.log(`  Why: ${why}.`);
+    if (skipped.length) {
+        console.log(`  Also skipped offline (${skipped.length}): ${skipped.join(', ')} — \`octwin platform-kb pull\` once at your repo root restores them.`);
+    }
+}
 /**
  * Two ways in, one saved result.
  *
@@ -1822,7 +1898,7 @@ async function cmdSeed(flags) {
         if (stepErrors.length) {
             // A kind failed but the rest ran — the reconcile softens each step. Say which,
             // and exit non-zero so a scripted `seed && chat` doesn't read as clean.
-            console.error(`
+            console.error(`
 ⚠ ${stepErrors.length} step${stepErrors.length === 1 ? '' : 's'} failed — data may be incomplete:`);
             for (const e of stepErrors)
                 console.error(`   • ${e}`);
@@ -2281,6 +2357,24 @@ async function apiGet(endpoint, t) {
     }
     return { status: res.status, json };
 }
+/**
+ * The project this token is pinned to, or null (unpinned, or the lookup failed). A pinned token
+ * cannot reach workspace-wide routes, so a command with a workspace view and a project view uses
+ * this to pick the one the token can actually read. `authHeaders`, never a hand-built header — an
+ * authenticating call without it stamps NULL over the token's client report.
+ */
+async function pinnedProjectOf(t) {
+    try {
+        const res = await fetch(`${t.url}/api/self/t/whoami`, { headers: authHeaders(t) });
+        if (!res.ok)
+            return null;
+        const j = await res.json();
+        return typeof j.project_slug === 'string' && j.project_slug ? j.project_slug : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Send a WRITE to an admin endpoint with the deploy token; returns `{ status, json }`.
  *
@@ -2399,7 +2493,7 @@ function pagingQs(flags, defaultLimit = 50) {
  * guessed) so the ambiguity is documented rather than emergent — a pack that
  * declares an entity actually called `note` reaches it via `--entity note`.
  */
-const RECORD_VERBS = new Set(['create', 'patch', 'stage', 'note', 'tasks', 'task']);
+const RECORD_VERBS = new Set(['create', 'patch', 'stage', 'note', 'tasks', 'task', 'archive', 'restore']);
 /** `octwin records [entity] [id]` — inspect the pack's XRM data (needs a `records:read` token). */
 async function cmdRecords(flags) {
     // A leading reserved word is a write. To READ an entity whose name collides
@@ -2536,6 +2630,24 @@ async function cmdRecordsWrite(flags) {
         console.log(`✓ #${json?.record?.record_number ?? '?'} is now at '${json?.record?.stage ?? to}'`);
         return;
     }
+    // There is no delete — on the platform or here. Archive is how a record leaves use (test data
+    // included): it drops out of every list, count and report, fires the entity's `on.archived`
+    // reactions exactly as the console's Archive does, and `restore` brings it back.
+    if (verb === 'archive' || verb === 'restore') {
+        const archived = verb === 'archive';
+        // `||`, not `??`: an EMPTY id (a failed `$(…)` in a script) must not reach the route.
+        const id = arg || die(`usage: octwin records ${verb} <recordId>`);
+        console.log(`→ ${archived ? 'Archiving' : 'Restoring'} ${id} in ${targetLabel(t)} …`);
+        const { status, json } = await apiSend('POST', `${base}/xrm/records/${encodeURIComponent(id)}/archive`, { archived }, t);
+        if (status === 404)
+            die(`record '${id}' not found`);
+        if (status !== 200)
+            writeFail(`${verb} record ${id}`, status, json, url, true);
+        console.log(archived
+            ? `✓ Archived #${json?.record?.record_number ?? '?'} — out of every list and count. Undo: octwin records restore ${id}`
+            : `✓ Restored #${json?.record?.record_number ?? '?'} — back in use.`);
+        return;
+    }
     if (verb === 'note') {
         const id = arg ?? die('usage: octwin records note <recordId> "the note text"');
         const note = flags._[2] ?? die('octwin records note needs the note text as the last argument');
@@ -2776,9 +2888,25 @@ async function cmdLogs(flags) {
     console.log(`Timeline for ${convId} (${events.length} events):`);
     for (const e of events) {
         const isErr = e.type === 'tool' && e.subtype === 'platform_error';
-        const tag = isErr ? '⚠ ERROR' : `${e.type}${e.subtype ? `/${e.subtype}` : ''}`;
+        /**
+         * An ADVISORY is a turn that worked and that you probably did not mean.
+         *
+         * It reads differently from an error on purpose: nothing failed, so `⚠ ERROR` would be a lie
+         * and the plain `tool/platform_advisory` tag would be scrolled past. The platform raises these
+         * exactly where a silent-but-wrong result used to be invisible — a `record_list` scoped to a
+         * customer who owns none of a shared entity returns zero rows and the `empty` port, which
+         * prints identically to a real no-match. Three separate authors lost debugging sessions to
+         * that one before it had anywhere to appear.
+         */
+        const isAdvisory = e.type === 'tool' && e.subtype === 'platform_advisory';
+        const tag = isErr ? '⚠ ERROR' : isAdvisory ? '! CHECK' : `${e.type}${e.subtype ? `/${e.subtype}` : ''}`;
         const body = typeof e.content === 'string' ? e.content : JSON.stringify(e.content ?? '');
         console.log(`  ${e.ts ?? ''}  ${tag}: ${body ?? ''}`);
+        // The remedy, indented under its advisory. Printing the observation without the fix is what
+        // the envelope field and the server log already did, and neither reached an author.
+        if (isAdvisory && typeof e.metadata?.remedy === 'string' && e.metadata.remedy) {
+            console.log(`      → ${e.metadata.remedy}`);
+        }
         // The renders this turn actually sent (captured outbound payloads) — the
         // other half of the story next to the structured tap lines.
         const captured = Array.isArray(e.metadata?.raw) ? e.metadata.raw : [];
@@ -2904,6 +3032,7 @@ class SseFrameReader {
 const REPLAY_SETTLE_MS = 400; // quiet gap that marks the end of the connect replay burst
 const TURN_SETTLE_MS = 2_000; // quiet gap after a render = the turn finished sending
 const REPLY_TIMEOUT_MS = 45_000; // hard cap waiting for the first render of the turn
+const LATE_DRAIN_MS = 3_000; // after the last turn: stay connected for late pushes (`drainLateRenders`)
 /**
  * Parse a `--script` file — ONE TURN PER LINE, in order:
  *
@@ -2938,19 +3067,12 @@ function parseChatScript(body) {
     }
     return turns;
 }
-/**
- * Send ONE turn and print everything it rendered. Returns the new frame boundary
- * (so the next turn only accepts frames newer than this turn's output) and how
- * many renders arrived.
- *
- * Splitting this out is what makes `--script` reliable. Driving a multi-step flow
- * by chaining shell invocations (`chat A && chat B`) races the agent loop: this
- * command ends a turn on a QUIET GAP, and the server-side loop can still be
- * running when the process exits, so the next invocation's inbound lands
- * mid-turn. The agent then fills required fields with placeholder text, or starts
- * a second workflow run. Inside one process the loop simply waits for the settle
- * before sending the next turn, over the same SSE connection.
- */
+/** The line printed for a held turn — what the author needs to know, not a failure. */
+function heldLine(voice) {
+    return voice === 'human'
+        ? '⏸ a person is holding this conversation — the AI Agent will not reply. The operator answers from Live chat in the console; nothing more comes back here for this turn.'
+        : '⏸ waiting for a person to join — the AI Agent will not reply until someone accepts in Live chat, or the wait runs out and the conversation returns to it.';
+}
 async function runChatTurn(args) {
     const { url, tenant, project, from, turn, frames, asJson } = args;
     let boundary = args.boundary;
@@ -2990,15 +3112,23 @@ async function runChatTurn(args) {
         console.log(`  … delivered — waiting for the reply (up to ${Math.round(REPLY_TIMEOUT_MS / 1000)}s)`);
     // Collect THIS turn's renders (id > boundary). A turn can send several
     // messages, so keep reading until a quiet gap after the last render.
+    //
+    // A HELD turn ends the wait too. While a person holds the conversation (or one has been
+    // asked for) the platform deliberately sends no AI Agent reply, and says so with a `held`
+    // envelope; before it did, this loop sat out the whole REPLY_TIMEOUT_MS on every held turn
+    // and the author read it as a hang. After `held` the loop still settles for TURN_SETTLE_MS,
+    // because the same customer message replays any operator line queued while they were away.
     const deadline = Date.now() + REPLY_TIMEOUT_MS;
     let rendersSeen = 0;
+    let held = null;
     for (;;) {
         const remaining = deadline - Date.now();
         if (remaining <= 0)
             break;
-        const f = await frames.next(rendersSeen > 0 ? TURN_SETTLE_MS : Math.min(remaining, REPLY_TIMEOUT_MS));
+        const settling = rendersSeen > 0 || held !== null;
+        const f = await frames.next(settling ? TURN_SETTLE_MS : Math.min(remaining, REPLY_TIMEOUT_MS));
         if (f === 'timeout') {
-            if (rendersSeen > 0)
+            if (settling)
                 break;
             else
                 continue;
@@ -3009,19 +3139,59 @@ async function runChatTurn(args) {
             continue; // late replay stragglers
         if (f.id != null)
             boundary = f.id;
+        if (f.ev?.kind === 'held' && held === null) {
+            held = f.ev.voice === 'human' ? 'human' : 'pending';
+            if (!asJson)
+                console.log(heldLine(held));
+        }
+        // Only an ANSWER ends the wait. A notify (a reminder firing mid-script) is printed, labelled,
+        // and the wait goes on — it used to count as the reply, end the turn on the reminder, and leave
+        // the real reply looking lost (`lib/chat-line.ts`).
         if (asJson) {
             console.log(JSON.stringify(f.ev));
-            if (f.ev?.kind === 'render')
+            if (f.ev?.kind === 'render' && answersTheTurn(f.ev))
                 rendersSeen++;
             continue;
         }
         if (f.ev?.kind !== 'render')
             continue; // status/typing noise
-        rendersSeen++;
-        console.log(`← ${f.ev.body ?? '(no text body)'}${f.ev.hint?.type && f.ev.hint.type !== 'text' ? `   (render: ${f.ev.hint.type})` : ''}`);
-        printHint(f.ev.hint);
+        if (answersTheTurn(f.ev))
+            rendersSeen++;
+        printRender(f.ev);
+    }
+    return { boundary, rendersSeen, held };
+}
+/** One render line — `← <label><body>` — and its interactive content. */
+function printRender(ev, note = '') {
+    console.log(`← ${chatLabel(ev)}${ev.body ?? '(no text body)'}${ev.hint?.type && ev.hint.type !== 'text' ? `   (render: ${ev.hint.type})` : ''}${note}`);
+    printHint(ev.hint);
+}
+/**
+ * After the LAST turn, keep reading for `LATE_DRAIN_MS` and print what arrives — a notify, a
+ * slow post-turn line — before closing the stream. A render the platform pushes to a stream the
+ * CLI has already closed reaches no one and is recorded as undelivered ("the visitor has no open
+ * chat connection"), which reads like a platform fault when it is only the CLI leaving early.
+ */
+async function drainLateRenders(frames, boundary, asJson) {
+    const deadline = Date.now() + LATE_DRAIN_MS;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return;
+        const f = await frames.next(remaining);
+        if (f === 'timeout' || f === 'done')
+            return;
+        if (f.id != null && f.id <= boundary)
+            continue;
+        if (f.id != null)
+            boundary = f.id;
+        if (asJson) {
+            console.log(JSON.stringify(f.ev));
+            continue;
+        }
+        if (f.ev?.kind === 'render')
+            printRender(f.ev, '   (after the last turn)');
     }
-    return { boundary, rendersSeen };
 }
 /** `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--script <file>] [--json]`
  *  — drive a turn (or a whole scripted conversation) through the dev web channel
@@ -3122,13 +3292,18 @@ async function cmdChat(flags) {
     // Phase 2+3 — run each turn in order, over the SAME connection. One turn is
     // the normal case; `--script` drives a whole conversation.
     let totalRenders = 0;
+    let anyHeld = false;
     for (const [i, turn] of turns.entries()) {
         if (turns.length > 1)
             console.log(`\n── turn ${i + 1}/${turns.length} ──`);
         const r = await runChatTurn({ url, tenant, project, from, turn, frames, boundary, asJson });
         boundary = r.boundary;
         totalRenders += r.rendersSeen;
-        if (r.rendersSeen === 0 && turns.length > 1) {
+        if (r.held)
+            anyHeld = true;
+        // A held turn answered nothing BY DESIGN — the script goes on, so an author can script the
+        // customer's side of a handoff (their lines reach the operator's pane) without it stopping.
+        if (r.rendersSeen === 0 && !r.held && turns.length > 1) {
             // Stop rather than fire the rest of the script into a conversation that
             // isn't answering — the remaining turns would land out of context.
             await cancel();
@@ -3136,8 +3311,9 @@ async function cmdChat(flags) {
             exitNow(1);
         }
     }
+    await drainLateRenders(frames, boundary, asJson);
     await cancel();
-    if (totalRenders === 0) {
+    if (totalRenders === 0 && !anyHeld) {
         console.error(`  no reply after ${Math.round(REPLY_TIMEOUT_MS / 1000)}s — the pack may not be warm yet, or the turn produced no render.`);
         exitNow(1);
     }
@@ -5150,9 +5326,13 @@ async function cmdUsage(flags) {
     const t = resolveTarget(flags);
     const { url } = t;
     const asJson = flags.json === true;
-    const scoped = Boolean(t.project);
+    // A token pinned to one project is refused on the workspace rollup (the pin is a ceiling on
+    // every route), so for a pinned token the project view IS the answer — ask whoami rather
+    // than print a 403 at someone whose token can only ever see one project.
+    const pinned = t.project ? null : await pinnedProjectOf(t);
+    const scoped = Boolean(t.project || pinned);
     if (!asJson)
-        console.log(`→ Reading model usage for ${scoped ? targetLabel(t) : 'the whole workspace'} …`);
+        console.log(`→ Reading model usage for ${scoped ? (pinned ? `project '${pinned}'` : targetLabel(t)) : 'the whole workspace'} …`);
     // Both URLs written out in place, for the same reason as `performance` above: an
     // `endpoint` variable would leave BOTH invisible to `cli-routes.test.ts`.
     const { status, json } = scoped
@@ -5185,388 +5365,408 @@ async function cmdUsage(flags) {
     console.log('\nThis is MODEL spend. WhatsApp/Meta message billing is operator-only — not reachable by an API token.');
 }
 function help() {
-    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
-
-  octwin --version                                      # print the CLI version (+ any upgrade notice)
-  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
-  octwin validate [--dir .] [--remote] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
-  octwin login   --url <platformUrl>                    # approve in a browser; the CLI collects the token
-  octwin login   --url <platformUrl> --token oct_…      # or paste a deploy token from the console
-  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
-  octwin projects [--archived] [--json]                  # the --project slugs this token can name
-  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
-  octwin status  [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
-  octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
-  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
-  octwin work    [recordId] [--queues] [--unrouted] [--json]  # inspect the work inbox (worked records) + timelines
-                 #   --queues: per-queue open counts + an UNROUTED warning · --unrouted: only the items in no queue
-  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
-  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
-  octwin media   generate "<prompt>" [--out <file.png>] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
-  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
-  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
-  octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
-  octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
-  octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
-  octwin automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
-  octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
-  octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
-  octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
-  octwin performance [--detail] [--json]                 # the project's business indicators (value/conversion/duration)
-  octwin usage   [--json]                                # model calls, tokens and cost (project if pinned, else workspace)
-  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
-  octwin test    [--dir .]                               # = validate --remote (the full platform check)
-  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
-  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
-
-Writes — exercise the state your pack creates (each needs the matching :write scope):
-  octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
-  octwin records tasks | task complete <taskId> [--outcome done|cancelled]
-  octwin work    assign <id> --to user:<uuid>|none | note <id> "…" | stage <id> --to <stage>
-  octwin work    decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
-  octwin orders  transition <ref> --to <status> | refund <ref> --force
-  octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
-  octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
-  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
-  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
-  octwin integrations test <key>                         # a LIVE call to the connection's health: operation
-  octwin integrations retry|cancel|send-now <deliveryId>
-  (octwin integrations preflight <key> needs only integrations:read — it makes no call)
-
-Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
-\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
-button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
-Signing in: \`octwin login --url <u>\` prints a link + code to approve in a browser. To pick your own
-scopes instead, mint a token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
-octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
-Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
+    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
+
+  octwin --version                                      # print the CLI version (+ any upgrade notice)
+  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+  octwin validate [--dir .] [--remote | --offline] [--require-kb]   # the platform's FULL check by default — no login needed
+  octwin login   --url <platformUrl>                    # approve in a browser; the CLI collects the token
+  octwin login   --url <platformUrl> --token oct_…      # or paste a deploy token from the console
+  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
+  octwin projects [--archived] [--json]                  # the --project slugs this token can name
+  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
+  octwin status  [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
+  octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
+  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
+  octwin work    [recordId] [--queues] [--unrouted] [--json]  # inspect the work inbox (worked records) + timelines
+                 #   --queues: per-queue open counts + an UNROUTED warning · --unrouted: only the items in no queue
+  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
+  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
+  octwin media   generate "<prompt>" [--out <file.png>] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
+  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
+  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
+  octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
+  octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
+  octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
+  octwin automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
+  octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
+  octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
+  octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
+  octwin performance [--detail] [--json]                 # the project's business indicators (value/conversion/duration)
+  octwin usage   [--json]                                # model calls, tokens and cost (project if pinned, else workspace)
+  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
+  octwin test    [--dir .]                               # = validate --remote (the full platform check)
+  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
+  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
+
+Writes — exercise the state your pack creates (each needs the matching :write scope):
+  octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…", archive|restore <id>
+  octwin records tasks | task complete <taskId> [--outcome done|cancelled]
+  octwin work    assign <id> --to user:<uuid>|none | note <id> "…" | stage <id> --to <stage>
+  octwin work    decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
+  octwin orders  transition <ref> --to <status> | refund <ref> --force
+  octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
+  octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
+  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
+  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
+  octwin integrations test <key>                         # a LIVE call to the connection's health: operation
+  octwin integrations retry|cancel|send-now <deliveryId>
+  (octwin integrations preflight <key> needs only integrations:read — it makes no call)
+
+Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
+\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
+button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
+Signing in: \`octwin login --url <u>\` prints a link + code to approve in a browser. To pick your own
+scopes instead, mint a token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
+octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
+Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
 Per-command usage: octwin <command> --help`);
 }
 /** Per-subcommand usage — printed for `octwin <cmd> --help|-h` BEFORE any
  *  network/auth work (a --help that 401s is worse than no help at all). */
 const COMMAND_HELP = {
-    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   Scaffold a pure-YAML starter pack into <dir>.`,
-    validate: `octwin validate [--dir .] [--remote] [--require-kb] [--strict-primitives]
-  Offline structural check, plus two checks driven by the pulled capability
-  reference (render-intent fields, primitive arguments). Those two SKIP when the
-  reference is missing — the run says so, and --require-kb turns the skip into a
-  failure for CI. --remote additionally runs the platform's FULL manifest +
-  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.
-  --strict-primitives (with --remote) additionally type-checks LITERAL args:
-  values against each primitive's declared input schema; expression strings
-  ('$found.id', '{$t(…)}') are always exempt.`,
-    login: `octwin login --url <platformUrl> [--token oct_…] [--wait <seconds>] [--json]
-  Sign in to a platform and make that url the DEFAULT deploy target for every
-  later command.
-
-  WITH --token: saves a token you minted yourself (console → Settings → API
-  tokens). Unchanged, and still the right answer for CI — there, skip login and
-  set PACK_PLATFORM_URL + PACK_TOKEN instead.
-
-  WITHOUT --token: prints a link to approve in a browser. A workspace admin opens
-  it, checks which machine is asking, and clicks Approve; the CLI then collects a
-  30-day token by itself, so no token is ever pasted between people. The code is
-  printed too — it is what the page shows, so you can tell it is your own request.
-  Approve only a link you opened because YOU ran this command: a link someone
-  sends you would connect THEIR machine to your workspace.
-
-  The wait is bounded (90s by default) and RESUMABLE: if nobody has approved yet
-  it exits 75 and keeps the request, so running \`octwin login\` again picks up the
+    validate: `octwin validate [--dir .] [--remote | --offline] [--require-kb] [--strict-primitives]
+  First the fast OFFLINE checks (structure, YAML, and the checks driven by the
+  pulled capability reference — those SKIP when the reference is missing, and
+  --require-kb turns the skip into a failure for CI). Then, BY DEFAULT, the
+  platform's FULL validation — the same check deploy runs, all errors at once.
+
+  The full check needs NO login: without a token + --project it goes to the
+  platform's public validate route. With a token AND --project (or PACK_PROJECT)
+  it goes through your workspace, which also confirms that project exists.
+
+  When the platform cannot be reached (no url, offline, rate-limited) the run
+  ends with "only the OFFLINE check ran — a PARTIAL check" and exits 0.
+  --remote REQUIRES the full check: not reaching it is an error. --offline runs
+  only the partial subset. --strict-primitives additionally type-checks LITERAL
+  args: values against each primitive's declared input schema; expression
+  strings ('$found.id', '{$t(…)}') are always exempt.`,
+    login: `octwin login --url <platformUrl> [--token oct_…] [--wait <seconds>] [--json]
+  Sign in to a platform and make that url the DEFAULT deploy target for every
+  later command.
+
+  WITH --token: saves a token you minted yourself (console → Settings → API
+  tokens). Unchanged, and still the right answer for CI — there, skip login and
+  set PACK_PLATFORM_URL + PACK_TOKEN instead.
+
+  WITHOUT --token: prints a link to approve in a browser. A workspace admin opens
+  it, checks which machine is asking, and clicks Approve; the CLI then collects a
+  30-day token by itself, so no token is ever pasted between people. The code is
+  printed too — it is what the page shows, so you can tell it is your own request.
+  Approve only a link you opened because YOU ran this command: a link someone
+  sends you would connect THEIR machine to your workspace.
+
+  The wait is bounded (90s by default) and RESUMABLE: if nobody has approved yet
+  it exits 75 and keeps the request, so running \`octwin login\` again picks up the
   same code. --wait 0 prints the code and returns at once.`,
-    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
+    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
-    projects: `octwin projects [--archived] [--json]
-  List the workspace's projects — the slugs every --project flag takes, with the
-  plan's project cap. --archived includes archived ones. A pack:deploy token
-  reaches this (it names a project in every other command).
-
-octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
-  Create a project. The URL slug is derived from the name unless --slug pins one.
-  --pack installs an ALREADY-published pack; the usual next step is instead
-  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
-
-octwin projects rm <slug> [--yes]
-  HARD delete — the project and everything cascading from it (conversations,
-  contacts, records, installs). No undo, and not the same as archiving.
-  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
-  default. Together these make a disposable end-to-end environment:
-    octwin projects create "Scratch" && octwin deploy --project scratch --seed
-    octwin chat "hi" --project scratch
-    octwin projects rm scratch --yes
+    projects: `octwin projects [--archived] [--json]
+  List the workspace's projects — the slugs every --project flag takes, with the
+  plan's project cap. --archived includes archived ones. A pack:deploy token
+  reaches this (it names a project in every other command).
+
+octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
+  Create a project. The URL slug is derived from the name unless --slug pins one.
+  --pack installs an ALREADY-published pack; the usual next step is instead
+  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
+
+octwin projects rm <slug> [--yes]
+  HARD delete — the project and everything cascading from it (conversations,
+  contacts, records, installs). No undo, and not the same as archiving.
+  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
+  default. Together these make a disposable end-to-end environment:
+    octwin projects create "Scratch" && octwin deploy --project scratch --seed
+    octwin chat "hi" --project scratch
+    octwin projects rm scratch --yes
   Both verbs need the \`projects:write\` scope — a pack:deploy token does NOT confer it.`,
-    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-                [--request-listing | --withdraw-listing]
-  Upload the pack bundle, validate server-side, install onto the project.
-  --seed additionally applies the pack's demo seed (streams progress).
-
-  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
-  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
-
-  --request-listing    ask an operator to review this pack for the public marketplace
-                       (the pre-signup storefront at /packs). Requires 'public: true'
-                       under 'listing:' in manifest.yaml — the manifest states that the
-                       pack is a product, the flag is you choosing to ask.
-  --withdraw-listing   retract the request, including an approved listing.
-
-  An approval covers the CONTENT it was made against, so a later deploy that changes the
+    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+                [--request-listing | --withdraw-listing]
+  Upload the pack bundle, validate server-side, install onto the project.
+  --seed additionally applies the pack's demo seed (streams progress).
+
+  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
+  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
+
+  --request-listing    ask an operator to review this pack for the public marketplace
+                       (the pre-signup storefront at /packs). Requires 'public: true'
+                       under 'listing:' in manifest.yaml — the manifest states that the
+                       pack is a product, the flag is you choosing to ask.
+  --withdraw-listing   retract the request, including an approved listing.
+
+  An approval covers the CONTENT it was made against, so a later deploy that changes the
   pack returns it to the review queue on its own — no flag needed, and the CLI says so.`,
-    seed: `octwin seed [--pack <packId>]
-  Apply the pack's demo/reference data to the project it is installed on, without
-  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
-  and the demo operator topology. Reports what each kind produced.
-  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
-  than regenerated, so a second pass costs nothing. --pack is only needed when a
+    seed: `octwin seed [--pack <packId>]
+  Apply the pack's demo/reference data to the project it is installed on, without
+  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
+  and the demo operator topology. Reports what each kind produced.
+  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
+  than regenerated, so a second pass costs nothing. --pack is only needed when a
   project somehow runs more than one.`,
-    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
-  Show installed vs live version + the flow list for this pack.
-  The pack id is read from manifest.yaml and QUALIFIED with your workspace slug
-  (a manifest declares a bare name; the owner is attached when you publish). Pass
-  <packId> explicitly to skip that lookup — \`octwin agents\` and \`octwin projects\`
+    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
+  Show installed vs live version + the flow list for this pack.
+  The pack id is read from manifest.yaml and QUALIFIED with your workspace slug
+  (a manifest declares a bare name; the owner is attached when you publish). Pass
+  <packId> explicitly to skip that lookup — \`octwin agents\` and \`octwin projects\`
   both print the qualified form.`,
-    records: `octwin records [entity] [id] [--limit 50] [--offset n]
-  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
-  tickets, anything routed to a queue) read best through \`octwin work\`.
-
-  WRITES (need \`records:write\`; every one is re-checked by RBAC on the record):
-    octwin records create <entity> --set field=value [--set …] [--stage s] [--contact <id>]
-    octwin records patch  <recordId> --entity <entity> --set field=value
-    octwin records stage  <recordId> --to <stage> [--note "..."]
-    octwin records note   <recordId> "the note text"
-    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
-    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
-
-  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
-  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
-  \`patch\` needs --entity even though it has an id: the route resolves the field
-  validator from it. A leading \`create/patch/stage/note/tasks/task\` is read as a
-  VERB — to list an entity actually named one of those, use \`--entity <name>\`.`,
-    work: `octwin work [recordId] [--queues] [--unrouted] [--limit 50] [--offset n] [--json]
-  Inspect the work inbox — every entity the pack declares worked (cases, orders
-  needing review, applications, …): the inbox, one item + its timeline
-  (+ applicable actions), or --queues for queue keys + open counts.
-
-  WRITES (need \`work:write\`; \`stage\` needs \`records:write\`):
-    octwin work assign <recordId> --to user:<uuid>|team:<uuid>|none
-    octwin work note   <recordId> "the note text"
-    octwin work stage  <recordId> --to <stage> [--note "..."]
-    octwin work decide <recordId> --action <action> [--param k=v] [--note "..."] [--dry-run]
-
-  \`decide\` applies one of the entity's declared operator actions — \`octwin work <id>\`
-  lists them with their params. --dry-run previews the customer-facing copy and the
-  resulting stage WITHOUT committing (that route needs only \`work:read\`).
+    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 archive <recordId>          # out of every list and count (test data too)
+    octwin records restore <recordId>          # undo an archive
+    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
+    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
+
+  There is NO delete — on the platform or here. \`archive\` is how a record leaves use:
+  it fires the entity's \`on.archived\` reactions, exactly like the console's Archive,
+  and \`restore\` brings it back.
+
+  --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/archive/restore/tasks/task\` is
+  read as a VERB — to list an entity actually named one of those, use \`--entity <name>\`.`,
+    work: `octwin work [recordId] [--queues] [--unrouted] [--limit 50] [--offset n] [--json]
+  Inspect the work inbox — every entity the pack declares worked (cases, orders
+  needing review, applications, …): the inbox, one item + its timeline
+  (+ applicable actions), or --queues for queue keys + open counts.
+
+  WRITES (need \`work:write\`; \`stage\` needs \`records:write\`):
+    octwin work assign <recordId> --to user:<uuid>|team:<uuid>|none
+    octwin work note   <recordId> "the note text"
+    octwin work stage  <recordId> --to <stage> [--note "..."]
+    octwin work decide <recordId> --action <action> [--param k=v] [--note "..."] [--dry-run]
+
+  \`decide\` applies one of the entity's declared operator actions — \`octwin work <id>\`
+  lists them with their params. --dry-run previews the customer-facing copy and the
+  resulting stage WITHOUT committing (that route needs only \`work:read\`).
   \`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.
+
+  Each reply line says who sent it. Plain \`← …\` is the AI Agent. \`← [notify] …\` is a
+  reminder or notification (a \`schedule_notify\`, a reaction) — NOT the turn's answer,
+  so the wait for the real reply goes on. \`← [operator: Name] …\` is a person in
+  Live chat; \`← [platform] …\` is a platform line (a handoff joining or returning).
+  After the last turn the stream stays open ${LATE_DRAIN_MS / 1000}s more, so a late message
+  still prints (marked "after the last turn") instead of reaching a closed connection.
+
+  --script drives a WHOLE conversation from a file, ONE TURN PER LINE, in one
+  process over one connection — waiting for each turn to settle before sending
+  the next. Use this for any multi-step flow: chaining shell invocations races
+  the agent loop, because a turn ends on a quiet gap that can arrive while the
+  server is still working (the symptom is placeholder-filled fields or a second
+  workflow run). Blank lines and # comments are skipped:
+
+    # book an appointment end to end
+    احجز موعد
+    tap:t:invoke:book-appointment:doctor_id=D1
+    media:./licence.jpg | here is my licence
     tap:t:resume:book-appointment:run_id=R1;_ctl_approved=true`,
-    media: `octwin media generate "<prompt>" [--out <file.png>] [--json]
-  AI-generate an image (needs a media:generate-scoped token), store it as a
-  public asset, and print its MEDIA- handle + serve URL. --out downloads the
-  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
+    media: `octwin media generate "<prompt>" [--out <file.png>] [--json]
+  AI-generate an image (needs a media:generate-scoped token), store it as a
+  public asset, and print its MEDIA- handle + serve URL. --out downloads the
+  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
   bytes }. Pair with 'octwin chat --media' to drive media flows.`,
-    agents: `octwin agents [packId::agentId] [--prompt] [--json]
-  No args = the roster with each agent's EFFECTIVE model and which layer set it.
-  With an agent = every governed setting (model / memory.last_messages /
-  working_memory) plus the layer that won — an operator PLATFORM default can
-  override what your manifest declares, and this is where you see that.
-  --prompt = the exact system prompt the LLM sees for this project (pack
-  instructions + platform protocol + any project overlay). Needs agents:read.
-  The agent ref is the compound \`<packId>::<agentId>\` key or the override-row UUID.
-
-  WRITES (need \`agents:write\`):
-    octwin agents set <ref> [--model <m>] [--enabled true|false] [--overlay "..."|none]
-                            [--enable-tool <toolId>] [--disable-tool <toolId>]
-
-  Only what you pass is changed. Tool flags read-modify-write \`config_json.tools\`
-  so a sibling decision isn't dropped; absent = enabled. A workspace that hides model
+    agents: `octwin agents [packId::agentId] [--prompt] [--json]
+  No args = the roster with each agent's EFFECTIVE model and which layer set it.
+  With an agent = every governed setting (model / memory.last_messages /
+  working_memory) plus the layer that won — an operator PLATFORM default can
+  override what your manifest declares, and this is where you see that.
+  --prompt = the exact system prompt the LLM sees for this project (pack
+  instructions + platform protocol + any project overlay). Needs agents:read.
+  The agent ref is the compound \`<packId>::<agentId>\` key or the override-row UUID.
+
+  WRITES (need \`agents:write\`):
+    octwin agents set <ref> [--model <m>] [--enabled true|false] [--overlay "..."|none]
+                            [--enable-tool <toolId>] [--disable-tool <toolId>]
+
+  Only what you pass is changed. Tool flags read-modify-write \`config_json.tools\`
+  so a sibling decision isn't dropped; absent = enabled. A workspace that hides model
   ids refuses --model with a 403 — the platform default governs there.`,
-    orders: `octwin orders [reference_id] [--status s] [--payment p] [--limit 50] [--json]
-  No args = the order list (#number, status/payment, total, contact). With a
-  reference_id = line items, the subtotal/tax/shipping/discount/total breakdown,
-  payment_ref, and the allowed status transitions. Needs orders:read + the
-  \`orders\` plan feature. Note: the forward payment lifecycle is webhook-owned,
-  so \`pending\` on a gateway-less workspace is expected, not a bug.
-
-  WRITES (need \`orders:write\`):
-    octwin orders transition <reference_id> --to <status>
-    octwin orders refund     <reference_id> [--reason "..."] [--mark-returned] --force
-
-  Refund is irreversible and moves money, hence --force. The route answers 200 even
-  when the GATEWAY refuses, so the CLI reads the gateway verdict and exits non-zero
-  on a refusal rather than reporting a refund that never happened. Only a payment in
+    orders: `octwin orders [reference_id] [--status s] [--payment p] [--limit 50] [--json]
+  No args = the order list (#number, status/payment, total, contact). With a
+  reference_id = line items, the subtotal/tax/shipping/discount/total breakdown,
+  payment_ref, and the allowed status transitions. Needs orders:read + the
+  \`orders\` plan feature. Note: the forward payment lifecycle is webhook-owned,
+  so \`pending\` on a gateway-less workspace is expected, not a bug.
+
+  WRITES (need \`orders:write\`):
+    octwin orders transition <reference_id> --to <status>
+    octwin orders refund     <reference_id> [--reason "..."] [--mark-returned] --force
+
+  Refund is irreversible and moves money, hence --force. The route answers 200 even
+  when the GATEWAY refuses, so the CLI reads the gateway verdict and exits non-zero
+  on a refusal rather than reporting a refund that never happened. Only a payment in
   \`captured\` state can be refunded; \`payment_status\` is never settable directly.`,
-    analytics: `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>] [--json]
-  No args = the entities that carry a \`pipeline:\` (a funnel needs stages).
-  With an entity = stage-by-stage conversion (default --funnel) over the last 30
-  days. --stage <id> lists the records CURRENTLY at a stage (a live snapshot, not
+    analytics: `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>] [--json]
+  No args = the entities that carry a \`pipeline:\` (a funnel needs stages).
+  With an entity = stage-by-stage conversion (default --funnel) over the last 30
+  days. --stage <id> lists the records CURRENTLY at a stage (a live snapshot, not
   range-filtered). Needs records:read + a \`view\` grant on \`record.<entity>\`.`,
-    catalog: `octwin catalog [--readiness] [--json]
-  The commerce \`product\` records + price, availability, stock (null = not
-  inventory-tracked) and the WhatsApp catalog binding. --readiness runs the Meta
-  Graph checklist (LIVE Graph calls; needs a bound access token). Needs
-  catalog:read + the \`catalog\` plan feature.
-
-  WRITES (need \`catalog:write\`):
-    octwin catalog availability <retailerId> --to "in stock"|"out of stock"|…
-    octwin catalog stock        <retailerId> [--set-on-hand <n>]
-
-  \`stock\` with no --set-on-hand READS it; \`null\` means the SKU is not
-  inventory-tracked (always sellable), which is different from 0. Lowering on_hand
-  below the units already reserved for open carts is refused. Creating/deleting
+    catalog: `octwin catalog [--readiness] [--json]
+  The commerce \`product\` records + price, availability, stock (null = not
+  inventory-tracked) and the WhatsApp catalog binding. --readiness runs the Meta
+  Graph checklist (LIVE Graph calls; needs a bound access token). Needs
+  catalog:read + the \`catalog\` plan feature.
+
+  WRITES (need \`catalog:write\`):
+    octwin catalog availability <retailerId> --to "in stock"|"out of stock"|…
+    octwin catalog stock        <retailerId> [--set-on-hand <n>]
+
+  \`stock\` with no --set-on-hand READS it; \`null\` means the SKU is not
+  inventory-tracked (always sellable), which is different from 0. Lowering on_hand
+  below the units already reserved for open carts is refused. Creating/deleting
   products and the Meta catalog binding/sync stay in the console.`,
-    scheduling: `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]
-  No args = the engine state (bookable resource types, upcoming slots, booked
-  seats). --slots <recordId> computes the slots for one bookable resource
-  (occupancy included; --days is clamped to 1-31 server-side) — the way to verify
-  the availability rules a \`deploy --seed\` created. Needs scheduling:read.
-
-  RULES (list needs scheduling:read; add/rm need scheduling:write):
-    octwin scheduling rules --resource <resourceRecordId>
-    octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00
-                               [--slot-minutes 30] [--capacity 1]
-    octwin scheduling rule rm  <ruleId>
-    octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra
-                                    [--start 09:00 --end 13:00]
-    octwin scheduling exception rm  <exceptionId>
-
-  --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
+    scheduling: `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]
+  No args = the engine state (bookable resource types, upcoming slots, booked
+  seats). --slots <recordId> computes the slots for one bookable resource
+  (occupancy included; --days is clamped to 1-31 server-side) — the way to verify
+  the availability rules a \`deploy --seed\` created. Needs scheduling:read.
+
+  RULES (list needs scheduling:read; add/rm need scheduling:write):
+    octwin scheduling rules --resource <resourceRecordId>
+    octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00
+                               [--slot-minutes 30] [--capacity 1]
+    octwin scheduling rule rm  <ruleId>
+    octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra
+                                    [--start 09:00 --end 13:00]
+    octwin scheduling exception rm  <exceptionId>
+
+  --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
   \`--slots\` is how you check what a rule actually produces.`,
-    automation: `octwin automation [campaigns] [--limit n] [--offset n] [--json]
-  No args = every job the pack's automation declaration produced, with its status,
-  interval and LAST RESULT (matched / acted / errors), under a health line whose
-  counts come from SQL rather than from filtering the page — the job list is capped
-  server-side, so a client-side count would depend on the cap. Needs automation:read.
-
-  Jobs are DERIVED from declarations. There is no \`create\`: no automation block in
-  the pack means no jobs, and \`octwin deploy\` is what installs them.
-
-  WRITES (automation:write):
-    octwin automation run <jobId>          # run once, now — prints matched/acted/errors
-    octwin automation pause|resume <jobId>
-    octwin automation send <campaignId>    # enqueue a campaign; enqueued != delivered
-
-  <jobId> is the \`key\` the list shows (its uuid works too). The routes themselves
-  accept only a uuid — the CLI resolves the key for you, and names the keys that do
-  exist when it cannot. A 403 on a write can be an RBAC grant gap rather than a
+    automation: `octwin automation [campaigns] [--limit n] [--offset n] [--json]
+  No args = every job the pack's automation declaration produced, with its status,
+  interval and LAST RESULT (matched / acted / errors), under a health line whose
+  counts come from SQL rather than from filtering the page — the job list is capped
+  server-side, so a client-side count would depend on the cap. Needs automation:read.
+
+  Jobs are DERIVED from declarations. There is no \`create\`: no automation block in
+  the pack means no jobs, and \`octwin deploy\` is what installs them.
+
+  WRITES (automation:write):
+    octwin automation run <jobId>          # run once, now — prints matched/acted/errors
+    octwin automation pause|resume <jobId>
+    octwin automation send <campaignId>    # enqueue a campaign; enqueued != delivered
+
+  <jobId> is the \`key\` the list shows (its uuid works too). The routes themselves
+  accept only a uuid — the CLI resolves the key for you, and names the keys that do
+  exist when it cannot. A 403 on a write can be an RBAC grant gap rather than a
   missing scope: the action is re-checked against the job.`,
-    integrations: `octwin integrations [--json]
-  What the pack DECLARES beside what is actually CONFIGURED, in one view — because a
-  connection that is declared and never configured is the commonest reason an
-  integration silently never fires, and neither list alone can show it. Flags the
-  gap explicitly. Needs integrations:read.
-
-  DIAGNOSE ONE CONNECTION:
-    octwin integrations preflight <key>    # every check, with a fix hint. Makes NO
-                                           # outbound call — needs only integrations:read
-    octwin integrations test <key>         # a LIVE call to its health: operation
-                                           # (integrations:write). Exits 1 when it fails.
-
-  THE DELIVERY LOG:
-    octwin integrations deliveries [--status s] [--operation id] [--limit n]
-    octwin integrations deliveries <id>    # + the redacted request/response snapshots
-    octwin integrations retry|cancel|send-now <id>     # integrations:write
-    octwin integrations events             # INBOUND events (what arrived at your webhook)
-
-  retry/cancel answer 409 when the delivery is in the wrong state; the message
+    integrations: `octwin integrations [--json]
+  What the pack DECLARES beside what is actually CONFIGURED, in one view — because a
+  connection that is declared and never configured is the commonest reason an
+  integration silently never fires, and neither list alone can show it. Flags the
+  gap explicitly. Needs integrations:read.
+
+  DIAGNOSE ONE CONNECTION:
+    octwin integrations preflight <key>    # every check, with a fix hint. Makes NO
+                                           # outbound call — needs only integrations:read
+    octwin integrations test <key>         # a LIVE call to its health: operation
+                                           # (integrations:write). Exits 1 when it fails.
+
+  THE DELIVERY LOG:
+    octwin integrations deliveries [--status s] [--operation id] [--limit n]
+    octwin integrations deliveries <id>    # + the redacted request/response snapshots
+    octwin integrations retry|cancel|send-now <id>     # integrations:write
+    octwin integrations events             # INBOUND events (what arrived at your webhook)
+
+  retry/cancel answer 409 when the delivery is in the wrong state; the message
   carries the rule.`,
-    journeys: `octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]
-                  [--stage <stageId>] [--limit n] [--json]
-  No args = the journeys the pack declares. With an id, one of six views —
-  --funnel (default) stage-by-stage reach and drop-off · --overview entered vs
-  converted plus the biggest drop-off · --goals completions, contacts, value and
-  p50 time · --trends per-bucket activity · --cost tokens and dollars per goal ·
-  --definition what was DECLARED, unmeasured (the one view that works with no
-  traffic). Needs journeys:read.
-
-  --stage <stageId> lists the runs sitting at a stage right now (a live snapshot,
-  not the funnel's cumulative reached counts).
-
-  Same flag grammar as \`octwin analytics\` on purpose: a journey funnel and an
-  entity funnel are the same question about different subjects. Journeys carry RBAC
-  on top of the scope, so an empty answer can be a missing \`view\` grant rather
+    journeys: `octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]
+                  [--stage <stageId>] [--limit n] [--json]
+  No args = the journeys the pack declares. With an id, one of six views —
+  --funnel (default) stage-by-stage reach and drop-off · --overview entered vs
+  converted plus the biggest drop-off · --goals completions, contacts, value and
+  p50 time · --trends per-bucket activity · --cost tokens and dollars per goal ·
+  --definition what was DECLARED, unmeasured (the one view that works with no
+  traffic). Needs journeys:read.
+
+  --stage <stageId> lists the runs sitting at a stage right now (a live snapshot,
+  not the funnel's cumulative reached counts).
+
+  Same flag grammar as \`octwin analytics\` on purpose: a journey funnel and an
+  entity funnel are the same question about different subjects. Journeys carry RBAC
+  on top of the scope, so an empty answer can be a missing \`view\` grant rather
   than missing data — the output says which causes are possible.`,
-    performance: `octwin performance [--detail] [--json]
-  The project's business indicators — value produced, conversion, duration — each
-  with its delta against the previous window and a \`why\` naming the declaration it
-  came from. --detail adds the per-indicator breakdown.
-
-  Needs records:read, NOT a performance scope (there is none), so a read-only token
-  already reaches it. Indicators are DERIVED: a pack that declares no journey goal
+    performance: `octwin performance [--detail] [--json]
+  The project's business indicators — value produced, conversion, duration — each
+  with its delta against the previous window and a \`why\` naming the declaration it
+  came from. --detail adds the per-indicator breakdown.
+
+  Needs records:read, NOT a performance scope (there is none), so a read-only token
+  already reaches it. Indicators are DERIVED: a pack that declares no journey goal
   value and no pipelined entity produces none, which is a different thing from zero.`,
-    usage: `octwin usage [--json]
-  Model calls, tokens and cost for the resolved scope — project when one is pinned
-  or passed with --project, otherwise the whole workspace. Broken down by model,
-  kind, agent and channel.
-
-  Needs no particular scope: any valid token reaches it.
-
-  This is MODEL spend only. WhatsApp/Meta message billing is operator-only and
+    usage: `octwin usage [--json]
+  Model calls, tokens and cost for the resolved scope — project when one is pinned
+  or passed with --project, otherwise the whole workspace. Broken down by model,
+  kind, agent and channel.
+
+  Needs no particular scope: any valid token reaches it.
+
+  This is MODEL spend only. WhatsApp/Meta message billing is operator-only and
   deliberately outside the token scope registry — no API token can read it.`,
-    'platform-kb': `octwin platform-kb [pull] [--if-stale] [--check] [--dir .] [--url <url>] [--token <t>]
-  Pull the platform capability reference (markdown + JSON catalogs) into
-  .octwin/platform-kb/ for the octwin-pack authoring skill, plus three maps:
-  INDEX.md (the corpus) · SYMBOLS.md (every name -> its file; grep this) ·
-  OUTLINE.md (every heading with its line number).
-
-  NO TOKEN NEEDED — the reference is platform stdlib and is served anonymously,
-  and this command never sends one. --token is accepted and ignored, so an older
-  script that passes it keeps working.
-
-  --if-stale   poll the platform's content_hash first and skip the download when
-               nothing changed. Cheap enough to run at the start of every session.
-  --check      report only, write nothing. Exit 0 = current, 2 = stale or never
-               pulled, 1 = could not tell (offline / no reference served). For
+    'platform-kb': `octwin platform-kb [pull] [--if-stale] [--check] [--dir .] [--url <url>] [--token <t>]
+  Pull the platform capability reference (markdown + JSON catalogs) into
+  .octwin/platform-kb/ for the octwin-pack authoring skill, plus three maps:
+  INDEX.md (the corpus) · SYMBOLS.md (every name -> its file; grep this) ·
+  OUTLINE.md (every heading with its line number).
+
+  NO TOKEN NEEDED — the reference is platform stdlib and is served anonymously,
+  and this command never sends one. --token is accepted and ignored, so an older
+  script that passes it keeps working.
+
+  --if-stale   poll the platform's content_hash first and skip the download when
+               nothing changed. Cheap enough to run at the start of every session.
+  --check      report only, write nothing. Exit 0 = current, 2 = stale or never
+               pulled, 1 = could not tell (offline / no reference served). For
                scripts and agent loops that want to branch without parsing prose.`,
-    test: `octwin test [--dir .]
+    test: `octwin test [--dir .]
   Alias for \`octwin validate --remote\` — the full platform check.`,
-    memos: `octwin memos [--all] [--json]
-  Read what the platform has told you: a REPLY to a report you sent with
-  \`octwin feedback\`, or a NOTICE published to every author (a new capability,
-  a deprecation, a breaking change). Bodies are printed in full.
-  Reading marks them read, so the reminder stops. --all re-reads history and
-  acks nothing. --json to branch on \`severity\`
+    memos: `octwin memos [--all] [--json]
+  Read what the platform has told you: a REPLY to a report you sent with
+  \`octwin feedback\`, or a NOTICE published to every author (a new capability,
+  a deprecation, a breaking change). Bodies are printed in full.
+  Reading marks them read, so the reminder stops. --all re-reads history and
+  acks nothing. --json to branch on \`severity\`
   (info | action_required | breaking).`,
-    feedback: `octwin feedback [--dir .]
-  Submit this pack's FEEDBACK.md to the platform team.
-  The octwin-pack skill writes that file in its last step — findings grouped by
-  owner (A · CLI, B · Platform, C · Skill/KB). This delivers it instead of asking
-  you to paste it into a chat.
-  Attaches the pack id + version from manifest.yaml, this CLI's version, and the
-  content_hash of the capability reference in .octwin/platform-kb/ — triage needs
-  the last two to tell "the platform is wrong" from "that was already fixed" or
+    feedback: `octwin feedback [--dir .]
+  Submit this pack's FEEDBACK.md to the platform team.
+  The octwin-pack skill writes that file in its last step — findings grouped by
+  owner (A · CLI, B · Platform, C · Skill/KB). This delivers it instead of asking
+  you to paste it into a chat.
+  Attaches the pack id + version from manifest.yaml, this CLI's version, and the
+  content_hash of the capability reference in .octwin/platform-kb/ — triage needs
+  the last two to tell "the platform is wrong" from "that was already fixed" or
   "you were reading a stale reference". Needs the \`pack:deploy\` scope.`,
 };
 async function main() {