octwin-cli 0.8.5 → 0.8.7

package/dist/index.js

@@ -73,7 +73,8 @@ import { loadBuiltinNames, findBuiltinViolations, describeBuiltinFinding } from
 import { loadTemplateSpecs, findTemplateViolations, describeTemplateFinding } from './lib/template-check.js';
 import { loadSystemEntities, findEntityViolations, describeEntityFinding } from './lib/entity-check.js';
 import { loadDeclarationSpecs, findDeclarationViolations, describeDeclarationFinding } from './lib/declaration-check.js';
-import { describeKbLookup, findPlatformKbDir } from './lib/kb-path.js';
+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 { kbOneLiner, buildKbIndexMarkdown, buildKbOutlineMarkdown, } from './lib/kb-index.js';
@@ -976,158 +977,161 @@ async function cmdValidate(flags) {
     const yamlDocs = () => parsed;
     // Checks that need the pulled KB. All of them DEGRADE when it is absent — the KB
     // is a gitignored cache wiped by every pull, so failing hard would break a fresh
-    // clone before the author could act. But a skip is ANNOUNCED, and remembered:
-    // the ✓ used to print above these blocks unconditionally while the per-check ✓s
-    // lived inside the `if`s, so a KB-less run read as "one check, passed". An entire
-    // backlog batch reached production that way. The defect is the silence, not the skip.
+    // clone before the author could act. But a skip is ANNOUNCED, and remembered.
     //
-    // Reasons are COLLECTED rather than printed inline. When the KB is missing, every
-    // check skips for the identical reason, and six copies of one sentence is how a
-    // reader learns to scroll past the ⚠ block — which is the same failure as not
-    // printing it. One line, naming all six.
-    const skipped = [];
-    const skipReasons = new Map();
-    const noteSkip = (label, lookup) => {
-        skipped.push(label);
-        // Group by the lookup's IDENTITY, then let `describeKbLookup` phrase the one
-        // line at print time — so the wording stays in the module that owns it and
-        // cannot drift into a doubled "SKIPPED — SKIPPED —".
-        const key = lookup.state === 'ok' ? 'ok'
-            : `${lookup.state}|${'dir' in lookup ? lookup.dir : ''}|${'reason' in lookup ? lookup.reason : ''}`;
-        const bucket = skipReasons.get(key) ?? { lookup, labels: [] };
-        bucket.labels.push(label);
-        skipReasons.set(key, bucket);
-    };
+    // Each check RETURNS an `Outcome` and prints nothing; `reportChecks` renders all of
+    // them and groups the skips by reason. That is the whole point: a check that returns
+    // nothing cannot reach the `passed` branch, so the false-`✓` this file printed twice
+    // before — once for six checks at a time, once over an unparseable file — is no longer
+    // a mistake anyone can make. See [`lib/outcome.ts`](./lib/outcome.ts).
     /** Stamp each finding with its source line — the walkers carry the node
      *  path; `files` holds the raw text the locator needs (E-08). */
     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, render.nested)));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} render-intent field error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeRenderFinding(f)}`);
-            die('fix these before deploying — the platform rejects them at load, and before that they rendered as nothing');
-        }
-        console.log('✓ render intents use only fields the platform renders');
-    }
-    else {
-        noteSkip('render-intent fields', render.lookup);
-    }
-    // Primitive `args:` keys, same source and same contract. Cannot see inside a
-    // `use:` template body (expansion is the platform's job); `--remote` covers that.
-    const args = loadPrimitiveArgSpecs(packDir);
-    if (args.specs) {
-        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findArgViolations(doc, p, args.specs)));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} primitive-argument error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeArgFinding(f)}`);
-            die('fix these before deploying — an undeclared argument is dropped with no error at runtime');
-        }
-        console.log('✓ primitive arguments match their declared inputs');
-    }
-    else {
-        noteSkip('primitive arguments', args.lookup);
-    }
-    // Expression builtins — the function set is CLOSED and generated from the
-    // runtime, so an invented `$fn(` is checkable here and nowhere else offline.
-    const builtins = loadBuiltinNames(packDir);
-    if (builtins.names) {
-        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findBuiltinViolations(doc, p, builtins.names)));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} unknown expression function${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeBuiltinFinding(f)}`);
-            die('fix these before deploying — the evaluator cannot resolve them, and it fails mid-conversation');
-        }
-        console.log('✓ every $function() in an expression exists');
-    }
-    else {
-        noteSkip('expression functions', builtins.lookup);
-    }
-    // `use:` templates. A pack's OWN templates shadow the platform's, so they are
-    // named here and skipped — this check has no schema for them.
-    const templates = loadTemplateSpecs(packDir);
-    if (templates.specs) {
-        // A pack template is `templates/<name>.template.yaml` — the `.template`
-        // segment is part of the convention the expander scans for, NOT part of the
-        // name a `use:` writes. Capturing it would leave every pack that shadows a
-        // platform template (kaiian shadows `field_prompt_render`) reported as using
-        // one that does not exist.
-        const packTemplates = new Set(Object.keys(files)
-            .map(p => /^templates\/(.+)\.template\.ya?ml$/i.exec(p.replace(/\\/g, '/'))?.[1])
-            .filter((n) => !!n));
-        const findings = yamlDocs().flatMap(([p, doc]) => findTemplateViolations(doc, p, templates.specs, packTemplates));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} template error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeTemplateFinding(f)}`);
-            die('fix these before deploying — a template param that does not exist arrives as undefined, and renders as a blank');
-        }
-        console.log('✓ `use:` templates and their params exist');
-    }
-    else {
-        noteSkip('`use:` templates', templates.lookup);
-    }
-    // Reserved XRM entity keys — a boot error, which means the pack deploys clean
-    // and then fails to load on the first inbound message.
-    const system = loadSystemEntities(packDir);
-    if (system.entities) {
-        const findings = yamlDocs()
-            .filter(([p]) => /(^|[/\\])xrm\.ya?ml$/i.test(p))
-            .flatMap(([p, doc]) => findEntityViolations(doc, p, system.entities, system.rules));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} reserved-entity error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeEntityFinding(f)}`);
-            die('fix these before deploying — these fail at BOOT, after a deploy that reported success');
-        }
-        // Name the narrower promise when the catalog-level rules are absent (a KB
-        // pulled before they were published) — a ✓ that reads wider than what ran is
-        // the failure this file's skip contract exists to prevent.
-        console.log(system.rules
-            ? '✓ no entity collides with a reserved platform key, and no extension overrides a platform-owned one'
-            : '✓ no entity collides with a reserved platform key (re-pull for the `contact`/extension-override rules)');
-    }
-    else {
-        noteSkip('reserved entity keys', system.lookup);
-    }
-    // The declaration files themselves, against the published JSON Schemas.
-    // Deliberately narrow (see declaration-check.ts) — it walks away from anything
-    // it cannot read rather than guessing.
-    const decls = loadDeclarationSpecs(packDir);
-    if (decls.specs) {
-        const findings = yamlDocs().flatMap(([p, doc]) => {
-            const base = p.replace(/\\/g, '/').split('/').pop() ?? p;
-            const spec = decls.specs.get(base);
-            // Only a file at the PACK ROOT is a declaration — `flows/tools/xrm.yaml`
-            // would be a flow that happens to share a name.
-            if (!spec || p.replace(/\\/g, '/').includes('/'))
-                return [];
-            return findDeclarationViolations(doc, spec).map(f => ({ ...f, file: p }));
-        });
-        if (findings.length) {
-            console.error(`✗ ${findings.length} declaration error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeDeclarationFinding(f)}`);
-            die('fix these before deploying — a declaration file is parsed strictly, and an unknown key is rejected');
-        }
-        // Deliberately narrow wording. Most of `xrm.yaml`'s field shapes are a Zod
-        // union, which renders as `anyOf` and which this check walks away from by
-        // design — so "matches its schema" would be a promise it does not keep, and
-        // an over-claimed ✓ is how an author stops reading `--remote` output.
-        console.log('✓ declaration files carry no unknown or missing keys (unions are left to --remote)');
-    }
-    else {
-        noteSkip('declaration schemas', decls.lookup);
-    }
-    // One ⚠ per distinct reason, naming every check it cost.
-    for (const { lookup, labels } of skipReasons.values()) {
-        const what = labels.length === 1 ? labels[0] : `${labels.length} checks (${labels.join(', ')})`;
-        console.log(`⚠ ${describeKbLookup(lookup, what)}`);
-    }
+    const checks = [
+        {
+            label: 'render-intent fields',
+            run: () => {
+                const render = loadAllowedRenderKeys(packDir);
+                if (!render.keys)
+                    return { kind: 'not-run', lookup: render.lookup };
+                const findings = withLines(yamlDocs().flatMap(([p, doc]) => findRenderKeyViolations(doc, p, render.keys, render.nested)));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'render-intent field error',
+                        lines: findings.map(describeRenderFinding),
+                        hint: 'fix these before deploying — the platform rejects them at load, and before that they rendered as nothing',
+                    }
+                    : { kind: 'passed', line: 'render intents use only fields the platform renders' };
+            },
+        },
+        {
+            // Primitive `args:` keys, same source and same contract. Cannot see inside a
+            // `use:` template body (expansion is the platform's job); `--remote` covers that.
+            label: 'primitive arguments',
+            run: () => {
+                const args = loadPrimitiveArgSpecs(packDir);
+                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
+                    ? {
+                        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' };
+            },
+        },
+        {
+            // Expression builtins — the function set is CLOSED and generated from the
+            // runtime, so an invented `$fn(` is checkable here and nowhere else offline.
+            label: 'expression functions',
+            run: () => {
+                const builtins = loadBuiltinNames(packDir);
+                if (!builtins.names)
+                    return { kind: 'not-run', lookup: builtins.lookup };
+                const findings = withLines(yamlDocs().flatMap(([p, doc]) => findBuiltinViolations(doc, p, builtins.names)));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'unknown expression function',
+                        lines: findings.map(describeBuiltinFinding),
+                        hint: 'fix these before deploying — the evaluator cannot resolve them, and it fails mid-conversation',
+                    }
+                    : { kind: 'passed', line: 'every $function() in an expression exists' };
+            },
+        },
+        {
+            // `use:` templates. A pack's OWN templates shadow the platform's, so they are
+            // named here and skipped — this check has no schema for them.
+            label: '`use:` templates',
+            run: () => {
+                const templates = loadTemplateSpecs(packDir);
+                if (!templates.specs)
+                    return { kind: 'not-run', lookup: templates.lookup };
+                // A pack template is `templates/<name>.template.yaml` — the `.template`
+                // segment is part of the convention the expander scans for, NOT part of the
+                // name a `use:` writes. Capturing it would leave every pack that shadows a
+                // platform template (kaiian shadows `field_prompt_render`) reported as using
+                // one that does not exist.
+                const packTemplates = new Set(Object.keys(files)
+                    .map(p => /^templates\/(.+)\.template\.ya?ml$/i.exec(p.replace(/\\/g, '/'))?.[1])
+                    .filter((n) => !!n));
+                const findings = yamlDocs().flatMap(([p, doc]) => findTemplateViolations(doc, p, templates.specs, packTemplates));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'template error',
+                        lines: findings.map(describeTemplateFinding),
+                        hint: 'fix these before deploying — a template param that does not exist arrives as undefined, and renders as a blank',
+                    }
+                    : { kind: 'passed', line: '`use:` templates and their params exist' };
+            },
+        },
+        {
+            // Reserved XRM entity keys — a boot error, which means the pack deploys clean
+            // and then fails to load on the first inbound message.
+            label: 'reserved entity keys',
+            run: () => {
+                const system = loadSystemEntities(packDir);
+                if (!system.entities)
+                    return { kind: 'not-run', lookup: system.lookup };
+                const findings = yamlDocs()
+                    .filter(([p]) => /(^|[/\\])xrm\.ya?ml$/i.test(p))
+                    .flatMap(([p, doc]) => findEntityViolations(doc, p, system.entities, system.rules));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'reserved-entity error',
+                        lines: findings.map(describeEntityFinding),
+                        hint: 'fix these before deploying — these fail at BOOT, after a deploy that reported success',
+                    }
+                    // Name the narrower promise when the catalog-level rules are absent (a KB
+                    // pulled before they were published) — a ✓ that reads wider than what ran is
+                    // the failure this file's skip contract exists to prevent, and it is why
+                    // `passed` carries its own line instead of the printer inventing one.
+                    : {
+                        kind: 'passed',
+                        line: system.rules
+                            ? 'no entity collides with a reserved platform key, and no extension overrides a platform-owned one'
+                            : 'no entity collides with a reserved platform key (re-pull for the `contact`/extension-override rules)',
+                    };
+            },
+        },
+        {
+            // The declaration files themselves, against the published JSON Schemas.
+            // Deliberately narrow (see declaration-check.ts) — it walks away from anything
+            // it cannot read rather than guessing.
+            label: 'declaration schemas',
+            run: () => {
+                const decls = loadDeclarationSpecs(packDir);
+                if (!decls.specs)
+                    return { kind: 'not-run', lookup: decls.lookup };
+                const findings = yamlDocs().flatMap(([p, doc]) => {
+                    const base = p.replace(/\\/g, '/').split('/').pop() ?? p;
+                    const spec = decls.specs.get(base);
+                    // Only a file at the PACK ROOT is a declaration — `flows/tools/xrm.yaml`
+                    // would be a flow that happens to share a name.
+                    if (!spec || p.replace(/\\/g, '/').includes('/'))
+                        return [];
+                    return findDeclarationViolations(doc, spec).map(f => ({ ...f, file: p }));
+                });
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'declaration error',
+                        lines: findings.map(describeDeclarationFinding),
+                        hint: 'fix these before deploying — a declaration file is parsed strictly, and an unknown key is rejected',
+                    }
+                    // Deliberately narrow wording. Most of `xrm.yaml`'s field shapes are a Zod
+                    // union, which renders as `anyOf` and which this check walks away from by
+                    // design — so "matches its schema" would be a promise it does not keep, and
+                    // an over-claimed ✓ is how an author stops reading `--remote` output.
+                    : { kind: 'passed', line: 'declaration files carry no unknown or missing keys (unions are left to --remote)' };
+            },
+        },
+    ];
+    const skipped = reportChecks(checks, {
+        log: (l) => console.log(l),
+        err: (l) => console.error(l),
+        die,
+    });
     // `--require-kb` is for CI, where a skip nobody reads is worse than a red build.
     if (skipped.length && flags['require-kb'] === true) {
         die(`--require-kb: ${skipped.length} check${skipped.length === 1 ? '' : 's'} could not run (${skipped.join(', ')})`);
@@ -1553,25 +1557,11 @@ function printDeploySuccess(id, version, t, r, listing, problems = 0) {
         : `✓ Deployed ${id}@${version} and installed onto ${targetLabel(t)}`);
     if (r?.warning)
         console.log(`  ⚠ ${r.warning}`);
-    const s = r?.summary;
-    if (s) {
-        const parts = [];
-        if (s.records != null)
-            parts.push(`${s.records} record(s) created`);
-        if (s.updated)
-            parts.push(`${s.updated} updated`);
-        if (s.images)
-            parts.push(`${s.images} image(s) generated`);
-        if (s.rules)
-            parts.push(`${s.rules} availability rule(s)`);
-        // A count of rows that threw. The seed keeps going past a bad row now, so a
-        // partial seed is a real outcome and has to be said out loud — the alternative
-        // reads as a complete one with fewer records than the author wrote.
-        if (s.failed)
-            parts.push(`${s.failed} row(s) FAILED`);
-        if (parts.length)
-            console.log(`  Seeded: ${parts.join(', ')}`);
-    }
+    // This read `r.summary.records` / `.rules` / `.failed` and had been DEAD: the deploy route's
+    // `summary` is a run-log STRING (`"clinic v1.2.0 — {…}"`), so every field was undefined and the
+    // block printed nothing. The counts live on `r.seeded`, keyed by seed kind, and `printSeedCounts`
+    // already renders them — filtering zeros, which is what makes a partial seed legible.
+    printSeedCounts(r?.seeded);
     // A redeploy rebuilds the pack's tools, and suspended flow runs live with them.
     // Say so: otherwise the next tap on a card rendered before the deploy comes back
     // stale and reads like a flow bug.
@@ -1622,7 +1612,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}`);
@@ -4980,372 +4970,372 @@ async function cmdUsage(flags) {
     console.log('\nThis is MODEL spend. WhatsApp/Meta message billing is operator-only — not reachable by an API token.');
 }
 function help() {
-    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
-
-  octwin --version                                      # print the CLI version (+ any upgrade notice)
-  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
-  octwin validate [--dir .] [--remote] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
-  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
-  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
-  octwin projects [--archived] [--json]                  # the --project slugs this token can name
-  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
-  octwin status  [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
-  octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
-  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
-  octwin work    [recordId] [--queues] [--unrouted] [--json]  # inspect the work inbox (worked records) + timelines
-                 #   --queues: per-queue open counts + an UNROUTED warning · --unrouted: only the items in no queue
-  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
-  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
-  octwin media   generate "<prompt>" [--out <file.png>] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
-  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
-  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
-  octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
-  octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
-  octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
-  octwin automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
-  octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
-  octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
-  octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
-  octwin performance [--detail] [--json]                 # the project's business indicators (value/conversion/duration)
-  octwin usage   [--json]                                # model calls, tokens and cost (project if pinned, else workspace)
-  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
-  octwin test    [--dir .]                               # = validate --remote (the full platform check)
-  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
-  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
-
-Writes — exercise the state your pack creates (each needs the matching :write scope):
-  octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
-  octwin records tasks | task complete <taskId> [--outcome done|cancelled]
-  octwin work    assign <id> --to user:<uuid>|none | note <id> "…" | stage <id> --to <stage>
-  octwin work    decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
-  octwin orders  transition <ref> --to <status> | refund <ref> --force
-  octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
-  octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
-  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
-  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
-  octwin integrations test <key>                         # a LIVE call to the connection's health: operation
-  octwin integrations retry|cancel|send-now <deliveryId>
-  (octwin integrations preflight <key> needs only integrations:read — it makes no call)
-
-Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
-\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
-button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
-Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
-octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
-Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
+    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
+
+  octwin --version                                      # print the CLI version (+ any upgrade notice)
+  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+  octwin validate [--dir .] [--remote] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
+  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
+  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
+  octwin projects [--archived] [--json]                  # the --project slugs this token can name
+  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
+  octwin status  [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
+  octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
+  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
+  octwin work    [recordId] [--queues] [--unrouted] [--json]  # inspect the work inbox (worked records) + timelines
+                 #   --queues: per-queue open counts + an UNROUTED warning · --unrouted: only the items in no queue
+  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
+  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
+  octwin media   generate "<prompt>" [--out <file.png>] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
+  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
+  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
+  octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
+  octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
+  octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
+  octwin automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
+  octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
+  octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
+  octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
+  octwin performance [--detail] [--json]                 # the project's business indicators (value/conversion/duration)
+  octwin usage   [--json]                                # model calls, tokens and cost (project if pinned, else workspace)
+  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
+  octwin test    [--dir .]                               # = validate --remote (the full platform check)
+  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
+  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
+
+Writes — exercise the state your pack creates (each needs the matching :write scope):
+  octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
+  octwin records tasks | task complete <taskId> [--outcome done|cancelled]
+  octwin work    assign <id> --to user:<uuid>|none | note <id> "…" | stage <id> --to <stage>
+  octwin work    decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
+  octwin orders  transition <ref> --to <status> | refund <ref> --force
+  octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
+  octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
+  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
+  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
+  octwin integrations test <key>                         # a LIVE call to the connection's health: operation
+  octwin integrations retry|cancel|send-now <deliveryId>
+  (octwin integrations preflight <key> needs only integrations:read — it makes no call)
+
+Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
+\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
+button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
+Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
+octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
+Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
 Per-command usage: octwin <command> --help`);
 }
 /** Per-subcommand usage — printed for `octwin <cmd> --help|-h` BEFORE any
  *  network/auth work (a --help that 401s is worse than no help at all). */
 const COMMAND_HELP = {
-    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   Scaffold a pure-YAML starter pack into <dir>.`,
-    validate: `octwin validate [--dir .] [--remote] [--require-kb] [--strict-primitives]
-  Offline structural check, plus two checks driven by the pulled capability
-  reference (render-intent fields, primitive arguments). Those two SKIP when the
-  reference is missing — the run says so, and --require-kb turns the skip into a
-  failure for CI. --remote additionally runs the platform's FULL manifest +
-  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.
-  --strict-primitives (with --remote) additionally type-checks LITERAL args:
-  values against each primitive's declared input schema; expression strings
+    validate: `octwin validate [--dir .] [--remote] [--require-kb] [--strict-primitives]
+  Offline structural check, plus two checks driven by the pulled capability
+  reference (render-intent fields, primitive arguments). Those two SKIP when the
+  reference is missing — the run says so, and --require-kb turns the skip into a
+  failure for CI. --remote additionally runs the platform's FULL manifest +
+  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.
+  --strict-primitives (with --remote) additionally type-checks LITERAL args:
+  values against each primitive's declared input schema; expression strings
   ('$found.id', '{$t(…)}') are always exempt.`,
-    login: `octwin login --url <platformUrl> --token oct_…
-  Save a deploy token (console → Settings → API tokens) for that platform url,
-  make that url the DEFAULT deploy target for every later command, and echo the
+    login: `octwin login --url <platformUrl> --token oct_…
+  Save a deploy token (console → Settings → API tokens) for that platform url,
+  make that url the DEFAULT deploy target for every later command, and echo the
   workspace + project pin + scopes the token reaches.`,
-    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
+    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
-    projects: `octwin projects [--archived] [--json]
-  List the workspace's projects — the slugs every --project flag takes, with the
-  plan's project cap. --archived includes archived ones. A pack:deploy token
-  reaches this (it names a project in every other command).
-
-octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
-  Create a project. The URL slug is derived from the name unless --slug pins one.
-  --pack installs an ALREADY-published pack; the usual next step is instead
-  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
-
-octwin projects rm <slug> [--yes]
-  HARD delete — the project and everything cascading from it (conversations,
-  contacts, records, installs). No undo, and not the same as archiving.
-  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
-  default. Together these make a disposable end-to-end environment:
-    octwin projects create "Scratch" && octwin deploy --project scratch --seed
-    octwin chat "hi" --project scratch
-    octwin projects rm scratch --yes
+    projects: `octwin projects [--archived] [--json]
+  List the workspace's projects — the slugs every --project flag takes, with the
+  plan's project cap. --archived includes archived ones. A pack:deploy token
+  reaches this (it names a project in every other command).
+
+octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
+  Create a project. The URL slug is derived from the name unless --slug pins one.
+  --pack installs an ALREADY-published pack; the usual next step is instead
+  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
+
+octwin projects rm <slug> [--yes]
+  HARD delete — the project and everything cascading from it (conversations,
+  contacts, records, installs). No undo, and not the same as archiving.
+  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
+  default. Together these make a disposable end-to-end environment:
+    octwin projects create "Scratch" && octwin deploy --project scratch --seed
+    octwin chat "hi" --project scratch
+    octwin projects rm scratch --yes
   Both verbs need the \`projects:write\` scope — a pack:deploy token does NOT confer it.`,
-    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-                [--request-listing | --withdraw-listing]
-  Upload the pack bundle, validate server-side, install onto the project.
-  --seed additionally applies the pack's demo seed (streams progress).
-
-  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
-  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
-
-  --request-listing    ask an operator to review this pack for the public marketplace
-                       (the pre-signup storefront at /packs). Requires 'public: true'
-                       under 'listing:' in manifest.yaml — the manifest states that the
-                       pack is a product, the flag is you choosing to ask.
-  --withdraw-listing   retract the request, including an approved listing.
-
-  An approval covers the CONTENT it was made against, so a later deploy that changes the
+    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+                [--request-listing | --withdraw-listing]
+  Upload the pack bundle, validate server-side, install onto the project.
+  --seed additionally applies the pack's demo seed (streams progress).
+
+  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
+  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
+
+  --request-listing    ask an operator to review this pack for the public marketplace
+                       (the pre-signup storefront at /packs). Requires 'public: true'
+                       under 'listing:' in manifest.yaml — the manifest states that the
+                       pack is a product, the flag is you choosing to ask.
+  --withdraw-listing   retract the request, including an approved listing.
+
+  An approval covers the CONTENT it was made against, so a later deploy that changes the
   pack returns it to the review queue on its own — no flag needed, and the CLI says so.`,
-    seed: `octwin seed [--pack <packId>]
-  Apply the pack's demo/reference data to the project it is installed on, without
-  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
-  and the demo operator topology. Reports what each kind produced.
-  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
-  than regenerated, so a second pass costs nothing. --pack is only needed when a
+    seed: `octwin seed [--pack <packId>]
+  Apply the pack's demo/reference data to the project it is installed on, without
+  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
+  and the demo operator topology. Reports what each kind produced.
+  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
+  than regenerated, so a second pass costs nothing. --pack is only needed when a
   project somehow runs more than one.`,
-    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
-  Show installed vs live version + the flow list for this pack.
-  The pack id is read from manifest.yaml and QUALIFIED with your workspace slug
-  (a manifest declares a bare name; the owner is attached when you publish). Pass
-  <packId> explicitly to skip that lookup — \`octwin agents\` and \`octwin projects\`
+    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
+  Show installed vs live version + the flow list for this pack.
+  The pack id is read from manifest.yaml and QUALIFIED with your workspace slug
+  (a manifest declares a bare name; the owner is attached when you publish). Pass
+  <packId> explicitly to skip that lookup — \`octwin agents\` and \`octwin projects\`
   both print the qualified form.`,
-    records: `octwin records [entity] [id] [--limit 50] [--offset n]
-  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
-  tickets, anything routed to a queue) read best through \`octwin work\`.
-
-  WRITES (need \`records:write\`; every one is re-checked by RBAC on the record):
-    octwin records create <entity> --set field=value [--set …] [--stage s] [--contact <id>]
-    octwin records patch  <recordId> --entity <entity> --set field=value
-    octwin records stage  <recordId> --to <stage> [--note "..."]
-    octwin records note   <recordId> "the note text"
-    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
-    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
-
-  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
-  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
-  \`patch\` needs --entity even though it has an id: the route resolves the field
-  validator from it. A leading \`create/patch/stage/note/tasks/task\` is read as a
+    records: `octwin records [entity] [id] [--limit 50] [--offset n]
+  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
+  tickets, anything routed to a queue) read best through \`octwin work\`.
+
+  WRITES (need \`records:write\`; every one is re-checked by RBAC on the record):
+    octwin records create <entity> --set field=value [--set …] [--stage s] [--contact <id>]
+    octwin records patch  <recordId> --entity <entity> --set field=value
+    octwin records stage  <recordId> --to <stage> [--note "..."]
+    octwin records note   <recordId> "the note text"
+    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
+    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
+
+  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
+  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
+  \`patch\` needs --entity even though it has an id: the route resolves the field
+  validator from it. A leading \`create/patch/stage/note/tasks/task\` is read as a
   VERB — to list an entity actually named one of those, use \`--entity <name>\`.`,
-    work: `octwin work [recordId] [--queues] [--unrouted] [--limit 50] [--offset n] [--json]
-  Inspect the work inbox — every entity the pack declares worked (cases, orders
-  needing review, applications, …): the inbox, one item + its timeline
-  (+ applicable actions), or --queues for queue keys + open counts.
-
-  WRITES (need \`work:write\`; \`stage\` needs \`records:write\`):
-    octwin work assign <recordId> --to user:<uuid>|team:<uuid>|none
-    octwin work note   <recordId> "the note text"
-    octwin work stage  <recordId> --to <stage> [--note "..."]
-    octwin work decide <recordId> --action <action> [--param k=v] [--note "..."] [--dry-run]
-
-  \`decide\` applies one of the entity's declared operator actions — \`octwin work <id>\`
-  lists them with their params. --dry-run previews the customer-facing copy and the
-  resulting stage WITHOUT committing (that route needs only \`work:read\`).
+    work: `octwin work [recordId] [--queues] [--unrouted] [--limit 50] [--offset n] [--json]
+  Inspect the work inbox — every entity the pack declares worked (cases, orders
+  needing review, applications, …): the inbox, one item + its timeline
+  (+ applicable actions), or --queues for queue keys + open counts.
+
+  WRITES (need \`work:write\`; \`stage\` needs \`records:write\`):
+    octwin work assign <recordId> --to user:<uuid>|team:<uuid>|none
+    octwin work note   <recordId> "the note text"
+    octwin work stage  <recordId> --to <stage> [--note "..."]
+    octwin work decide <recordId> --action <action> [--param k=v] [--note "..."] [--dry-run]
+
+  \`decide\` applies one of the entity's declared operator actions — \`octwin work <id>\`
+  lists them with their params. --dry-run previews the customer-facing copy and the
+  resulting stage WITHOUT committing (that route needs only \`work:read\`).
   \`stage\` is the XRM records verb (one transition spelling platform-wide).`,
-    logs: `octwin logs [conversationId] [--as <handle>] [--json]
-  No id = recent conversations (handle, status, last activity; --as filters).
-  With id = the full event timeline including what each turn rendered.
+    logs: `octwin logs [conversationId] [--as <handle>] [--json]
+  No id = recent conversations (handle, status, last activity; --as filters).
+  With id = the full event timeline including what each turn rendered.
   --json = raw events (verbatim payloads).`,
-    pull: `octwin pull <packId> [--dir <out>] [--version <v>] [--force]
-  Write a DEPLOYED pack's source back to disk — the inverse of deploy.
-  A pack pushed with 'octwin deploy' lives on the platform as an artifact the
-  runtime serves but nothing hands back, so its only source copy is the machine
-  that pushed it. Pull it, fix it, redeploy it.
-  Defaults to the version installed on the target project; --version overrides.
-  --dir defaults to ./<packId>; a non-empty dir needs --force.
-  The pulled dir redeploys where it came from — the target is your saved login.
+    pull: `octwin pull <packId> [--dir <out>] [--version <v>] [--force]
+  Write a DEPLOYED pack's source back to disk — the inverse of deploy.
+  A pack pushed with 'octwin deploy' lives on the platform as an artifact the
+  runtime serves but nothing hands back, so its only source copy is the machine
+  that pushed it. Pull it, fix it, redeploy it.
+  Defaults to the version installed on the target project; --version overrides.
+  --dir defaults to ./<packId>; a non-empty dir needs --force.
+  The pulled dir redeploys where it came from — the target is your saved login.
   You may pull a pack your tenant OWNS (deployed); an operator token pulls any.`,
-    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
-       octwin chat --script <file> [--as <handle>] [--json]
-  Drive ONE turn through the dev web channel and print every render with its
-  tap ids. Same --as handle = same conversation (multi-turn works).
-  --tap presses a rendered button/list row instead of sending text.
-  --media uploads a local file (or a media id from 'media generate --json') as
-  an image/document/audio inbound — any "message" rides as its caption; feeds a
-  running media-collect flow (e.g. activate-app).
-  --json dumps the raw SSE envelopes for the turn.
-
-  --script drives a WHOLE conversation from a file, ONE TURN PER LINE, in one
-  process over one connection — waiting for each turn to settle before sending
-  the next. Use this for any multi-step flow: chaining shell invocations races
-  the agent loop, because a turn ends on a quiet gap that can arrive while the
-  server is still working (the symptom is placeholder-filled fields or a second
-  workflow run). Blank lines and # comments are skipped:
-
-    # book an appointment end to end
-    احجز موعد
-    tap:t:invoke:book-appointment:doctor_id=D1
-    media:./licence.jpg | here is my licence
+    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
+       octwin chat --script <file> [--as <handle>] [--json]
+  Drive ONE turn through the dev web channel and print every render with its
+  tap ids. Same --as handle = same conversation (multi-turn works).
+  --tap presses a rendered button/list row instead of sending text.
+  --media uploads a local file (or a media id from 'media generate --json') as
+  an image/document/audio inbound — any "message" rides as its caption; feeds a
+  running media-collect flow (e.g. activate-app).
+  --json dumps the raw SSE envelopes for the turn.
+
+  --script drives a WHOLE conversation from a file, ONE TURN PER LINE, in one
+  process over one connection — waiting for each turn to settle before sending
+  the next. Use this for any multi-step flow: chaining shell invocations races
+  the agent loop, because a turn ends on a quiet gap that can arrive while the
+  server is still working (the symptom is placeholder-filled fields or a second
+  workflow run). Blank lines and # comments are skipped:
+
+    # book an appointment end to end
+    احجز موعد
+    tap:t:invoke:book-appointment:doctor_id=D1
+    media:./licence.jpg | here is my licence
     tap:t:resume:book-appointment:run_id=R1;_ctl_approved=true`,
-    media: `octwin media generate "<prompt>" [--out <file.png>] [--json]
-  AI-generate an image (needs a media:generate-scoped token), store it as a
-  public asset, and print its MEDIA- handle + serve URL. --out downloads the
-  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
+    media: `octwin media generate "<prompt>" [--out <file.png>] [--json]
+  AI-generate an image (needs a media:generate-scoped token), store it as a
+  public asset, and print its MEDIA- handle + serve URL. --out downloads the
+  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
   bytes }. Pair with 'octwin chat --media' to drive media flows.`,
-    agents: `octwin agents [packId::agentId] [--prompt] [--json]
-  No args = the roster with each agent's EFFECTIVE model and which layer set it.
-  With an agent = every governed setting (model / memory.last_messages /
-  working_memory) plus the layer that won — an operator PLATFORM default can
-  override what your manifest declares, and this is where you see that.
-  --prompt = the exact system prompt the LLM sees for this project (pack
-  instructions + platform protocol + any project overlay). Needs agents:read.
-  The agent ref is the compound \`<packId>::<agentId>\` key or the override-row UUID.
-
-  WRITES (need \`agents:write\`):
-    octwin agents set <ref> [--model <m>] [--enabled true|false] [--overlay "..."|none]
-                            [--enable-tool <toolId>] [--disable-tool <toolId>]
-
-  Only what you pass is changed. Tool flags read-modify-write \`config_json.tools\`
-  so a sibling decision isn't dropped; absent = enabled. A workspace that hides model
+    agents: `octwin agents [packId::agentId] [--prompt] [--json]
+  No args = the roster with each agent's EFFECTIVE model and which layer set it.
+  With an agent = every governed setting (model / memory.last_messages /
+  working_memory) plus the layer that won — an operator PLATFORM default can
+  override what your manifest declares, and this is where you see that.
+  --prompt = the exact system prompt the LLM sees for this project (pack
+  instructions + platform protocol + any project overlay). Needs agents:read.
+  The agent ref is the compound \`<packId>::<agentId>\` key or the override-row UUID.
+
+  WRITES (need \`agents:write\`):
+    octwin agents set <ref> [--model <m>] [--enabled true|false] [--overlay "..."|none]
+                            [--enable-tool <toolId>] [--disable-tool <toolId>]
+
+  Only what you pass is changed. Tool flags read-modify-write \`config_json.tools\`
+  so a sibling decision isn't dropped; absent = enabled. A workspace that hides model
   ids refuses --model with a 403 — the platform default governs there.`,
-    orders: `octwin orders [reference_id] [--status s] [--payment p] [--limit 50] [--json]
-  No args = the order list (#number, status/payment, total, contact). With a
-  reference_id = line items, the subtotal/tax/shipping/discount/total breakdown,
-  payment_ref, and the allowed status transitions. Needs orders:read + the
-  \`orders\` plan feature. Note: the forward payment lifecycle is webhook-owned,
-  so \`pending\` on a gateway-less workspace is expected, not a bug.
-
-  WRITES (need \`orders:write\`):
-    octwin orders transition <reference_id> --to <status>
-    octwin orders refund     <reference_id> [--reason "..."] [--mark-returned] --force
-
-  Refund is irreversible and moves money, hence --force. The route answers 200 even
-  when the GATEWAY refuses, so the CLI reads the gateway verdict and exits non-zero
-  on a refusal rather than reporting a refund that never happened. Only a payment in
+    orders: `octwin orders [reference_id] [--status s] [--payment p] [--limit 50] [--json]
+  No args = the order list (#number, status/payment, total, contact). With a
+  reference_id = line items, the subtotal/tax/shipping/discount/total breakdown,
+  payment_ref, and the allowed status transitions. Needs orders:read + the
+  \`orders\` plan feature. Note: the forward payment lifecycle is webhook-owned,
+  so \`pending\` on a gateway-less workspace is expected, not a bug.
+
+  WRITES (need \`orders:write\`):
+    octwin orders transition <reference_id> --to <status>
+    octwin orders refund     <reference_id> [--reason "..."] [--mark-returned] --force
+
+  Refund is irreversible and moves money, hence --force. The route answers 200 even
+  when the GATEWAY refuses, so the CLI reads the gateway verdict and exits non-zero
+  on a refusal rather than reporting a refund that never happened. Only a payment in
   \`captured\` state can be refunded; \`payment_status\` is never settable directly.`,
-    analytics: `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>] [--json]
-  No args = the entities that carry a \`pipeline:\` (a funnel needs stages).
-  With an entity = stage-by-stage conversion (default --funnel) over the last 30
-  days. --stage <id> lists the records CURRENTLY at a stage (a live snapshot, not
+    analytics: `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>] [--json]
+  No args = the entities that carry a \`pipeline:\` (a funnel needs stages).
+  With an entity = stage-by-stage conversion (default --funnel) over the last 30
+  days. --stage <id> lists the records CURRENTLY at a stage (a live snapshot, not
   range-filtered). Needs records:read + a \`view\` grant on \`record.<entity>\`.`,
-    catalog: `octwin catalog [--readiness] [--json]
-  The commerce \`product\` records + price, availability, stock (null = not
-  inventory-tracked) and the WhatsApp catalog binding. --readiness runs the Meta
-  Graph checklist (LIVE Graph calls; needs a bound access token). Needs
-  catalog:read + the \`catalog\` plan feature.
-
-  WRITES (need \`catalog:write\`):
-    octwin catalog availability <retailerId> --to "in stock"|"out of stock"|…
-    octwin catalog stock        <retailerId> [--set-on-hand <n>]
-
-  \`stock\` with no --set-on-hand READS it; \`null\` means the SKU is not
-  inventory-tracked (always sellable), which is different from 0. Lowering on_hand
-  below the units already reserved for open carts is refused. Creating/deleting
+    catalog: `octwin catalog [--readiness] [--json]
+  The commerce \`product\` records + price, availability, stock (null = not
+  inventory-tracked) and the WhatsApp catalog binding. --readiness runs the Meta
+  Graph checklist (LIVE Graph calls; needs a bound access token). Needs
+  catalog:read + the \`catalog\` plan feature.
+
+  WRITES (need \`catalog:write\`):
+    octwin catalog availability <retailerId> --to "in stock"|"out of stock"|…
+    octwin catalog stock        <retailerId> [--set-on-hand <n>]
+
+  \`stock\` with no --set-on-hand READS it; \`null\` means the SKU is not
+  inventory-tracked (always sellable), which is different from 0. Lowering on_hand
+  below the units already reserved for open carts is refused. Creating/deleting
   products and the Meta catalog binding/sync stay in the console.`,
-    scheduling: `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]
-  No args = the engine state (bookable resource types, upcoming slots, booked
-  seats). --slots <recordId> computes the slots for one bookable resource
-  (occupancy included; --days is clamped to 1-31 server-side) — the way to verify
-  the availability rules a \`deploy --seed\` created. Needs scheduling:read.
-
-  RULES (list needs scheduling:read; add/rm need scheduling:write):
-    octwin scheduling rules --resource <resourceRecordId>
-    octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00
-                               [--slot-minutes 30] [--capacity 1]
-    octwin scheduling rule rm  <ruleId>
-    octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra
-                                    [--start 09:00 --end 13:00]
-    octwin scheduling exception rm  <exceptionId>
-
-  --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
+    scheduling: `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]
+  No args = the engine state (bookable resource types, upcoming slots, booked
+  seats). --slots <recordId> computes the slots for one bookable resource
+  (occupancy included; --days is clamped to 1-31 server-side) — the way to verify
+  the availability rules a \`deploy --seed\` created. Needs scheduling:read.
+
+  RULES (list needs scheduling:read; add/rm need scheduling:write):
+    octwin scheduling rules --resource <resourceRecordId>
+    octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00
+                               [--slot-minutes 30] [--capacity 1]
+    octwin scheduling rule rm  <ruleId>
+    octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra
+                                    [--start 09:00 --end 13:00]
+    octwin scheduling exception rm  <exceptionId>
+
+  --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
   \`--slots\` is how you check what a rule actually produces.`,
-    automation: `octwin automation [campaigns] [--limit n] [--offset n] [--json]
-  No args = every job the pack's automation declaration produced, with its status,
-  interval and LAST RESULT (matched / acted / errors), under a health line whose
-  counts come from SQL rather than from filtering the page — the job list is capped
-  server-side, so a client-side count would depend on the cap. Needs automation:read.
-
-  Jobs are DERIVED from declarations. There is no \`create\`: no automation block in
-  the pack means no jobs, and \`octwin deploy\` is what installs them.
-
-  WRITES (automation:write):
-    octwin automation run <jobId>          # run once, now — prints matched/acted/errors
-    octwin automation pause|resume <jobId>
-    octwin automation send <campaignId>    # enqueue a campaign; enqueued != delivered
-
-  <jobId> is the \`key\` the list shows (its uuid works too). The routes themselves
-  accept only a uuid — the CLI resolves the key for you, and names the keys that do
-  exist when it cannot. A 403 on a write can be an RBAC grant gap rather than a
+    automation: `octwin automation [campaigns] [--limit n] [--offset n] [--json]
+  No args = every job the pack's automation declaration produced, with its status,
+  interval and LAST RESULT (matched / acted / errors), under a health line whose
+  counts come from SQL rather than from filtering the page — the job list is capped
+  server-side, so a client-side count would depend on the cap. Needs automation:read.
+
+  Jobs are DERIVED from declarations. There is no \`create\`: no automation block in
+  the pack means no jobs, and \`octwin deploy\` is what installs them.
+
+  WRITES (automation:write):
+    octwin automation run <jobId>          # run once, now — prints matched/acted/errors
+    octwin automation pause|resume <jobId>
+    octwin automation send <campaignId>    # enqueue a campaign; enqueued != delivered
+
+  <jobId> is the \`key\` the list shows (its uuid works too). The routes themselves
+  accept only a uuid — the CLI resolves the key for you, and names the keys that do
+  exist when it cannot. A 403 on a write can be an RBAC grant gap rather than a
   missing scope: the action is re-checked against the job.`,
-    integrations: `octwin integrations [--json]
-  What the pack DECLARES beside what is actually CONFIGURED, in one view — because a
-  connection that is declared and never configured is the commonest reason an
-  integration silently never fires, and neither list alone can show it. Flags the
-  gap explicitly. Needs integrations:read.
-
-  DIAGNOSE ONE CONNECTION:
-    octwin integrations preflight <key>    # every check, with a fix hint. Makes NO
-                                           # outbound call — needs only integrations:read
-    octwin integrations test <key>         # a LIVE call to its health: operation
-                                           # (integrations:write). Exits 1 when it fails.
-
-  THE DELIVERY LOG:
-    octwin integrations deliveries [--status s] [--operation id] [--limit n]
-    octwin integrations deliveries <id>    # + the redacted request/response snapshots
-    octwin integrations retry|cancel|send-now <id>     # integrations:write
-    octwin integrations events             # INBOUND events (what arrived at your webhook)
-
-  retry/cancel answer 409 when the delivery is in the wrong state; the message
+    integrations: `octwin integrations [--json]
+  What the pack DECLARES beside what is actually CONFIGURED, in one view — because a
+  connection that is declared and never configured is the commonest reason an
+  integration silently never fires, and neither list alone can show it. Flags the
+  gap explicitly. Needs integrations:read.
+
+  DIAGNOSE ONE CONNECTION:
+    octwin integrations preflight <key>    # every check, with a fix hint. Makes NO
+                                           # outbound call — needs only integrations:read
+    octwin integrations test <key>         # a LIVE call to its health: operation
+                                           # (integrations:write). Exits 1 when it fails.
+
+  THE DELIVERY LOG:
+    octwin integrations deliveries [--status s] [--operation id] [--limit n]
+    octwin integrations deliveries <id>    # + the redacted request/response snapshots
+    octwin integrations retry|cancel|send-now <id>     # integrations:write
+    octwin integrations events             # INBOUND events (what arrived at your webhook)
+
+  retry/cancel answer 409 when the delivery is in the wrong state; the message
   carries the rule.`,
-    journeys: `octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]
-                  [--stage <stageId>] [--limit n] [--json]
-  No args = the journeys the pack declares. With an id, one of six views —
-  --funnel (default) stage-by-stage reach and drop-off · --overview entered vs
-  converted plus the biggest drop-off · --goals completions, contacts, value and
-  p50 time · --trends per-bucket activity · --cost tokens and dollars per goal ·
-  --definition what was DECLARED, unmeasured (the one view that works with no
-  traffic). Needs journeys:read.
-
-  --stage <stageId> lists the runs sitting at a stage right now (a live snapshot,
-  not the funnel's cumulative reached counts).
-
-  Same flag grammar as \`octwin analytics\` on purpose: a journey funnel and an
-  entity funnel are the same question about different subjects. Journeys carry RBAC
-  on top of the scope, so an empty answer can be a missing \`view\` grant rather
+    journeys: `octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]
+                  [--stage <stageId>] [--limit n] [--json]
+  No args = the journeys the pack declares. With an id, one of six views —
+  --funnel (default) stage-by-stage reach and drop-off · --overview entered vs
+  converted plus the biggest drop-off · --goals completions, contacts, value and
+  p50 time · --trends per-bucket activity · --cost tokens and dollars per goal ·
+  --definition what was DECLARED, unmeasured (the one view that works with no
+  traffic). Needs journeys:read.
+
+  --stage <stageId> lists the runs sitting at a stage right now (a live snapshot,
+  not the funnel's cumulative reached counts).
+
+  Same flag grammar as \`octwin analytics\` on purpose: a journey funnel and an
+  entity funnel are the same question about different subjects. Journeys carry RBAC
+  on top of the scope, so an empty answer can be a missing \`view\` grant rather
   than missing data — the output says which causes are possible.`,
-    performance: `octwin performance [--detail] [--json]
-  The project's business indicators — value produced, conversion, duration — each
-  with its delta against the previous window and a \`why\` naming the declaration it
-  came from. --detail adds the per-indicator breakdown.
-
-  Needs records:read, NOT a performance scope (there is none), so a read-only token
-  already reaches it. Indicators are DERIVED: a pack that declares no journey goal
+    performance: `octwin performance [--detail] [--json]
+  The project's business indicators — value produced, conversion, duration — each
+  with its delta against the previous window and a \`why\` naming the declaration it
+  came from. --detail adds the per-indicator breakdown.
+
+  Needs records:read, NOT a performance scope (there is none), so a read-only token
+  already reaches it. Indicators are DERIVED: a pack that declares no journey goal
   value and no pipelined entity produces none, which is a different thing from zero.`,
-    usage: `octwin usage [--json]
-  Model calls, tokens and cost for the resolved scope — project when one is pinned
-  or passed with --project, otherwise the whole workspace. Broken down by model,
-  kind, agent and channel.
-
-  Needs no particular scope: any valid token reaches it.
-
-  This is MODEL spend only. WhatsApp/Meta message billing is operator-only and
+    usage: `octwin usage [--json]
+  Model calls, tokens and cost for the resolved scope — project when one is pinned
+  or passed with --project, otherwise the whole workspace. Broken down by model,
+  kind, agent and channel.
+
+  Needs no particular scope: any valid token reaches it.
+
+  This is MODEL spend only. WhatsApp/Meta message billing is operator-only and
   deliberately outside the token scope registry — no API token can read it.`,
-    'platform-kb': `octwin platform-kb [pull] [--if-stale] [--check] [--dir .] [--url <url>] [--token <t>]
-  Pull the platform capability reference (markdown + JSON catalogs) into
-  .octwin/platform-kb/ for the octwin-pack authoring skill, plus three maps:
-  INDEX.md (the corpus) · SYMBOLS.md (every name -> its file; grep this) ·
-  OUTLINE.md (every heading with its line number).
-
-  NO TOKEN NEEDED — the reference is platform stdlib and is served anonymously,
-  and this command never sends one. --token is accepted and ignored, so an older
-  script that passes it keeps working.
-
-  --if-stale   poll the platform's content_hash first and skip the download when
-               nothing changed. Cheap enough to run at the start of every session.
-  --check      report only, write nothing. Exit 0 = current, 2 = stale or never
-               pulled, 1 = could not tell (offline / no reference served). For
+    'platform-kb': `octwin platform-kb [pull] [--if-stale] [--check] [--dir .] [--url <url>] [--token <t>]
+  Pull the platform capability reference (markdown + JSON catalogs) into
+  .octwin/platform-kb/ for the octwin-pack authoring skill, plus three maps:
+  INDEX.md (the corpus) · SYMBOLS.md (every name -> its file; grep this) ·
+  OUTLINE.md (every heading with its line number).
+
+  NO TOKEN NEEDED — the reference is platform stdlib and is served anonymously,
+  and this command never sends one. --token is accepted and ignored, so an older
+  script that passes it keeps working.
+
+  --if-stale   poll the platform's content_hash first and skip the download when
+               nothing changed. Cheap enough to run at the start of every session.
+  --check      report only, write nothing. Exit 0 = current, 2 = stale or never
+               pulled, 1 = could not tell (offline / no reference served). For
                scripts and agent loops that want to branch without parsing prose.`,
-    test: `octwin test [--dir .]
+    test: `octwin test [--dir .]
   Alias for \`octwin validate --remote\` — the full platform check.`,
-    memos: `octwin memos [--all] [--json]
-  Read what the platform has told you: a REPLY to a report you sent with
-  \`octwin feedback\`, or a NOTICE published to every author (a new capability,
-  a deprecation, a breaking change). Bodies are printed in full.
-  Reading marks them read, so the reminder stops. --all re-reads history and
-  acks nothing. --json to branch on \`severity\`
+    memos: `octwin memos [--all] [--json]
+  Read what the platform has told you: a REPLY to a report you sent with
+  \`octwin feedback\`, or a NOTICE published to every author (a new capability,
+  a deprecation, a breaking change). Bodies are printed in full.
+  Reading marks them read, so the reminder stops. --all re-reads history and
+  acks nothing. --json to branch on \`severity\`
   (info | action_required | breaking).`,
-    feedback: `octwin feedback [--dir .]
-  Submit this pack's FEEDBACK.md to the platform team.
-  The octwin-pack skill writes that file in its last step — findings grouped by
-  owner (A · CLI, B · Platform, C · Skill/KB). This delivers it instead of asking
-  you to paste it into a chat.
-  Attaches the pack id + version from manifest.yaml, this CLI's version, and the
-  content_hash of the capability reference in .octwin/platform-kb/ — triage needs
-  the last two to tell "the platform is wrong" from "that was already fixed" or
+    feedback: `octwin feedback [--dir .]
+  Submit this pack's FEEDBACK.md to the platform team.
+  The octwin-pack skill writes that file in its last step — findings grouped by
+  owner (A · CLI, B · Platform, C · Skill/KB). This delivers it instead of asking
+  you to paste it into a chat.
+  Attaches the pack id + version from manifest.yaml, this CLI's version, and the
+  content_hash of the capability reference in .octwin/platform-kb/ — triage needs
+  the last two to tell "the platform is wrong" from "that was already fixed" or
   "you were reading a stale reference". Needs the \`pack:deploy\` scope.`,
 };
 async function main() {