octwin-cli 0.7.3 → 0.8.1

package/dist/index.js

@@ -28,6 +28,11 @@
  *   octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion, any pipelined entity
  *   octwin catalog [--readiness]     # commerce products + stock + the WhatsApp catalog binding (catalog:read)
  *   octwin scheduling [--slots <resourceRecordId>]  # engine state / computed slots (scheduling:read)
+ *   octwin automation [campaigns]    # the jobs your declarations produced + health + last result (automation:read)
+ *   octwin integrations [deliveries|events|preflight|test …]  # declared vs configured, and the delivery log (integrations:read)
+ *   octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]  # declared journeys, measured (journeys:read)
+ *   octwin performance [--detail]    # the project's business indicators (records:read — there is no performance scope)
+ *   octwin usage                     # model calls, tokens and cost (any valid token; NOT Meta message billing)
  *   octwin platform-kb [pull] [--if-stale|--check] [--dir .]  # the platform capability reference (no token needed)
  *   octwin test    [--dir .]        # = validate --remote (the full platform check)
  *
@@ -216,6 +221,21 @@ const VERB_REQUIREMENTS = {
     // which does NOT confer this — that 403 is otherwise baffling.
     'projects create': { scope: 'projects:write' },
     'projects rm': { scope: 'projects:write' },
+    // Jobs are declaration-derived, so there is no `create` — only acting on one.
+    // `campaigns` is absent on purpose: it is a READ sharing the verb slot, and an
+    // entry here would print "needs automation:write" on a read failure.
+    'automation run': { scope: 'automation:write' },
+    'automation pause': { scope: 'automation:write' },
+    'automation resume': { scope: 'automation:write' },
+    'automation send': { scope: 'automation:write' },
+    // `preflight` is the odd one: it is a diagnosis, so the route gates it on
+    // `view`, not `act`. Naming the READ scope here is what stops a 403 on it
+    // sending the author to mint a write token they do not need.
+    'integrations preflight': { scope: 'integrations:read' },
+    'integrations test': { scope: 'integrations:write' },
+    'integrations retry': { scope: 'integrations:write' },
+    'integrations cancel': { scope: 'integrations:write' },
+    'integrations send-now': { scope: 'integrations:write' },
 };
 const COMMAND_REQUIREMENTS = {
     deploy: { scope: 'pack:deploy' },
@@ -250,6 +270,17 @@ const COMMAND_REQUIREMENTS = {
     // hint names the scope a NON-deploy token would be missing — a `pack:deploy`
     // holder never sees this line, because they never get the 403.
     projects: { scope: 'projects:read' },
+    automation: { scope: 'automation:read' },
+    integrations: { scope: 'integrations:read' },
+    journeys: { scope: 'journeys:read' },
+    // `records:read`, not a `performance:*` scope — there is none. The indicators are
+    // derived from record + journey data, and the route is gated accordingly, so the
+    // Read-only token preset already reaches this.
+    performance: { scope: 'records:read' },
+    // `usage` is deliberately absent: its route is `requireTenantAccess` only, so any
+    // valid token reaches it. Declaring a requirement would print "needs the X scope"
+    // on a failure whose real cause is an unreachable instance — the same reasoning as
+    // `platform-kb` above.
 };
 /** The command currently running — set once in `main()` so any failure printer can
  *  name the scope that command needs without threading it through every call.
@@ -556,11 +587,12 @@ function diffKbIndex(prev, next) {
 }
 /**
  * Fetch the platform's KB identity (`?meta=1`) — the cheap poll behind both the
- * drift nudge and `--if-stale`. Returns null on anything that is not a clean
+ * drift nudge and `--if-stale`. Returns not-ok on anything that is not a clean
  * answer; the caller decides whether that is worth a word.
  *
- * `notAuthorized` is reported separately because it is the one failure with a
- * fix the author can act on.
+ * There is no `notAuthorized` case any more. `kbEndpoint` is anonymous, so this
+ * poll cannot be refused for lack of a scope — which used to be its most common
+ * failure, and the reason the drift nudge below carried a whole branch of advice.
  */
 async function fetchKbMeta(t, timeoutMs = 2_000) {
     const ep = kbEndpoint(t);
@@ -571,12 +603,12 @@ async function fetchKbMeta(t, timeoutMs = 2_000) {
             // socket checked out of the pool, and this poll runs on the way to a possible `exitNow` —
             // a held socket at exit is a pending libuv handle.
             await res.arrayBuffer().catch(() => undefined);
-            return { ok: false, notAuthorized: res.status === 401 || res.status === 403 };
+            return { ok: false };
         }
         return { ok: true, meta: await res.json() };
     }
     catch {
-        return { ok: false, notAuthorized: false };
+        return { ok: false };
     }
 }
 /** Nudge (to stderr) when the platform's capability KB has changed since the last
@@ -597,24 +629,20 @@ async function kbStaleNotice(flags) {
         const local = readLocalKb(packDir);
         if (!local?.content_hash)
             return []; // never pulled → the skill already says to pull
-        const t = resolveTargetOrNull(flags);
-        if (!t)
+        // URL only, deliberately: the KB poll is anonymous, so requiring a token here would
+        // silence the nudge for exactly the authors who most need it. This used to call
+        // `resolveTargetOrNull` (url AND token) against the tenant-scoped route, which needs
+        // `pack:deploy` — so an author inspecting data with a narrow (`records:read`-only)
+        // token got NO drift signal at all, silently, and a stale reference is precisely what
+        // makes an author invent a primitive from memory. The branch that apologised for that
+        // is gone with the cause; every remaining failure (offline, timeout, a platform
+        // serving no reference) stays silent, because observing must not break a command.
+        const t = readTarget(flags);
+        if (!t.url)
             return [];
         const polled = await fetchKbMeta(t);
-        if (!polled.ok) {
-            // The tenant-scoped meta poll needs `pack:deploy`, but this nudge rides on every
-            // networked command — so an author inspecting data with a narrow (`records:read`-only)
-            // token got NO drift signal at all, silently, and a stale reference is exactly what
-            // makes an author invent a primitive from memory. Say so once; stay silent for every
-            // other failure (offline, timeout, a platform without the route).
-            if (polled.notAuthorized) {
-                return [
-                    '\nⓘ can\'t check whether the platform capability reference drifted — that token lacks `pack:deploy`.',
-                    '  Check it without a token: octwin platform-kb --check   (or refresh: octwin platform-kb --token oct_…)',
-                ];
-            }
+        if (!polled.ok)
             return [];
-        }
         const meta = polled.meta;
         if (meta.content_hash && meta.content_hash !== local.content_hash) {
             // Per-entry summary (now that the index carries per-entry hashes) — the
@@ -791,6 +819,11 @@ function commandTouchesPlatform(command, flags) {
         case 'analytics':
         case 'catalog':
         case 'scheduling':
+        case 'automation':
+        case 'integrations':
+        case 'journeys':
+        case 'performance':
+        case 'usage':
         case 'projects':
         case 'seed': return true;
         default: return false;
@@ -1171,20 +1204,32 @@ function resolveTargetOrNull(flags) {
 /**
  * Where to read the platform capability reference from, and how.
  *
- * The KB is tenant-independent platform stdlib, and the platform now serves it
- * anonymously at `/api/public/octwin-platform-kb` precisely so a COLD START does
- * not need a login: `.octwin/` is gitignored, so a fresh clone — or a fresh
- * Claude Code session — has no reference at all, and an authoring agent's first
- * useful question came after a credential round-trip it had no way to satisfy.
+ * ALWAYS the anonymous route. The KB is tenant-independent platform stdlib, and
+ * the platform serves the SAME bundle from all three of its views -- its own
+ * route file says so twice ("THREE views of the SAME `getPlatformKbBundle()`";
+ * "the payload is identical") and forbids tenant data ever entering the reader.
+ * So the authed route returns nothing extra, and asking for a credential to read
+ * it can only ever subtract.
  *
- * A token still WINS when one is available: the tenant-scoped route is the one
- * that has always existed, it works against platforms that predate the public
- * rung, and using it keeps the author's own instance the source of truth.
+ * It subtracted, measurably. This used to prefer the tenant-scoped route
+ * WHENEVER a token was saved, and that route is guarded by `pack:deploy` -- so a
+ * developer holding a token WITHOUT that scope got a 403 on a pull that would
+ * have succeeded with no token at all. Having logged in made the CLI strictly
+ * worse than not having logged in, on the very first command an author runs. No
+ * console preset could even reach `pack:deploy` before 2026-08-26, so that was
+ * the likeliest token a new developer held.
+ *
+ * The two arguments the old comment gave for preferring a token did not survive
+ * being checked: "keeps the author's own instance the source of truth" is
+ * vacuous (both routes are `t.url` -- the same instance), and "works against
+ * platforms that predate the public rung" is a backward-compatibility shim,
+ * which this codebase does not carry.
+ *
+ * `--token` is still ACCEPTED here, and ignored, so a scripted `platform-kb pull
+ * --token …` keeps working instead of turning into an unknown-flag error.
  */
 function kbEndpoint(t) {
-    return t.token
-        ? { url: `${t.url}/api/self/t/octwin-platform-kb`, headers: authHeaders(t), anonymous: false }
-        : { url: `${t.url}/api/public/octwin-platform-kb`, headers: {}, anonymous: true };
+    return { url: `${t.url}/api/public/octwin-platform-kb`, headers: {} };
 }
 /** The raw resolution both wrappers share — may return empty url/token. */
 function readTarget(flags) {
@@ -1464,13 +1509,13 @@ async function cmdSeed(flags) {
         const { terminal: final, stepErrors } = await readDeployProgress(res.body);
         if (!final || final.stage === 'error')
             die(`seed failed${final?.message ? `: ${final.message}` : ' (stream ended early)'}`);
-        console.log(`
+        console.log(`
 ✓ ${final.message ?? 'seed complete'}`);
         printSeedCounts(final.result?.seeded);
         if (stepErrors.length) {
             // A kind failed but the rest ran — the reconcile softens each step. Say which,
             // and exit non-zero so a scripted `seed && chat` doesn't read as clean.
-            console.error(`
+            console.error(`
 ⚠ ${stepErrors.length} step${stepErrors.length === 1 ? '' : 's'} failed — data may be incomplete:`);
             for (const e of stepErrors)
                 console.error(`   • ${e}`);
@@ -1720,9 +1765,7 @@ async function cmdPlatformKb(flags) {
         const local = readLocalKb(packDir);
         const polled = await fetchKbMeta(t, 10_000);
         if (!polled.ok) {
-            console.error(polled.notAuthorized
-                ? '✗ cannot check — the platform refused the token, and this instance serves no anonymous reference.'
-                : `✗ cannot check — ${url} did not answer.`);
+            console.error(`✗ cannot check — ${url} did not answer, or serves no capability reference.`);
             exitNow(1);
         }
         const remote = polled.meta.content_hash;
@@ -1751,7 +1794,7 @@ async function cmdPlatformKb(flags) {
             return;
         }
     }
-    console.log(`→ Pulling the platform capability reference from ${url}${ep.anonymous ? ' (anonymous — no token needed for the reference)' : ''} …`);
+    console.log(`→ Pulling the platform capability reference from ${url} (no token needed for the reference) …`);
     const res = await fetchOrDie(ep.url, { headers: ep.headers }, 'platform-kb pull');
     const text = await res.text();
     if (!res.ok) {
@@ -1919,11 +1962,21 @@ async function apiGet(endpoint, t) {
  * `content-type` + `authHeaders` block was inlined at each of the four original
  * write sites, and fifteen more copies is how one of them ends up subtly different.
  * A `204` (media delete) has no body to parse, hence the empty-text guard.
+ *
+ * `body: undefined` sends NO `content-type` either. The header used to be
+ * unconditional, so a genuinely body-less write announced `application/json` and
+ * then sent nothing — Fastify tried to parse the empty body and answered a bare
+ * `400 Bad Request` with no hint of the cause. Latent until 2026-08-27 because every
+ * caller until then passed an object; the first body-less POST (`automation run`)
+ * hit it immediately, and a caller having to know "pass `{}` or you get a 400" is
+ * exactly the per-site divergence this helper exists to prevent.
  */
 async function apiSend(method, endpoint, body, t) {
     const res = await fetchOrDie(endpoint, {
         method,
-        headers: { 'content-type': 'application/json', ...authHeaders(t) },
+        headers: body === undefined
+            ? authHeaders(t)
+            : { 'content-type': 'application/json', ...authHeaders(t) },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }),
     }, 'request');
     const text = await res.text();
@@ -3364,7 +3417,9 @@ async function cmdAgents(flags) {
         return;
     }
     if (!ref) {
-        const { status, json } = await apiGet(base, t);
+        // Template literal, not bare `base` — see the note in `cmdScheduling`: the route
+        // guard's extractor cannot read a bare identifier, so this URL was exempt.
+        const { status, json } = await apiGet(`${base}`, t);
         if (status !== 200)
             die(`could not read agents (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
         if (asJson) {
@@ -3998,7 +4053,9 @@ async function cmdScheduling(flags) {
     }
     if (!asJson)
         console.log(`→ Reading the scheduling engine state from ${targetLabel(t)} …`);
-    const { status, json } = await apiGet(base, t);
+    // A template literal, not the bare `base` — `cli-routes.test.ts` cannot read a
+    // bare identifier, so this URL was silently exempt from the route guard.
+    const { status, json } = await apiGet(`${base}`, t);
     if (status !== 200)
         die(`could not read scheduling (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     if (asJson) {
@@ -4016,290 +4073,1128 @@ async function cmdScheduling(flags) {
     console.log(`  upcoming slots: ${json?.upcoming_slots ?? 0}   booked seats: ${json?.booked_seats ?? 0}`);
     console.log('\nSlots for one resource:  octwin scheduling --slots <resourceRecordId>   (ids: octwin records <entity>)');
 }
+// ── automation: declaration-derived jobs + campaigns ─────────────────────────
+/**
+ * Verbs that mean "act on a job", not "an id".
+ *
+ * `pause` / `resume` rather than a literal `status active|paused`: the route body
+ * takes the status, but the RBAC layer it calls checks the ACTION
+ * (`assertCan(…, action: 'pause' | 'resume')`), and `VERB_REQUIREMENTS` is keyed
+ * per verb — so one verb per intent makes both the permission hint and the 403
+ * say the right thing.
+ */
+const AUTOMATION_VERBS = new Set(['run', 'pause', 'resume', 'campaigns', 'send']);
+/**
+ * Turn whatever the author typed into the UUID the route demands.
+ *
+ * (`UUID_RE` is the one already declared for `--media`, deliberately reused rather
+ * than a second copy of the same pattern.)
+ *
+ * The write routes take a UUID path param and reject anything else with a bare
+ * *"Malformed identifier in the URL — expected a UUID"* 400. But the thing an author
+ * has in front of them is the declaration KEY (`cart_recovery_nudge`) — that is what
+ * the list prints, and it is the name in their own YAML. Measured: passing the key
+ * 400s on all three write verbs.
+ *
+ * So the key is resolved here, against the list route, rather than documented as a
+ * gotcha. A UUID passes straight through, and an unknown key fails naming the keys
+ * that DO exist — which is the answer to the question the author is actually asking.
+ */
+async function resolveAutomationId(kind, typed, base, t) {
+    if (UUID_RE.test(typed))
+        return typed;
+    const { status, json } = await apiGet(`${base}/${kind}`, t);
+    if (status !== 200) {
+        die(`could not resolve '${typed}' — reading ${kind} failed (HTTP ${status})${errDetail(json)}`);
+    }
+    const rows = readPage(json).rows;
+    const hit = rows.find(r => r.key === typed || r.id === typed);
+    if (hit?.id)
+        return hit.id;
+    const keys = rows.map(r => r.key ?? r.id).filter(Boolean);
+    die(`no ${kind === 'jobs' ? 'job' : 'campaign'} '${typed}' in this project.`
+        + (keys.length ? ` Available: ${keys.join(', ')}` : ` This project declares none.`));
+}
+/** `pause`/`resume`/`run`/`send` — the writes behind `octwin automation`. */
+async function cmdAutomationWrite(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const verb = flags._[0];
+    const typed = flags._[1];
+    const asJson = flags.json === true;
+    if (!typed)
+        die(`usage: octwin automation ${verb} <${verb === 'send' ? 'campaignId' : 'jobId'}>   (ids: octwin automation${verb === 'send' ? ' campaigns' : ''})`);
+    const id = await resolveAutomationId(verb === 'send' ? 'campaigns' : 'jobs', typed, base, t);
+    if (verb === 'pause' || verb === 'resume') {
+        const { status, json } = await apiSend('PATCH', `${base}/jobs/${encodeURIComponent(id)}/status`, { status: verb === 'pause' ? 'paused' : 'active' }, t);
+        if (status === 404)
+            die(`job '${typed}' not found in ${targetLabel(t)} (ids: octwin automation)`);
+        // RBAC re-checks the ACTION on the job, so a 403 here can be a grant gap
+        // rather than a missing scope — same caveat as a record write.
+        if (status !== 200)
+            writeFail(`${verb} job '${typed}'`, status, json, url, true);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const j = json?.job ?? {};
+        console.log(`✓ job '${j.key ?? typed}' is now ${j.status}`);
+        if (j.next_run_at)
+            console.log(`  next run: ${j.next_run_at}`);
+        return;
+    }
+    if (verb === 'run') {
+        if (!asJson)
+            console.log(`→ Running job '${typed}' in ${targetLabel(t)} …`);
+        const { status, json } = await apiSend('POST', `${base}/jobs/${encodeURIComponent(id)}/run`, undefined, t);
+        if (status === 404)
+            die(`job '${typed}' not found in ${targetLabel(t)} (ids: octwin automation)`);
+        if (status !== 200)
+            writeFail(`run job '${typed}'`, status, json, url, true);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const r = json?.result ?? {};
+        console.log(`✓ ran '${typed}': matched ${r.matched ?? 0}, acted ${r.acted ?? 0}, errors ${r.errors ?? 0}`);
+        // `acted < matched` is the route's own definition of a PARTIAL run, so say so
+        // rather than leaving three numbers for the author to compare.
+        if ((r.errors ?? 0) > 0)
+            console.log('  ⚠ some rows errored — see the job\'s last_result in `octwin automation`');
+        else if ((r.acted ?? 0) < (r.matched ?? 0))
+            console.log('  partial: matched rows were skipped (cooldown, or already acted on)');
+        return;
+    }
+    // send — one campaign
+    if (!asJson)
+        console.log(`→ Sending campaign '${typed}' in ${targetLabel(t)} …`);
+    const { status, json } = await apiSend('POST', `${base}/campaigns/${encodeURIComponent(id)}/send`, undefined, t);
+    if (status === 404)
+        die(`campaign '${typed}' not found in ${targetLabel(t)} (ids: octwin automation campaigns)`);
+    if (status !== 200)
+        writeFail(`send campaign '${typed}'`, status, json, url, true);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    const r = json?.result ?? {};
+    console.log(`✓ campaign '${typed}': matched ${r.matched ?? 0}, enqueued ${r.enqueued ?? 0}`);
+    if ((r.enqueued ?? 0) < (r.matched ?? 0))
+        console.log('  partial: some matched contacts were not enqueued (cooldown, or no reachable channel)');
+    console.log('  enqueued ≠ delivered — watch the sends land with `octwin logs`');
+}
+/**
+ * `octwin automation [--campaigns] [--json]` — the jobs a pack's declarations
+ * produced, with their last result, plus the health counts.
+ *
+ * Needs `automation:read`. The job list is CAPPED server-side and the counts are
+ * computed in SQL, so the header numbers come from `/health` rather than from
+ * filtering the page — past the cap a client-side count would depend on the cap
+ * instead of the data.
+ */
+async function cmdAutomation(flags) {
+    if (typeof flags._[0] === 'string' && AUTOMATION_VERBS.has(flags._[0])) {
+        // `campaigns` is a READ that shares the verb slot with the writes.
+        if (flags._[0] !== 'campaigns')
+            return cmdAutomationWrite(flags);
+    }
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const asJson = flags.json === true;
+    const campaigns = flags._[0] === 'campaigns' || flags.campaigns === true;
+    if (campaigns) {
+        if (!asJson)
+            console.log(`→ Reading campaigns from ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}/campaigns?${pagingQs(flags)}`, t);
+        if (status !== 200)
+            die(`could not read campaigns (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const page = readPage(json);
+        console.log(`Campaigns in ${targetLabel(t)}: ${page.total ?? page.rows.length}`);
+        if (page.rows.length === 0)
+            console.log('  (none — a campaign comes from a `campaigns:` block in the pack\'s automation declaration)');
+        for (const c of page.rows) {
+            const label = pickLabel(c.label) ?? c.key ?? c.id;
+            console.log(`  ${String(label).padEnd(28)} ${String(c.audience_size ?? c.matched ?? '—').padStart(6)} contact(s)  ${c.key ?? c.id}`);
+        }
+        const more = morePageHint(page, 'octwin automation campaigns');
+        if (more)
+            console.log(more);
+        console.log('\nSend one:  octwin automation send <campaignId>   (needs automation:write)');
+        return;
+    }
+    if (!asJson)
+        console.log(`→ Reading automation jobs from ${targetLabel(t)} …`);
+    const [jobs, health] = await Promise.all([
+        apiGet(`${base}/jobs`, t),
+        apiGet(`${base}/health`, t),
+    ]);
+    if (jobs.status !== 200)
+        die(`could not read automation jobs (HTTP ${jobs.status})${errDetail(jobs.json)}${authFailureDetail(jobs.status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify({ jobs: jobs.json, health: health.json }, null, 2));
+        return;
+    }
+    const page = readPage(jobs.json);
+    const h = health.status === 200 ? (health.json ?? {}) : {};
+    console.log(`Automation in ${targetLabel(t)}: ${h.total ?? page.rows.length} job(s)`
+        + `  —  ${h.active ?? '?'} active, ${h.paused ?? '?'} paused, ${h.failing ?? '?'} failing, ${h.never_ran ?? '?'} never ran`);
+    if (page.rows.length === 0) {
+        console.log('  (none — jobs are DERIVED from the pack\'s automation declaration, not created here.');
+        console.log('   No `automation.yaml` block → no jobs. `octwin deploy` installs them.)');
+        return;
+    }
+    for (const j of page.rows) {
+        const r = j.last_result ?? {};
+        const ran = j.last_run_at ? `last ${j.last_run_at}` : 'never ran';
+        const result = j.last_result
+            ? `  matched ${r.matched ?? 0}/acted ${r.acted ?? 0}${(r.errors ?? 0) > 0 ? `/ERRORS ${r.errors}` : ''}`
+            : '';
+        console.log(`  ${String(j.key ?? j.id).padEnd(26)} ${String(j.status).padEnd(7)} ${j.kind}/${j.entity ?? '—'}`
+            + `  every ${j.interval_seconds}s  ${ran}${result}`);
+    }
+    console.log('\nRun one now:  octwin automation run <jobId>     (jobId = the `key` above, or its uuid)');
+    console.log('Pause/resume: octwin automation pause|resume <jobId>');
+    console.log('Campaigns:    octwin automation campaigns');
+}
+// ── integrations: declared connections, their credentials, and the delivery log ──
+/** Verbs that act on a connection or a delivery, rather than naming one. */
+const INTEGRATION_VERBS = new Set(['test', 'preflight', 'deliveries', 'retry', 'cancel', 'send-now', 'events']);
+/** The three delivery actions — each its own verb so the scope hint can differ. */
+const DELIVERY_ACTIONS = {
+    'retry': { path: 'retry', what: 'retry' },
+    'cancel': { path: 'cancel', what: 'cancel' },
+    'send-now': { path: 'send-now', what: 'send' },
+};
+/** `octwin integrations <verb> …` — the connection + delivery verbs. */
+async function cmdIntegrationsVerb(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/integrations`;
+    const verb = flags._[0];
+    const arg = flags._[1];
+    const asJson = flags.json === true;
+    // ── deliveries: the outbound log ──────────────────────────────────────────
+    if (verb === 'deliveries') {
+        if (arg) {
+            const { status, json } = await apiGet(`${base}/deliveries/${encodeURIComponent(arg)}`, t);
+            if (status === 404)
+                die(`delivery '${arg}' not found`);
+            if (status !== 200)
+                die(`could not read delivery (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+            if (asJson) {
+                console.log(JSON.stringify(json, null, 2));
+                return;
+            }
+            const d = json?.delivery ?? {};
+            console.log(`Delivery ${d.id}  ${d.status}  ${d.connection_key}/${d.operation_id}`);
+            console.log(`  attempts ${d.attempts}${d.http_status ? `   HTTP ${d.http_status}` : ''}${d.port ? `   port: ${d.port}` : ''}`);
+            if (d.last_error)
+                console.log(`  last error: ${d.last_error}`);
+            if (d.next_attempt_at)
+                console.log(`  next attempt: ${d.next_attempt_at}`);
+            console.log(`  from ${d.source_kind ?? '—'}${d.source_hook ? ` (${d.source_hook})` : ''}${d.source_record_id ? `  record ${d.source_record_id}` : ''}`);
+            // The snapshots are redacted at WRITE time, which is why the detail view may print them.
+            if (d.request)
+                console.log(`  request:  ${JSON.stringify(d.request)}`);
+            if (d.response)
+                console.log(`  response: ${JSON.stringify(d.response)}`);
+            return;
+        }
+        const q = new URLSearchParams(pagingQs(flags));
+        if (typeof flags.status === 'string')
+            q.set('status', flags.status);
+        if (typeof flags.operation === 'string')
+            q.set('operation', flags.operation);
+        if (!asJson)
+            console.log(`→ Reading the delivery log from ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}/deliveries?${q.toString()}`, t);
+        if (status !== 200)
+            die(`could not read deliveries (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const page = readPage(json);
+        const c = json?.counts;
+        console.log(`Deliveries in ${targetLabel(t)}: ${page.total ?? page.rows.length}`
+            + (c ? `  —  queued ${c.queued ?? 0}, sent ${c.sent ?? 0}, failed ${c.failed ?? 0}, cancelled ${c.cancelled ?? 0}` : ''));
+        if (page.rows.length === 0)
+            console.log('  (none — a delivery is produced by an `integrations:` operation firing on a record hook)');
+        for (const d of page.rows) {
+            const err = d.last_error ? `  ${String(d.last_error).slice(0, 60)}` : '';
+            console.log(`  ${String(d.status).padEnd(9)} ${String(d.connection_key ?? '—').padEnd(16)} ${String(d.operation_id ?? '—').padEnd(20)}`
+                + ` try ${d.attempts}${d.http_status ? ` HTTP ${d.http_status}` : ''}  ${d.id}${err}`);
+        }
+        const more = morePageHint(page, 'octwin integrations deliveries');
+        if (more)
+            console.log(more);
+        console.log('\nOne delivery + its request/response:  octwin integrations deliveries <id>');
+        console.log('Act on one:  octwin integrations retry|cancel|send-now <id>');
+        return;
+    }
+    // ── inbound events ────────────────────────────────────────────────────────
+    if (verb === 'events') {
+        if (!asJson)
+            console.log(`→ Reading inbound integration events from ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}/inbound-events?${pagingQs(flags)}`, t);
+        if (status !== 200)
+            die(`could not read inbound events (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const events = (json?.events ?? readPage(json).rows);
+        console.log(`Inbound events in ${targetLabel(t)}: ${events.length}`);
+        if (events.length === 0)
+            console.log('  (none — an inbound event arrives at POST /api/integrations/<tenant>/<project>/<inboundKey>)');
+        for (const e of events) {
+            console.log(`  ${e.received_at ?? e.created_at ?? '—'}  ${e.inbound_key ?? '—'}  ${e.status ?? e.outcome ?? '—'}${e.detail ? `  ${e.detail}` : ''}`);
+        }
+        return;
+    }
+    // ── a delivery action ─────────────────────────────────────────────────────
+    const action = DELIVERY_ACTIONS[verb];
+    if (action) {
+        if (!arg)
+            die(`usage: octwin integrations ${verb} <deliveryId>   (ids: octwin integrations deliveries)`);
+        const { status, json } = await apiSend('POST', `${base}/deliveries/${encodeURIComponent(arg)}/${action.path}`, undefined, t);
+        // 409 is the route's own "wrong state" answer, and it carries the rule — print
+        // it rather than a generic failure, because the fix is choosing another delivery.
+        if (status === 409)
+            die(`cannot ${action.what} delivery '${arg}'${errDetail(json)}`);
+        if (status === 404)
+            die(`delivery '${arg}' not found`);
+        if (status !== 200)
+            writeFail(`${action.what} delivery '${arg}'`, status, json, url);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const d = json?.delivery ?? {};
+        console.log(`✓ delivery ${d.id ?? arg} is now ${d.status}${d.next_attempt_at ? `  (next attempt ${d.next_attempt_at})` : ''}`);
+        return;
+    }
+    // ── preflight / test on one connection ────────────────────────────────────
+    if (!arg)
+        die(`usage: octwin integrations ${verb} <connectionKey>   (keys: octwin integrations)`);
+    if (verb === 'preflight') {
+        if (!asJson)
+            console.log(`→ Preflighting connection '${arg}' in ${targetLabel(t)} …`);
+        const { status, json } = await apiSend('POST', `${base}/connections/${encodeURIComponent(arg)}/preflight`, undefined, t);
+        if (status !== 200)
+            die(`could not preflight '${arg}' (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const marks = { pass: '✓', fail: '✗', warn: '⚠', skipped: '–' };
+        console.log(`Preflight '${json?.connection_key ?? arg}': ${json?.ok ? 'READY' : 'NOT READY'}`);
+        for (const c of (json?.checks ?? [])) {
+            console.log(`  ${marks[c.status] ?? '?'} ${String(c.label).padEnd(30)} ${c.detail}`);
+            if (c.fix)
+                console.log(`      fix: ${c.fix}`);
+        }
+        // Preflight is a DIAGNOSIS and needs only `integrations:read`; `test` makes a
+        // live call and needs write. Worth saying, because the two read alike.
+        if (!json?.ok)
+            console.log('\nPreflight makes no live call. Once it is READY: octwin integrations test <key>');
+        return;
+    }
+    // test — a live call against the connection's declared `health:` operation
+    if (!asJson)
+        console.log(`→ Testing connection '${arg}' against its health operation …`);
+    const { status, json } = await apiSend('POST', `${base}/connections/${encodeURIComponent(arg)}/test`, undefined, t);
+    if (status === 409)
+        die(`no pack is installed on ${targetLabel(t)}${errDetail(json)}`);
+    if (status === 404)
+        die(`${errDetail(json).replace(/^ — /, '') || `connection '${arg}' is not declared by the installed pack`}`);
+    // A 400 here is a real answer, not a usage error: the route returns
+    // `{ ok:false, detail }` when the live call fails, and that detail IS the result.
+    if (status === 400 && json && typeof json === 'object' && 'ok' in json) {
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`✗ '${arg}' failed: ${json.detail ?? '(no detail)'}`);
+        console.log('  Diagnose without calling out:  octwin integrations preflight ' + arg);
+        process.exitCode = 1;
+        return;
+    }
+    if (status !== 200)
+        writeFail(`test connection '${arg}'`, status, json, url);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    console.log(`${json?.ok ? '✓' : '✗'} '${arg}': ${json?.detail ?? '(no detail)'}`);
+    if (json?.http_status)
+        console.log(`  HTTP ${json.http_status}   port: ${json.port ?? '—'}`);
+    if (json?.data !== undefined && json?.data !== null)
+        console.log(`  data: ${JSON.stringify(json.data).slice(0, 300)}`);
+    if (!json?.ok)
+        process.exitCode = 1;
+}
+/**
+ * `octwin integrations [--json]` — what the pack DECLARES beside what is actually
+ * configured, in one view.
+ *
+ * Needs `integrations:read`. The two halves are deliberately joined: a declared
+ * connection with no configured row is the single most common reason an
+ * integration silently never fires, and reading either list alone cannot show it.
+ */
+async function cmdIntegrations(flags) {
+    if (typeof flags._[0] === 'string' && INTEGRATION_VERBS.has(flags._[0]))
+        return cmdIntegrationsVerb(flags);
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/integrations`;
+    const asJson = flags.json === true;
+    if (!asJson)
+        console.log(`→ Reading integrations from ${targetLabel(t)} …`);
+    const [declared, configured] = await Promise.all([
+        apiGet(`${base}/declared`, t),
+        apiGet(`${base}/connections`, t),
+    ]);
+    if (declared.status !== 200)
+        die(`could not read declared integrations (HTTP ${declared.status})${errDetail(declared.json)}${authFailureDetail(declared.status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify({ declared: declared.json, configured: configured.json }, null, 2));
+        return;
+    }
+    const d = declared.json ?? {};
+    const rows = (configured.status === 200 ? (configured.json?.connections ?? []) : []);
+    const byKey = new Map(rows.map(r => [r.connection_key, r]));
+    const conns = (d.connections ?? []);
+    if (!d.pack_id) {
+        console.log('No pack is installed on this project — nothing declares an integration.');
+        return;
+    }
+    if (conns.length === 0 && (d.operations ?? []).length === 0 && (d.inbound ?? []).length === 0) {
+        console.log(`Pack '${d.pack_id}' declares no integrations — no \`integrations.yaml\`.`);
+        return;
+    }
+    console.log(`Integrations declared by '${d.pack_id}':`);
+    for (const c of conns) {
+        const row = byKey.get(c.key);
+        const state = !row
+            ? 'NOT CONFIGURED'
+            : row.status !== 'active'
+                ? row.status
+                : row.has_credential ? `ready (…${row.credential_hint ?? '••••'})` : 'no credential';
+        const test = row?.last_test_at
+            ? `  last test ${row.last_test_ok ? 'ok' : 'FAILED'} ${row.last_test_at}`
+            : '';
+        console.log(`  ${String(c.key).padEnd(20)} ${state.padEnd(22)} ${c.auth_kind} in ${c.auth_in}${test}`);
+        if (!row && c.setup_hint)
+            console.log(`      setup: ${c.setup_hint}`);
+        if (row?.last_test_detail && row.last_test_ok === false)
+            console.log(`      ${row.last_test_detail}`);
+    }
+    const ops = (d.operations ?? []);
+    if (ops.length) {
+        console.log(`\n  operations: ${ops.map(o => o.id ?? o.key).join(', ')}`);
+    }
+    const inbound = (d.inbound ?? []);
+    if (inbound.length) {
+        console.log(`  inbound keys: ${inbound.map(i => i.key ?? i.id).join(', ')}`);
+    }
+    // A declared-but-unconfigured connection is the failure this view exists to make
+    // visible, so it gets the next step rather than being left as a status word.
+    const missing = conns.filter(c => !byKey.has(c.key)).map(c => c.key);
+    if (missing.length) {
+        console.log(`\n⚠ ${missing.length} connection(s) declared but never configured: ${missing.join(', ')}`);
+        console.log('  Nothing using them will fire. Configure them in the console → Integrations,');
+        console.log(`  then: octwin integrations preflight ${missing[0]}`);
+    }
+    console.log('\nDiagnose one: octwin integrations preflight <key>   Live call: octwin integrations test <key>');
+    console.log('Outbound log: octwin integrations deliveries        Inbound:   octwin integrations events');
+}
+// ── journeys: the pack's declared customer journeys, measured ────────────────
+/**
+ * The five journey analytics modes, plus `definition`.
+ *
+ * Deliberately the SAME flag grammar as `octwin analytics`
+ * (`--funnel|--overview|--trends|--cost`) rather than a second shape for the same
+ * idea — a journey funnel and an entity funnel are the same question asked of a
+ * different subject. `goals` is the journey-only member (an entity has
+ * milestones); `definition` prints what the pack declared, unmeasured.
+ */
+const JOURNEY_MODES = ['funnel', 'overview', 'goals', 'trends', 'cost', 'definition'];
+/** Both "no such journey" and "no `view` grant" answer 200 + `has_data:false` — a
+ *  deliberate empty state, never a 403 — so a bare "no data" would hide the cause. */
+function printNoJourneyData(journeyId) {
+    console.log(`No data for journey '${journeyId}'. Either:`);
+    console.log(`  • the pack declares no journey with that id (list them: octwin journeys), or`);
+    console.log(`  • your token's role has no \`view\` grant on it, or`);
+    console.log(`  • nothing has entered the journey in the window yet — drive one with \`octwin chat\`.`);
+}
+/**
+ * `octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]
+ *  [--stage <stageId>] [--json]` — the journeys a pack declares, and how they perform.
+ *
+ * Needs `journeys:read`. Journeys carry RBAC ON TOP of the scope, so a token can
+ * hold the scope and still see an empty journey — `printNoJourneyData` names that
+ * rather than reporting it as absence of data.
+ */
+async function cmdJourneys(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/journeys`;
+    const journeyId = flags._[0];
+    const asJson = flags.json === true;
+    const stage = typeof flags.stage === 'string' ? flags.stage : undefined;
+    const mode = JOURNEY_MODES.find(m => flags[m] === true) ?? 'funnel';
+    if (stage && !journeyId)
+        die('usage: octwin journeys <journeyId> --stage <stageId>   (a stage belongs to a journey)');
+    // ── the list ──────────────────────────────────────────────────────────────
+    if (!journeyId) {
+        if (!asJson)
+            console.log(`→ Reading declared journeys from ${targetLabel(t)} …`);
+        /**
+         * A template literal, not the bare `base`, so `cli-routes.test.ts` can SEE this
+         * URL — its extractor only reads a template literal in the first argument
+         * position, and a bare identifier slips past unchecked. That guard exists
+         * because six deleted routes shipped as silent 404s; a call it cannot read is a
+         * call it cannot protect.
+         *
+         * The first draft of this very comment QUOTED the call shape it was describing,
+         * which made the comment itself match the extractor's pattern — the scan
+         * consumed the prose and skipped the real call one line below. So the note that
+         * explains the guard silently disabled it. Do not spell the scanned pattern
+         * inside a comment in a file that is itself scanned.
+         */
+        const { status, json } = await apiGet(`${base}`, t);
+        if (status !== 200)
+            die(`could not read journeys (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const js = (json?.journeys ?? []);
+        if (js.length === 0) {
+            console.log('No journeys declared — a journey comes from the pack\'s `journeys.yaml`.');
+            console.log('(Per-ENTITY stage funnels are a different surface: octwin analytics)');
+            return;
+        }
+        console.log(`Journeys in ${targetLabel(t)}:`);
+        for (const j of js)
+            console.log(`  ${String(j.id).padEnd(24)} ${pickLabel(j.label) ?? ''}`);
+        console.log('\nOne journey:  octwin journeys <journeyId>   (add --overview / --goals / --trends / --cost / --definition)');
+        console.log('Who is at a stage: octwin journeys <journeyId> --stage <stageId>');
+        return;
+    }
+    // ── stage drill-down: the runs currently at a stage ────────────────────────
+    if (stage) {
+        if (!asJson)
+            console.log(`→ Reading '${journeyId}' runs at stage '${stage}' …`);
+        const { status, json } = await apiGet(`${base}/${encodeURIComponent(journeyId)}/stages/${encodeURIComponent(stage)}/runs?${pagingQs(flags)}`, t);
+        if (status === 404)
+            die(`unknown stage '${stage}' for journey '${journeyId}'${errDetail(json)}`);
+        if (status !== 200)
+            die(`could not read stage runs (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        if (json?.has_data === false) {
+            printNoJourneyData(journeyId);
+            return;
+        }
+        const page = readPage(json);
+        console.log(`'${journeyId}' at '${stage}' (live snapshot): ${page.total ?? page.rows.length} run(s)`);
+        for (const r of page.rows) {
+            const who = r.channel_contact_handle ?? r.display_name ?? r.contact_id ?? '—';
+            console.log(`  ${who}  entered ${r.entered_at ?? r.created_at ?? '—'}${r.completed_at ? `  completed ${r.completed_at}` : ''}`);
+        }
+        const more = morePageHint(page, `octwin journeys ${journeyId} --stage ${stage}`);
+        if (more)
+            console.log(more);
+        return;
+    }
+    if (!asJson)
+        console.log(`→ Reading '${journeyId}' ${mode} from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(journeyId)}/${mode}`, t);
+    if (status === 404)
+        die(`journey '${journeyId}' not found (list them: octwin journeys)`);
+    if (status !== 200)
+        die(`could not read ${mode} (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    if (json?.has_data === false) {
+        printNoJourneyData(journeyId);
+        return;
+    }
+    const range = json?.range ? ` (${String(json.range.from).slice(0, 10)} → ${String(json.range.to).slice(0, 10)})` : '';
+    console.log(`Journey '${journeyId}' — ${mode}${range}:`);
+    switch (mode) {
+        case 'definition': {
+            /**
+             * Unmeasured: what the pack DECLARED. The one mode that answers "is this journey
+             * even wired the way I think" with no traffic at all.
+             *
+             * The payload nests under `definition` and its own field names differ from the
+             * measured modes: a stage carries `order` (not the funnel's `rank`), and a goal
+             * names the `stage` it fires on. Read off the live route rather than assumed —
+             * the first draft printed `?.` for every rank because it reused `rank`.
+             */
+            const def = json?.definition ?? {};
+            const stages = (def.stages ?? []);
+            const goals = (def.goals ?? []);
+            const events = (def.events ?? []);
+            for (const s of stages) {
+                console.log(`  ${String(s.order ?? '?').padStart(2)}. ${String(s.id).padEnd(24)} ${pickLabel(s.label) ?? ''}`);
+            }
+            if (goals.length) {
+                console.log('  goals:');
+                for (const g of goals) {
+                    console.log(`    ${String(g.id).padEnd(24)} ${String(pickLabel(g.label) ?? '').padEnd(22)}`
+                        + `${g.stage ? ` on stage '${g.stage}'` : ''}${g.value != null ? `  value ${g.value}` : ''}`);
+                }
+            }
+            // An event is keyed by `name` and carries what it MOVES — `advances_to` a stage
+            // and optionally `completes` a goal. That wiring is the whole reason to read a
+            // definition, so it gets a row each rather than a comma list of names.
+            if (events.length) {
+                console.log('  events (what moves the journey):');
+                for (const e of events) {
+                    console.log(`    ${String(e.name).padEnd(24)} ${String(pickLabel(e.label) ?? '').padEnd(22)}`
+                        + `${e.advances_to ? ` → stage '${e.advances_to}'` : ''}${e.completes ? `, completes '${e.completes}'` : ''}`);
+                }
+            }
+            break;
+        }
+        case 'funnel':
+            for (const s of (json?.funnel ?? [])) {
+                const conv = s.conversion_from_prev_pct == null ? '' : `  ${s.conversion_from_prev_pct}% of prev`;
+                const lost = s.drop_off_from_prev ? `  (−${s.drop_off_from_prev})` : '';
+                console.log(`  ${String(s.rank).padStart(2)}. ${String(pickLabel(s.label) ?? s.stage_id).padEnd(24)} ${String(s.reached).padStart(6)}${conv}${lost}`);
+            }
+            break;
+        case 'overview': {
+            const s = json?.summary ?? {};
+            console.log(`  entered ${s.entered}  →  converted ${s.converted}${s.conversion_pct == null ? '' : `  (${s.conversion_pct}%)`}`
+                + `${s.converted_basis ? `   [basis: ${s.converted_basis}]` : ''}`);
+            if (s.biggest_dropoff)
+                console.log(`  biggest drop-off: ${s.biggest_dropoff.from} → ${s.biggest_dropoff.to}  (lost ${s.biggest_dropoff.lost})`);
+            if (s.top_goal)
+                console.log(`  top goal: ${pickLabel(s.top_goal.label) ?? s.top_goal.goal_id} (${s.top_goal.completions})`);
+            break;
+        }
+        case 'goals':
+            for (const g of (json?.goals ?? [])) {
+                const p50 = g.p50_seconds == null ? '' : `  p50 ${Math.round(g.p50_seconds / 60)}m`;
+                console.log(`  ${String(pickLabel(g.label) ?? g.goal_id).padEnd(28)} ${String(g.completions).padStart(6)} completion(s),`
+                    + ` ${g.unique_contacts} contact(s)${g.total_value ? `, value ${g.total_value}` : ''}${p50}`);
+            }
+            break;
+        case 'trends':
+            for (const b of (json?.buckets ?? [])) {
+                console.log(`  ${String(b.bucket).slice(0, 10)}  active ${b.active_contacts}  goals ${b.goal_completions}`);
+            }
+            break;
+        case 'cost':
+            for (const g of (json?.by_goal ?? [])) {
+                const unknown = g.cost_unknown_rows ? `  (${g.cost_unknown_rows} row(s) unpriced)` : '';
+                console.log(`  ${String(pickLabel(g.label) ?? g.id).padEnd(24)} ${String(g.conversations).padStart(5)} conv,`
+                    + ` ${String(g.total_tokens).padStart(8)} tokens, $${(g.cost_usd ?? 0).toFixed(4)}${unknown}`);
+            }
+            break;
+    }
+}
+// ── performance: the project's business indicators ──────────────────────────
+/**
+ * `octwin performance [--detail] [--json]` — the indicators the project's own
+ * declarations produce: value, conversion, duration, per journey.
+ *
+ * Needs `records:read` — **not** a `performance:*` scope, which does not exist.
+ * That means the Read-only token preset already reaches this.
+ */
+async function cmdPerformance(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/performance`;
+    const asJson = flags.json === true;
+    const detail = flags.detail === true;
+    if (!asJson)
+        console.log(`→ Reading business performance from ${targetLabel(t)} …`);
+    // Two explicit calls rather than `apiGet(detail ? … : base)`: the route guard's
+    // extractor only reads a template literal in the FIRST argument position, so a
+    // ternary hides both URLs from it.
+    const { status, json } = detail
+        ? await apiGet(`${base}/detail`, t)
+        : await apiGet(`${base}`, t);
+    if (status !== 200)
+        die(`could not read performance (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    if (json?.has_data === false) {
+        console.log('No performance indicators — they are DERIVED from declarations (a journey with a');
+        console.log('goal value, a pipelined entity), so a pack that declares none produces none.');
+        return;
+    }
+    const r = json?.range ?? {};
+    console.log(`Performance in ${targetLabel(t)}`
+        + `${r.from ? ` (${String(r.from).slice(0, 10)} → ${String(r.to).slice(0, 10)}, ${r.days ?? '?'}d, by ${json?.bucket ?? 'day'})` : ''}:`);
+    const inds = (json?.indicators ?? []);
+    if (inds.length === 0)
+        console.log('  (none)');
+    for (const i of inds) {
+        const unit = i.unit === 'pct' ? '%' : '';
+        // `delta_pct` is signed and against the PREVIOUS window — sign it explicitly so
+        // a fall is never read as a rise.
+        const delta = i.delta_pct == null ? '' : `  ${i.delta_pct >= 0 ? '+' : ''}${i.delta_pct}% vs prev`;
+        const frac = i.numerator != null && i.denominator != null
+            ? `  (${i.numerator}/${i.denominator}${i.denominator_of ? ` ${i.denominator_of}` : ''})`
+            : '';
+        console.log(`  ${String(pickLabel(i.heading) ?? i.kind).padEnd(16)} ${String(pickLabel(i.label) ?? '').padEnd(20)}`
+            + ` ${String(i.value ?? '—').padStart(9)}${unit}${delta}${frac}`);
+        if (i.why)
+            console.log(`      why: ${i.why}`);
+        if (i.biggest_dropoff)
+            console.log(`      biggest drop-off: ${i.biggest_dropoff.from} → ${i.biggest_dropoff.to} (lost ${i.biggest_dropoff.lost})`);
+    }
+    if (!detail)
+        console.log('\nPer-indicator breakdown:  octwin performance --detail');
+}
+// ── usage: model calls, tokens and cost ─────────────────────────────────────
+/** One `{ key, calls, total_tokens, cost_usd }` breakdown row. */
+function printUsageRows(title, rows) {
+    if (!rows?.length)
+        return;
+    console.log(`  ${title}:`);
+    for (const r of rows) {
+        console.log(`    ${String(r.key ?? r.day).padEnd(40)} ${String(r.calls ?? '—').padStart(6)} call(s)`
+            + ` ${String(r.total_tokens ?? 0).padStart(10)} tokens  $${(r.cost_usd ?? 0).toFixed(4)}`
+            + `${r.cost_partial ? '  (partial — some rows unpriced)' : ''}`);
+    }
+}
+/**
+ * `octwin usage [--json]` — model calls, tokens and cost for the resolved scope.
+ *
+ * Needs NO scope beyond a valid token (the route is `requireTenantAccess`), which
+ * is why it has no `COMMAND_REQUIREMENTS` entry: declaring one would print
+ * "needs the X scope" on a failure whose cause is something else.
+ *
+ * Project-scoped when a project is resolved, tenant-wide otherwise — both routes
+ * exist and the narrower one is the more useful default while testing a pack.
+ * This is spend on MODEL calls; WhatsApp/Meta billing is operator-only and no
+ * token can reach it.
+ */
+async function cmdUsage(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const asJson = flags.json === true;
+    const scoped = Boolean(t.project);
+    if (!asJson)
+        console.log(`→ Reading model usage for ${scoped ? 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
+        ? await apiGet(`${url}/api/self/p/usage`, t)
+        : await apiGet(`${url}/api/self/t/usage`, t);
+    if (status !== 200)
+        die(`could not read usage (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    const u = json?.usage ?? {};
+    const tot = u.totals ?? {};
+    const r = json?.range ?? {};
+    console.log(`Model usage — ${scoped ? `project '${json?.project?.slug ?? t.project}'` : `workspace '${json?.tenant?.slug ?? ''}'`}`
+        + `${r.from ? ` (${String(r.from).slice(0, 10)} → ${String(r.to).slice(0, 10)})` : ''}`);
+    console.log(`  ${tot.calls ?? 0} call(s)   ${tot.total_tokens ?? 0} tokens`
+        + ` (${tot.prompt_tokens ?? 0} in / ${tot.completion_tokens ?? 0} out)   $${(tot.cost_usd ?? 0).toFixed(4)}`
+        + `${tot.cost_partial ? '  ⚠ partial: some calls had no price' : ''}`);
+    if ((tot.calls ?? 0) === 0) {
+        console.log('  (nothing in the window — drive a turn with `octwin chat`)');
+        return;
+    }
+    printUsageRows('by model', u.by_model);
+    printUsageRows('by kind', u.by_kind);
+    printUsageRows('by agent', u.by_agent);
+    printUsageRows('by channel', u.by_channel);
+    // Not WhatsApp/Meta spend: that is operator-only and deliberately outside the
+    // token scope registry, so this command cannot show it at all.
+    console.log('\nThis is MODEL spend. WhatsApp/Meta message billing is operator-only — not reachable by an API token.');
+}
 function help() {
-    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
-
-  octwin --version                                      # print the CLI version (+ any upgrade notice)
-  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
-  octwin validate [--dir .] [--remote] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
-  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
-  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
-  octwin projects [--archived] [--json]                  # the --project slugs this token can name
-  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
-  octwin status  [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
-  octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
-  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
-  octwin work    [recordId] [--queues] [--json]          # inspect the work inbox (worked records) + timelines
-  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
-  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
-  octwin media   generate "<prompt>" [--out <file.png>] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
-  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
-  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
-  octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
-  octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
-  octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
-  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
-  octwin test    [--dir .]                               # = validate --remote (the full platform check)
-  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
-  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
-
-Writes — exercise the state your pack creates (each needs the matching :write scope):
-  octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
-  octwin records tasks | task complete <taskId> [--outcome done|cancelled]
-  octwin work    assign <id> --to user:<uuid>|none | note <id> "…" | stage <id> --to <stage>
-  octwin work    decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
-  octwin orders  transition <ref> --to <status> | refund <ref> --force
-  octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
-  octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
-  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
-
-Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
-\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
-button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
-Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
-octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
-Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
+    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
+
+  octwin --version                                      # print the CLI version (+ any upgrade notice)
+  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+  octwin validate [--dir .] [--remote] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
+  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
+  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
+  octwin projects [--archived] [--json]                  # the --project slugs this token can name
+  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
+  octwin status  [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
+  octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
+  octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
+  octwin work    [recordId] [--queues] [--json]          # inspect the work inbox (worked records) + timelines
+  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
+  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
+  octwin media   generate "<prompt>" [--out <file.png>] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
+  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
+  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
+  octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
+  octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
+  octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
+  octwin automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
+  octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
+  octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
+  octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
+  octwin performance [--detail] [--json]                 # the project's business indicators (value/conversion/duration)
+  octwin usage   [--json]                                # model calls, tokens and cost (project if pinned, else workspace)
+  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
+  octwin test    [--dir .]                               # = validate --remote (the full platform check)
+  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
+  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
+
+Writes — exercise the state your pack creates (each needs the matching :write scope):
+  octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
+  octwin records tasks | task complete <taskId> [--outcome done|cancelled]
+  octwin work    assign <id> --to user:<uuid>|none | note <id> "…" | stage <id> --to <stage>
+  octwin work    decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
+  octwin orders  transition <ref> --to <status> | refund <ref> --force
+  octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
+  octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
+  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
+  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
+  octwin integrations test <key>                         # a LIVE call to the connection's health: operation
+  octwin integrations retry|cancel|send-now <deliveryId>
+  (octwin integrations preflight <key> needs only integrations:read — it makes no call)
+
+Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
+\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
+button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
+Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
+octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
+Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
 Per-command usage: octwin <command> --help`);
 }
 /** Per-subcommand usage — printed for `octwin <cmd> --help|-h` BEFORE any
  *  network/auth work (a --help that 401s is worse than no help at all). */
 const COMMAND_HELP = {
-    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   Scaffold a pure-YAML starter pack into <dir>.`,
-    validate: `octwin validate [--dir .] [--remote] [--require-kb] [--strict-primitives]
-  Offline structural check, plus two checks driven by the pulled capability
-  reference (render-intent fields, primitive arguments). Those two SKIP when the
-  reference is missing — the run says so, and --require-kb turns the skip into a
-  failure for CI. --remote additionally runs the platform's FULL manifest +
-  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.
-  --strict-primitives (with --remote) additionally type-checks LITERAL args:
-  values against each primitive's declared input schema; expression strings
+    validate: `octwin validate [--dir .] [--remote] [--require-kb] [--strict-primitives]
+  Offline structural check, plus two checks driven by the pulled capability
+  reference (render-intent fields, primitive arguments). Those two SKIP when the
+  reference is missing — the run says so, and --require-kb turns the skip into a
+  failure for CI. --remote additionally runs the platform's FULL manifest +
+  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.
+  --strict-primitives (with --remote) additionally type-checks LITERAL args:
+  values against each primitive's declared input schema; expression strings
   ('$found.id', '{$t(…)}') are always exempt.`,
-    login: `octwin login --url <platformUrl> --token oct_…
-  Save a deploy token (console → Settings → API tokens) for that platform url,
-  make that url the DEFAULT deploy target for every later command, and echo the
+    login: `octwin login --url <platformUrl> --token oct_…
+  Save a deploy token (console → Settings → API tokens) for that platform url,
+  make that url the DEFAULT deploy target for every later command, and echo the
   workspace + project pin + scopes the token reaches.`,
-    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
+    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
-    projects: `octwin projects [--archived] [--json]
-  List the workspace's projects — the slugs every --project flag takes, with the
-  plan's project cap. --archived includes archived ones. A pack:deploy token
-  reaches this (it names a project in every other command).
-
-octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
-  Create a project. The URL slug is derived from the name unless --slug pins one.
-  --pack installs an ALREADY-published pack; the usual next step is instead
-  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
-
-octwin projects rm <slug> [--yes]
-  HARD delete — the project and everything cascading from it (conversations,
-  contacts, records, installs). No undo, and not the same as archiving.
-  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
-  default. Together these make a disposable end-to-end environment:
-    octwin projects create "Scratch" && octwin deploy --project scratch --seed
-    octwin chat "hi" --project scratch
-    octwin projects rm scratch --yes
+    projects: `octwin projects [--archived] [--json]
+  List the workspace's projects — the slugs every --project flag takes, with the
+  plan's project cap. --archived includes archived ones. A pack:deploy token
+  reaches this (it names a project in every other command).
+
+octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
+  Create a project. The URL slug is derived from the name unless --slug pins one.
+  --pack installs an ALREADY-published pack; the usual next step is instead
+  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
+
+octwin projects rm <slug> [--yes]
+  HARD delete — the project and everything cascading from it (conversations,
+  contacts, records, installs). No undo, and not the same as archiving.
+  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
+  default. Together these make a disposable end-to-end environment:
+    octwin projects create "Scratch" && octwin deploy --project scratch --seed
+    octwin chat "hi" --project scratch
+    octwin projects rm scratch --yes
   Both verbs need the \`projects:write\` scope — a pack:deploy token does NOT confer it.`,
-    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-                [--request-listing | --withdraw-listing]
-  Upload the pack bundle, validate server-side, install onto the project.
-  --seed additionally applies the pack's demo seed (streams progress).
-
-  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
-  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
-
-  --request-listing    ask an operator to review this pack for the public marketplace
-                       (the pre-signup storefront at /packs). Requires 'public: true'
-                       under 'listing:' in manifest.yaml — the manifest states that the
-                       pack is a product, the flag is you choosing to ask.
-  --withdraw-listing   retract the request, including an approved listing.
-
-  An approval covers the CONTENT it was made against, so a later deploy that changes the
+    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+                [--request-listing | --withdraw-listing]
+  Upload the pack bundle, validate server-side, install onto the project.
+  --seed additionally applies the pack's demo seed (streams progress).
+
+  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
+  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
+
+  --request-listing    ask an operator to review this pack for the public marketplace
+                       (the pre-signup storefront at /packs). Requires 'public: true'
+                       under 'listing:' in manifest.yaml — the manifest states that the
+                       pack is a product, the flag is you choosing to ask.
+  --withdraw-listing   retract the request, including an approved listing.
+
+  An approval covers the CONTENT it was made against, so a later deploy that changes the
   pack returns it to the review queue on its own — no flag needed, and the CLI says so.`,
-    seed: `octwin seed [--pack <packId>]
-  Apply the pack's demo/reference data to the project it is installed on, without
-  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
-  and the demo operator topology. Reports what each kind produced.
-  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
-  than regenerated, so a second pass costs nothing. --pack is only needed when a
+    seed: `octwin seed [--pack <packId>]
+  Apply the pack's demo/reference data to the project it is installed on, without
+  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
+  and the demo operator topology. Reports what each kind produced.
+  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
+  than regenerated, so a second pass costs nothing. --pack is only needed when a
   project somehow runs more than one.`,
-    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
-  Show installed vs live version + the flow list for this pack.
-  The pack id is read from manifest.yaml and QUALIFIED with your workspace slug
-  (a manifest declares a bare name; the owner is attached when you publish). Pass
-  <packId> explicitly to skip that lookup — \`octwin agents\` and \`octwin projects\`
+    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
+  Show installed vs live version + the flow list for this pack.
+  The pack id is read from manifest.yaml and QUALIFIED with your workspace slug
+  (a manifest declares a bare name; the owner is attached when you publish). Pass
+  <packId> explicitly to skip that lookup — \`octwin agents\` and \`octwin projects\`
   both print the qualified form.`,
-    records: `octwin records [entity] [id] [--limit 50] [--offset n]
-  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
-  tickets, anything routed to a queue) read best through \`octwin work\`.
-
-  WRITES (need \`records:write\`; every one is re-checked by RBAC on the record):
-    octwin records create <entity> --set field=value [--set …] [--stage s] [--contact <id>]
-    octwin records patch  <recordId> --entity <entity> --set field=value
-    octwin records stage  <recordId> --to <stage> [--note "..."]
-    octwin records note   <recordId> "the note text"
-    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
-    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
-
-  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
-  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
-  \`patch\` needs --entity even though it has an id: the route resolves the field
-  validator from it. A leading \`create/patch/stage/note/tasks/task\` is read as a
+    records: `octwin records [entity] [id] [--limit 50] [--offset n]
+  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
+  tickets, anything routed to a queue) read best through \`octwin work\`.
+
+  WRITES (need \`records:write\`; every one is re-checked by RBAC on the record):
+    octwin records create <entity> --set field=value [--set …] [--stage s] [--contact <id>]
+    octwin records patch  <recordId> --entity <entity> --set field=value
+    octwin records stage  <recordId> --to <stage> [--note "..."]
+    octwin records note   <recordId> "the note text"
+    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
+    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
+
+  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
+  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
+  \`patch\` needs --entity even though it has an id: the route resolves the field
+  validator from it. A leading \`create/patch/stage/note/tasks/task\` is read as a
   VERB — to list an entity actually named one of those, use \`--entity <name>\`.`,
-    work: `octwin work [recordId] [--queues] [--limit 50] [--offset n] [--json]
-  Inspect the work inbox — every entity the pack declares worked (cases, orders
-  needing review, applications, …): the inbox, one item + its timeline
-  (+ applicable actions), or --queues for queue keys + open counts.
-
-  WRITES (need \`work:write\`; \`stage\` needs \`records:write\`):
-    octwin work assign <recordId> --to user:<uuid>|team:<uuid>|none
-    octwin work note   <recordId> "the note text"
-    octwin work stage  <recordId> --to <stage> [--note "..."]
-    octwin work decide <recordId> --action <action> [--param k=v] [--note "..."] [--dry-run]
-
-  \`decide\` applies one of the entity's declared operator actions — \`octwin work <id>\`
-  lists them with their params. --dry-run previews the customer-facing copy and the
-  resulting stage WITHOUT committing (that route needs only \`work:read\`).
+    work: `octwin work [recordId] [--queues] [--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.`,
-    'platform-kb': `octwin platform-kb [pull] [--if-stale] [--check] [--dir .] [--url <url>] [--token <t>]
-  Pull the platform capability reference (markdown + JSON catalogs) into
-  .octwin/platform-kb/ for the octwin-pack authoring skill, plus three maps:
-  INDEX.md (the corpus) · SYMBOLS.md (every name -> its file; grep this) ·
-  OUTLINE.md (every heading with its line number).
-
-  NO TOKEN NEEDED — the reference is platform stdlib and is served anonymously.
-  A token is used when you have one (it also works against older platforms).
-
-  --if-stale   poll the platform's content_hash first and skip the download when
-               nothing changed. Cheap enough to run at the start of every session.
-  --check      report only, write nothing. Exit 0 = current, 2 = stale or never
-               pulled, 1 = could not tell (offline / refused). For scripts and
-               agent loops that want to branch without parsing prose.`,
-    test: `octwin test [--dir .]
+    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
+  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
+  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
+  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
+  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
+               scripts and agent loops that want to branch without parsing prose.`,
+    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() {
@@ -4393,6 +5288,21 @@ async function main() {
         case 'scheduling':
             await cmdScheduling(flags);
             break;
+        case 'automation':
+            await cmdAutomation(flags);
+            break;
+        case 'integrations':
+            await cmdIntegrations(flags);
+            break;
+        case 'journeys':
+            await cmdJourneys(flags);
+            break;
+        case 'performance':
+            await cmdPerformance(flags);
+            break;
+        case 'usage':
+            await cmdUsage(flags);
+            break;
         case 'platform-kb':
             await cmdPlatformKb(flags);
             break;