octwin-cli 0.1.13 → 0.1.15

package/dist/index.js

@@ -19,6 +19,11 @@
  *   octwin logs    [conversationId] [--as h] [--json]  # list conversations / show one's timeline
  *   octwin chat    "msg" [--as h] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn via the web channel (+ send media)
  *   octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (media:generate scope)
+ *   octwin agents  [packId::agentId] [--prompt]   # effective model/memory + which layer won; --prompt = the resolved system prompt
+ *   octwin orders  [reference_id]    # the orders a conversation produced — money breakdown + payment state (orders:read)
+ *   octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion, any pipelined entity
+ *   octwin catalog [--readiness]     # commerce products + stock + the WhatsApp catalog binding (catalog:read)
+ *   octwin scheduling [--slots <resourceRecordId>]  # engine state / computed slots (scheduling:read)
  *   octwin platform-kb [pull] [--dir .]  # pull the platform capability reference for the authoring skill
  *   octwin test    [--dir .]        # = validate --remote (the full platform check)
  *
@@ -99,12 +104,66 @@ function authFailureHint(status, url) {
         ? `the token was rejected — invalid / expired / revoked. If it JUST worked, this can be a one-off platform hiccup: retry once before re-logging in (octwin login --url ${url} --token oct_…)`
         : `the token is valid but not authorized here (missing scope, plan feature, or role)`;
 }
-/** Print the auth-scope hint below an HTTP-failure line when it's a 401/403 —
- *  so every command explains a token problem, not just the inspect family
- *  (author-feedback A7). No-op for other statuses. */
+/**
+ * The scope (and plan feature, where the route is entitlement-gated) each command's
+ * endpoints require — a client-side mirror of the platform's scope registry
+ * (`src/platform/core/identity/scopes.ts` `SCOPE_REGISTRY`) narrowed to what the CLI
+ * calls. A 403 that names the missing scope is the difference between a two-minute
+ * fix (mint a wider token) and a support thread.
+ *
+ * `pack:deploy` and `media:generate` have access `special`: they match by DIRECT
+ * grant only, so even a `tenant:admin` preset token does NOT confer them
+ * (`scopeSatisfies` — the preset branches only reach `:read`/`:write`). That is the
+ * single most common "but my token is admin" confusion, hence the explicit note below.
+ */
+const COMMAND_REQUIREMENTS = {
+    deploy: { scope: 'pack:deploy' },
+    validate: { scope: 'pack:deploy' },
+    status: { scope: 'pack:deploy' },
+    test: { scope: 'pack:deploy' },
+    'platform-kb': { scope: 'pack:deploy' },
+    media: { scope: 'media:generate' },
+    records: { scope: 'records:read', feature: 'records' },
+    analytics: { scope: 'records:read', feature: 'records' },
+    cases: { scope: 'cases:read', feature: 'cases' },
+    logs: { scope: 'conversations:read' },
+    orders: { scope: 'orders:read', feature: 'orders' },
+    catalog: { scope: 'catalog:read', feature: 'catalog' },
+    scheduling: { scope: 'scheduling:read' },
+    agents: { scope: 'agents:read' },
+};
+/** 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. */
+let CURRENT_COMMAND;
+/** `→ needs the \`orders:read\` scope …` — the requirement line for the running
+ *  command, or '' when the command has no declared requirement. */
+function scopeRequirementHint() {
+    const req = CURRENT_COMMAND ? COMMAND_REQUIREMENTS[CURRENT_COMMAND] : undefined;
+    if (!req)
+        return '';
+    const special = req.scope === 'pack:deploy' || req.scope === 'media:generate';
+    return `needs the \`${req.scope}\` scope`
+        + (special ? ' (granted DIRECTLY only — a `tenant:admin` token does not confer it)' : '')
+        + (req.feature ? `, and the \`${req.feature}\` plan feature on this workspace` : '');
+}
+/** Print the auth hints below an HTTP-failure line when it's a 401/403 — so every
+ *  command explains a token problem, not just the inspect family (author-feedback A7):
+ *  WHY it failed, then WHAT the command needs. No-op for other statuses. */
 function printAuthHint(status, url) {
-    if (status === 401 || status === 403)
-        console.error(`  → ${authFailureHint(status, url)}`);
+    if (status !== 401 && status !== 403)
+        return;
+    console.error(`  → ${authFailureHint(status, url)}`);
+    const req = scopeRequirementHint();
+    if (req)
+        console.error(`  → ${req}`);
+}
+/** The same two hints folded into ONE line, for the `die(...)` call sites that
+ *  report an auth failure inline instead of via `printAuthHint`. */
+function authFailureDetail(status, url) {
+    if (status !== 401 && status !== 403)
+        return '';
+    const req = scopeRequirementHint();
+    return ` — ${authFailureHint(status, url)}${req ? `; ${req}` : ''}`;
 }
 /** Pretty-print a JSON error body (or raw text) for an HTTP failure line. */
 function errDetail(json) {
@@ -335,8 +394,8 @@ async function notifyIfKbStale(flags) {
             return;
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), 2_000);
-        const res = await fetch(`${t.url}/api/admin/tenants/${t.tenant}/octwin-platform-kb?meta=1`, {
-            headers: { authorization: `Bearer ${t.token}` }, signal: ctrl.signal,
+        const res = await fetch(`${t.url}/api/self/t/octwin-platform-kb?meta=1`, {
+            headers: authHeaders(t), signal: ctrl.signal,
         });
         clearTimeout(timer);
         if (!res.ok)
@@ -376,7 +435,12 @@ function commandTouchesPlatform(command, flags) {
         case 'records':
         case 'cases':
         case 'logs':
-        case 'whoami': return true;
+        case 'whoami':
+        case 'agents':
+        case 'orders':
+        case 'analytics':
+        case 'catalog':
+        case 'scheduling': return true;
         default: return false;
     }
 }
@@ -402,10 +466,11 @@ function cmdInit(flags) {
         displayName: flags['display-name'] ?? undefined,
     });
     // Deploy config + repo hygiene + a README.
+    // The token carries its own tenant (and optional project pin), so pack.json
+    // needs only the platform URL. `tenant`/`project` may be added as optional
+    // overrides (they also seed `octwin chat`, which is tenant/project-pathed).
     writeFileSync(join(dir, 'pack.json'), JSON.stringify({
         platform_url: 'http://localhost:3000',
-        tenant: 'your-tenant-slug',
-        project: 'main',
     }, null, 2) + '\n', 'utf8');
     writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.pack-bundles/\n.octwin/\n', 'utf8');
     if (!existsSync(join(dir, 'README.md'))) {
@@ -417,7 +482,7 @@ function cmdInit(flags) {
     console.log('  git init && git add -A && git commit -m "init pack"');
     console.log('  # edit manifest.yaml / flows / prompts, then:');
     console.log('  octwin validate');
-    console.log('  # set platform_url + tenant + project in pack.json, then:');
+    console.log('  # set platform_url in pack.json (tenant comes from your token), then:');
     console.log('  octwin login --url <platformUrl> --token <deploy-token>');
     console.log('  octwin deploy');
 }
@@ -443,11 +508,12 @@ async function cmdValidate(flags) {
     }
     // Remote: the SAME validation the deploy route runs — manifest `.strict()` +
     // every flow (schema/expression/structure) — returning ALL errors at once.
-    const { url, tenant, project, token } = resolveTarget(flags, packDir);
-    console.log(`→ Validating against ${tenant}/${project} @ ${url} …`);
-    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/projects/${project}/packs/validate`, {
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    console.log(`→ Validating against ${targetLabel(t)} @ ${url} …`);
+    const res = await fetchOrDie(`${url}/api/self/p/packs/validate`, {
         method: 'POST',
-        headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+        headers: { 'content-type': 'application/json', ...authHeaders(t) },
         body: JSON.stringify({ files }),
     }, 'remote validate');
     const text = await res.text();
@@ -467,6 +533,12 @@ async function cmdValidate(flags) {
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
         process.exit(1);
     }
+    const warnings = (json?.warnings ?? []);
+    if (warnings.length) {
+        console.log(`  ⚠ ${warnings.length} warning${warnings.length === 1 ? '' : 's'} (won't block deploy):`);
+        for (const w of warnings)
+            console.log(`    ⚠ [${w.where}] ${w.message}`);
+    }
     if (json?.ok) {
         console.log(`✓ ${id}@${version} passes the platform's FULL validation — deploy won't reject on schema.`);
         return;
@@ -486,55 +558,83 @@ async function cmdValidate(flags) {
     }
     process.exit(1);
 }
-function cmdLogin(flags) {
-    const url = flags.url ?? process.env.PACK_PLATFORM_URL ?? die('usage: octwin login --url <platformUrl> --token <t>');
+async function cmdLogin(flags) {
+    const rawUrl = flags.url ?? process.env.PACK_PLATFORM_URL ?? die('usage: octwin login --url <platformUrl> --token <t>');
+    const url = rawUrl.replace(/\/$/, '');
     const token = flags.token ?? process.env.PACK_TOKEN ?? die('missing --token');
     const creds = readCreds();
-    creds[url.replace(/\/$/, '')] = token;
+    creds[url] = token;
     writeCreds(creds);
     console.log(`✓ Saved token for ${url}`);
+    // Best-effort: echo what the token reaches (workspace + project pin + scopes)
+    // so a fresh token self-identifies without a second `octwin whoami`. A network
+    // failure never fails the save — the token is stored regardless.
+    try {
+        const res = await fetch(`${url}/api/self/t/whoami`, { headers: { authorization: `Bearer ${token}` } });
+        if (res.ok) {
+            const j = await res.json();
+            const scopes = Array.isArray(j.scopes) && j.scopes.length ? ` · scopes: ${j.scopes.join(', ')}` : '';
+            console.log(`  → workspace '${j.tenant_slug}'${j.project_slug ? `, pinned to project '${j.project_slug}'` : ''}${scopes}`);
+        }
+        else if (res.status === 401 || res.status === 403) {
+            console.log(`  ⚠ token saved, but the platform rejected it (HTTP ${res.status}) — check it's a current oct_… token`);
+        }
+    }
+    catch { /* platform unreachable — the token is saved regardless */ }
 }
-/** Resolve platform url + tenant + project + token: flags > pack.json > env > saved login. */
+/** Bearer auth + the optional self-surface overrides, as request headers. */
+function authHeaders(t) {
+    const h = { authorization: `Bearer ${t.token}` };
+    if (t.tenant)
+        h['x-octwin-tenant'] = t.tenant;
+    if (t.project)
+        h['x-octwin-project'] = t.project;
+    return h;
+}
+/** Resolve platform url + token (+ optional tenant/project overrides):
+ *  flags > pack.json > env > saved login. Tenant is derived from the token
+ *  server-side, so only url + token are required. */
 function resolveTarget(flags, packDir) {
     const cfg = readPackConfig(packDir);
     const url = (flags.url ?? process.env.PACK_PLATFORM_URL ?? cfg.platform_url ?? '').replace(/\/$/, '');
-    const tenant = flags.tenant ?? process.env.PACK_TENANT ?? cfg.tenant ?? '';
-    const project = flags.project ?? process.env.PACK_PROJECT ?? cfg.project ?? 'main';
+    const tenant = flags.tenant || process.env.PACK_TENANT || cfg.tenant || undefined;
+    const project = flags.project || process.env.PACK_PROJECT || cfg.project || undefined;
     const token = flags.token ?? process.env.PACK_TOKEN ?? readCreds()[url] ?? '';
     if (!url)
         die('no platform url — set it in pack.json, --url, or PACK_PLATFORM_URL');
-    if (!tenant)
-        die('no tenant — set it in pack.json, --tenant, or PACK_TENANT');
     if (!token)
-        die('no token — generate a deploy token in the console (Settings → API tokens), then `octwin login --url <url> --token oct_…` or pass --token');
-    return { url, tenant, project, token };
+        die('no token — generate an API token in the console (Settings → API tokens), then `octwin login --url <url> --token oct_…` or pass --token');
+    return { url, token, tenant, project };
 }
-/** Non-fatal `resolveTarget`: returns null (never dies) when any of url/tenant/token
- *  is missing. Used by the fail-silent KB-staleness observer, which must never
+/** Non-fatal `resolveTarget`: returns null (never dies) when url or token is
+ *  missing. Used by the fail-silent KB-staleness observer, which must never
  *  interrupt a command over a config gap. */
 function resolveTargetOrNull(flags, packDir) {
     const cfg = readPackConfig(packDir);
     const url = (flags.url ?? process.env.PACK_PLATFORM_URL ?? cfg.platform_url ?? '').replace(/\/$/, '');
-    const tenant = flags.tenant ?? process.env.PACK_TENANT ?? cfg.tenant ?? '';
-    const project = flags.project ?? process.env.PACK_PROJECT ?? cfg.project ?? 'main';
+    const tenant = flags.tenant || process.env.PACK_TENANT || cfg.tenant || undefined;
+    const project = flags.project || process.env.PACK_PROJECT || cfg.project || undefined;
     const token = flags.token ?? process.env.PACK_TOKEN ?? readCreds()[url] ?? '';
-    if (!url || !tenant || !token)
+    if (!url || !token)
         return null;
-    return { url, tenant, project, token };
+    return { url, token, tenant, project };
 }
 async function cmdWhoami(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const { url, tenant, token } = resolveTarget(flags, packDir);
-    console.log(`→ Checking the saved token against '${tenant}' @ ${url} …`);
-    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/packs`, { headers: { authorization: `Bearer ${token}` } }, 'token check');
+    const t = resolveTarget(flags, packDir);
+    console.log(`→ Checking the token against ${t.url} …`);
+    const res = await fetchOrDie(`${t.url}/api/self/t/whoami`, { headers: authHeaders(t) }, 'token check');
     if (res.ok) {
-        console.log(`✓ Token valid for tenant '${tenant}' at ${url} (${token.startsWith('oct_') ? 'deploy token' : 'session token'})`);
+        const j = await res.json();
+        console.log(`✓ Token valid — workspace '${j.tenant_slug}'${j.project_slug ? `, pinned to project '${j.project_slug}'` : ''} (${j.kind === 'api_token' ? 'API token' : 'session'})`);
+        if (Array.isArray(j.scopes))
+            console.log(`  scopes: ${j.scopes.length ? j.scopes.join(', ') : '(none)'}`);
         return;
     }
     const why = res.status === 401 ? 'invalid / expired / revoked token'
-        : res.status === 403 ? 'token not authorized for this tenant'
+        : res.status === 403 ? 'token not authorized for this workspace'
             : await res.text();
-    die(`token check failed for '${tenant}' (HTTP ${res.status}) — ${why}`);
+    die(`token check failed (HTTP ${res.status}) — ${why}`);
 }
 /**
  * Read the deploy SSE stream, printing each progress frame's message live, and
@@ -547,6 +647,11 @@ async function readDeployProgress(body) {
     const decoder = new TextDecoder();
     let buf = '';
     let terminal = null;
+    // Non-terminal frames with `status:'error'` are step failures the install
+    // SOFTENS to non-fatal (e.g. a demo-seed row) — the reconcile keeps going and
+    // still emits a `done`. We collect them so the deploy is NOT reported as a
+    // clean ✓ when a step actually failed (the false-✓ trap).
+    const stepErrors = [];
     for (;;) {
         const { done, value } = await reader.read();
         if (done)
@@ -570,14 +675,18 @@ async function readDeployProgress(body) {
                 terminal = ev;
                 continue;
             }
-            if (ev.message)
-                console.log(`   ${ev.status === 'error' ? '⚠' : '·'} ${ev.message}`);
+            if (ev.message) {
+                const isErr = ev.status === 'error';
+                if (isErr)
+                    stepErrors.push(ev.message);
+                console.log(`   ${isErr ? '⚠' : '·'} ${ev.message}`);
+            }
         }
     }
-    return terminal;
+    return { terminal, stepErrors };
 }
-function printDeploySuccess(id, version, tenant, project, r) {
-    console.log(`✓ Deployed ${id}@${version} and installed onto ${tenant}/${project}`);
+function printDeploySuccess(id, version, t, r) {
+    console.log(`✓ Deployed ${id}@${version} and installed onto ${targetLabel(t)}`);
     if (r?.warning)
         console.log(`  ⚠ ${r.warning}`);
     const s = r?.summary;
@@ -594,29 +703,39 @@ function printDeploySuccess(id, version, tenant, project, r) {
         if (parts.length)
             console.log(`  Seeded: ${parts.join(', ')}`);
     }
-    console.log(`\nChat with it on your tenant (web widget / console test page for ${tenant}/${project}).`);
+    console.log(`\nChat with it: octwin chat "hi" --as tester   (or the web widget / console test page).`);
 }
 async function cmdDeploy(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const { url, tenant, project, token } = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
     const { id, version, files } = localValidate(packDir);
-    const endpoint = `${url}/api/admin/tenants/${tenant}/projects/${project}/packs/deploy`;
+    const endpoint = `${url}/api/self/p/packs/deploy`;
     const seed = flags.seed === true;
-    console.log(`→ Deploying ${id}@${version} (${Object.keys(files).length} files) to ${tenant}/${project}${seed ? ' — with demo seed' : ''} …`);
+    console.log(`→ Deploying ${id}@${version} (${Object.keys(files).length} files) to ${targetLabel(t)}${seed ? ' — with demo seed' : ''} …`);
     const res = await fetchOrDie(endpoint, {
         method: 'POST',
         // Ask for a progress stream; the platform falls back to plain JSON if it
         // (or an error before any progress) can't stream — handled below.
-        headers: { 'content-type': 'application/json', accept: 'text/event-stream', authorization: `Bearer ${token}` },
+        headers: { 'content-type': 'application/json', accept: 'text/event-stream', ...authHeaders(t) },
         body: JSON.stringify({ files, seed }),
     }, 'deploy');
     // Streaming path — live install + seed progress (image generation can take a
     // while, so `--seed` prints per-record / per-image lines as they happen).
     if (res.ok && (res.headers.get('content-type') ?? '').includes('text/event-stream') && res.body) {
-        const final = await readDeployProgress(res.body);
+        const { terminal: final, stepErrors } = await readDeployProgress(res.body);
         if (!final || final.stage === 'error')
             die(`deploy failed${final?.message ? `: ${final.message}` : ' (stream ended early)'}`);
-        printDeploySuccess(id, version, tenant, project, final);
+        printDeploySuccess(id, version, t, final);
+        if (stepErrors.length) {
+            // The pack IS installed, but a step (e.g. the demo seed) failed — say so
+            // plainly and exit non-zero so CI / a `deploy && chat` chain doesn't treat
+            // an incomplete install as a clean success.
+            console.error(`\n⚠ Deployed with ${stepErrors.length} warning${stepErrors.length === 1 ? '' : 's'} — data may be incomplete:`);
+            for (const e of stepErrors)
+                console.error(`   • ${e}`);
+            process.exit(1);
+        }
         return;
     }
     // Non-streaming path — plain JSON (older platform, or an error thrown before
@@ -635,11 +754,12 @@ async function cmdDeploy(flags) {
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
         process.exit(1);
     }
-    printDeploySuccess(id, version, tenant, project, json);
+    printDeploySuccess(id, version, t, json);
 }
 async function cmdStatus(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const { url, tenant, project, token } = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
     const manifestPath = join(packDir, 'manifest.yaml');
     if (!existsSync(manifestPath))
         die('no manifest.yaml in the pack directory (run from your pack dir or pass --dir)');
@@ -648,9 +768,9 @@ async function cmdStatus(flags) {
         die('manifest.yaml must declare a string `id`');
     const id = doc.id;
     const localVersion = typeof doc?.version === 'string' ? doc.version : '?';
-    console.log(`→ Checking ${id}@${localVersion} on ${tenant}/${project} @ ${url} …`);
-    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/projects/${project}/packs/${id}/runtime`, {
-        headers: { authorization: `Bearer ${token}` },
+    console.log(`→ Checking ${id}@${localVersion} on ${targetLabel(t)} @ ${url} …`);
+    const res = await fetchOrDie(`${url}/api/self/p/packs/${id}/runtime`, {
+        headers: authHeaders(t),
     }, 'status check');
     const text = await res.text();
     let json;
@@ -662,13 +782,13 @@ async function cmdStatus(flags) {
     }
     if (!res.ok) {
         if (res.status === 404)
-            die(`'${id}' is not installed on ${tenant}/${project} yet — run \`octwin deploy\` first`);
+            die(`'${id}' is not installed on ${targetLabel(t)} yet — run \`octwin deploy\` first`);
         console.error(`✗ status check failed (HTTP ${res.status})`);
         printAuthHint(res.status, url);
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
         process.exit(1);
     }
-    console.log(`${id} on ${tenant}/${project} @ ${url}`);
+    console.log(`${id} on ${targetLabel(t)} @ ${url}`);
     console.log(`  installed version : ${json.installed_version}`);
     console.log(`  live on instance  : registered=${json.registered}  source=${json.source}  loaded=${json.loaded_version ?? '(none)'}`);
     console.log(`  flows             : ${(json.flows ?? []).join(', ') || '(none)'}`);
@@ -687,10 +807,11 @@ async function cmdStatus(flags) {
 }
 async function cmdPlatformKb(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const { url, tenant, token } = resolveTarget(flags, packDir);
-    console.log(`→ Pulling the platform capability reference from '${tenant}' @ ${url} …`);
-    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/octwin-platform-kb`, {
-        headers: { authorization: `Bearer ${token}` },
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    console.log(`→ Pulling the platform capability reference from ${url} …`);
+    const res = await fetchOrDie(`${url}/api/self/t/octwin-platform-kb`, {
+        headers: authHeaders(t),
     }, 'platform-kb pull');
     const text = await res.text();
     if (!res.ok) {
@@ -755,8 +876,8 @@ async function cmdPlatformKb(flags) {
 /** GET an admin endpoint with the deploy token; returns `{ status, json }`.
  *  Dies (with the URL) on a network failure; auth failures return so the
  *  caller can add command-specific context on top of `authFailureHint`. */
-async function apiGet(endpoint, token) {
-    const res = await fetchOrDie(endpoint, { headers: { authorization: `Bearer ${token}` } }, 'request');
+async function apiGet(endpoint, t) {
+    const res = await fetchOrDie(endpoint, { headers: authHeaders(t) }, 'request');
     const text = await res.text();
     let json;
     try {
@@ -767,16 +888,22 @@ async function apiGet(endpoint, token) {
     }
     return { status: res.status, json };
 }
+/** A progress-line label for the target workspace. The token names the tenant, so
+ *  we surface at most the project (when pinned or overridden by `--project`). */
+function targetLabel(t) {
+    return t.project ? `project '${t.project}'` : 'your workspace';
+}
 /** `octwin records [entity] [id]` — inspect the pack's XRM data (needs a `records:read` token). */
 async function cmdRecords(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const { url, tenant, project, token } = resolveTarget(flags, packDir);
-    const base = `${url}/api/admin/tenants/${tenant}/projects/${project}`;
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p`;
     const entity = flags._[0];
     const recordId = flags._[1];
-    console.log(`→ Reading ${recordId ? `${entity} record ${recordId}` : entity ? `${entity} records` : 'the entity catalog'} from ${tenant}/${project} …`);
+    console.log(`→ Reading ${recordId ? `${entity} record ${recordId}` : entity ? `${entity} records` : 'the entity catalog'} from ${targetLabel(t)} …`);
     if (!entity) {
-        const { status, json } = await apiGet(`${base}/xrm/entities`, token);
+        const { status, json } = await apiGet(`${base}/xrm/entities`, t);
         if (status !== 200)
             die(`could not read entities (HTTP ${status})`);
         if (json?.has_xrm === false) {
@@ -788,7 +915,7 @@ async function cmdRecords(flags) {
             console.log('No entities visible — mint a token with the `records:read` scope to inspect data.');
             return;
         }
-        console.log(`Entities in ${tenant}/${project}:`);
+        console.log(`Entities in ${targetLabel(t)}:`);
         for (const e of ents)
             console.log(`  ${e.entity}  (${e.open_count ?? 0} records)`);
         console.log('\nList records:  octwin records <entity>');
@@ -796,16 +923,14 @@ async function cmdRecords(flags) {
     }
     if (!recordId) {
         const limit = flags.limit ?? '50';
-        const { status, json } = await apiGet(`${base}/xrm/records?entity=${encodeURIComponent(entity)}&limit=${limit}`, token);
-        if (status === 403)
-            die('forbidden — the paged record list needs the `records` plan feature on this tenant');
+        const { status, json } = await apiGet(`${base}/xrm/records?entity=${encodeURIComponent(entity)}&limit=${limit}`, t);
         if (status !== 200) {
             // Always show the server's reason (it names the unknown entity). Cases are
             // casework (worklist), not pack-declared XRM — point at the right command.
             if (entity === 'case' || entity === 'cases') {
                 console.error(`  '${entity}' is casework (worklist), not a pack-declared XRM entity — inspect tickets with: octwin cases`);
             }
-            die(`could not read records (HTTP ${status})${errDetail(json)}${status === 401 ? ` — ${authFailureHint(status, url)}` : ''}`);
+            die(`could not read records (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
         }
         const rows = (json?.records ?? []);
         console.log(`${entity}: ${json?.total ?? rows.length} record(s)`);
@@ -815,32 +940,29 @@ async function cmdRecords(flags) {
             console.log(`  #${r.record_number ?? '?'}  ${r.title ?? '(untitled)'}${r.stage ? `  [${r.stage}]` : ''}  ${r.id}`);
         return;
     }
-    const { status, json } = await apiGet(`${base}/xrm/records/${encodeURIComponent(recordId)}`, token);
-    if (status === 403)
-        die('forbidden — mint a token with the `records:read` scope');
+    const { status, json } = await apiGet(`${base}/xrm/records/${encodeURIComponent(recordId)}`, t);
     if (status === 404)
         die(`record '${recordId}' not found`);
-    if (status === 401)
-        die(`could not read record — ${authFailureHint(401, url)}`);
     if (status !== 200)
-        die(`could not read record (HTTP ${status})`);
+        die(`could not read record (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     console.log(JSON.stringify(json?.record ?? json, null, 2));
 }
 /** `octwin logs [conversationId] [--as <handle>] [--json]` — list conversations
  *  or show one's event timeline (full text + the renders each turn produced). */
 async function cmdLogs(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const { url, tenant, project, token } = resolveTarget(flags, packDir);
-    const base = `${url}/api/admin/tenants/${tenant}/projects/${project}`;
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p`;
     const convId = flags._[0];
     const asJson = flags.json === true;
     const asHandle = typeof flags.as === 'string' ? flags.as : undefined;
     if (!asJson)
-        console.log(`→ Reading ${convId ? `conversation ${convId}` : 'recent conversations'} from ${tenant}/${project} …`);
+        console.log(`→ Reading ${convId ? `conversation ${convId}` : 'recent conversations'} from ${targetLabel(t)} …`);
     if (!convId) {
-        const { status, json } = await apiGet(`${base}/conversations?limit=50`, token);
+        const { status, json } = await apiGet(`${base}/conversations?limit=50`, t);
         if (status !== 200)
-            die(`could not read conversations (HTTP ${status})${errDetail(json)} — ${authFailureHint(status, url)}`);
+            die(`could not read conversations (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
         let convs = (json?.conversations ?? []);
         if (asHandle)
             convs = convs.filter((c) => c.contact?.channel_contact_handle === asHandle);
@@ -852,7 +974,7 @@ async function cmdLogs(flags) {
             console.log(JSON.stringify(convs, null, 2));
             return;
         }
-        console.log(`Recent conversations in ${tenant}/${project}${asHandle ? ` (handle: ${asHandle})` : ''}:`);
+        console.log(`Recent conversations in ${targetLabel(t)}${asHandle ? ` (handle: ${asHandle})` : ''}:`);
         for (const c of convs) {
             const handle = c.contact?.channel_contact_handle ?? '?';
             const name = c.contact?.display_name && c.contact.display_name !== handle ? ` (${c.contact.display_name})` : '';
@@ -862,11 +984,11 @@ async function cmdLogs(flags) {
         console.log('\nView a timeline:  octwin logs <conversationId>   (add --json for full payloads)');
         return;
     }
-    const { status, json } = await apiGet(`${base}/conversations/${encodeURIComponent(convId)}`, token);
+    const { status, json } = await apiGet(`${base}/conversations/${encodeURIComponent(convId)}`, t);
     if (status === 404)
         die(`conversation '${convId}' not found`);
     if (status !== 200)
-        die(`could not read conversation (HTTP ${status})${errDetail(json)} — ${authFailureHint(status, url)}`);
+        die(`could not read conversation (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     const events = (json?.events ?? []);
     if (asJson) {
         console.log(JSON.stringify(events, null, 2));
@@ -1017,12 +1139,33 @@ async function cmdChat(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const cfg = readPackConfig(packDir);
     const url = (flags.url ?? process.env.PACK_PLATFORM_URL ?? cfg.platform_url ?? '').replace(/\/$/, '');
-    const tenant = flags.tenant ?? process.env.PACK_TENANT ?? cfg.tenant ?? '';
-    const project = flags.project ?? process.env.PACK_PROJECT ?? cfg.project ?? 'main';
     if (!url)
         die('no platform url — set it in pack.json, --url, or PACK_PLATFORM_URL');
+    let tenant = flags.tenant || process.env.PACK_TENANT || cfg.tenant || '';
+    let project = flags.project || process.env.PACK_PROJECT || cfg.project || '';
+    // The dev web channel is tenant/project-pathed (it simulates an end-user on a
+    // specific project). When they aren't configured, derive them from the token —
+    // its tenant + optional project pin — via the slug-free `/api/self/t/whoami`.
+    if (!tenant || !project) {
+        const token = flags.token ?? process.env.PACK_TOKEN ?? readCreds()[url] ?? '';
+        if (token) {
+            try {
+                const who = await fetch(`${url}/api/self/t/whoami`, {
+                    headers: { authorization: `Bearer ${token}`, ...(tenant ? { 'x-octwin-tenant': tenant } : {}) },
+                });
+                if (who.ok) {
+                    const j = await who.json();
+                    tenant = tenant || (j.tenant_slug ?? '');
+                    project = project || (j.project_slug ?? '');
+                }
+            }
+            catch { /* fall through to the checks below */ }
+        }
+    }
     if (!tenant)
-        die('no tenant — set it in pack.json, --tenant, or PACK_TENANT');
+        die('no tenant — set --tenant / PACK_TENANT / pack.json, or pass a --token to derive it');
+    if (!project)
+        project = 'main';
     const from = flags.as ?? 'cli-tester';
     const asJson = flags.json === true;
     const tapId = typeof flags.tap === 'string' ? flags.tap : undefined;
@@ -1136,7 +1279,8 @@ async function cmdMedia(flags) {
     if (sub !== 'generate')
         die('usage: octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]');
     const packDir = resolve(flags.dir ?? '.');
-    const { url, tenant, project, token } = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
     const prompt = flags._[1];
     if (!prompt)
         die('usage: octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]');
@@ -1144,10 +1288,10 @@ async function cmdMedia(flags) {
     const size = typeof flags.size === 'string' ? flags.size : undefined;
     const out = typeof flags.out === 'string' ? flags.out : undefined;
     if (!asJson)
-        console.log(`→ Generating an image on '${tenant}/${project}' @ ${url} …`);
-    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/projects/${project}/media/generate`, {
+        console.log(`→ Generating an image on ${targetLabel(t)} @ ${url} …`);
+    const res = await fetchOrDie(`${url}/api/self/p/media/generate`, {
         method: 'POST',
-        headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+        headers: { 'content-type': 'application/json', ...authHeaders(t) },
         body: JSON.stringify({ prompt, ...(size ? { size } : {}) }),
     }, 'media generate');
     const text = await res.text();
@@ -1191,19 +1335,22 @@ async function cmdMedia(flags) {
  *  the aggregate inbox, one case + its timeline, or the queue list. */
 async function cmdCases(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const { url, tenant, project, token } = resolveTarget(flags, packDir);
-    const base = `${url}/api/admin/tenants/${tenant}/projects/${project}`;
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p`;
     const caseId = flags._[0];
     const asJson = flags.json === true;
     if (!asJson)
-        console.log(`→ Reading ${flags.queues === true ? 'case queues' : caseId ? `case ${caseId}` : 'the case inbox'} from ${tenant}/${project} …`);
+        console.log(`→ Reading ${flags.queues === true ? 'case queues' : caseId ? `case ${caseId}` : 'the case inbox'} from ${targetLabel(t)} …`);
     const caseFail = (what, status, json) => {
+        // A 403 here can also be an RBAC gap the scope hint can't see — a role whose
+        // grants don't reach the queue passes the scope gate and still gets nothing.
         if (status === 403)
-            die(`forbidden — casework needs the 'cases' plan feature on this tenant, and a role whose grants reach the queue`);
-        die(`could not read ${what} (HTTP ${status})${errDetail(json)}${status === 401 ? ` — ${authFailureHint(status, url)}` : ''}`);
+            console.error('  → (a role whose grants reach the queue is also required)');
+        die(`could not read ${what} (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     };
     if (flags.queues === true) {
-        const { status, json } = await apiGet(`${base}/case-queues`, token);
+        const { status, json } = await apiGet(`${base}/case-queues`, t);
         if (status !== 200)
             caseFail('case queues', status, json);
         if (asJson) {
@@ -1211,7 +1358,7 @@ async function cmdCases(flags) {
             return;
         }
         const queues = (json?.queues ?? []);
-        console.log(`Case queues in ${tenant}/${project}:`);
+        console.log(`Case queues in ${targetLabel(t)}:`);
         for (const q of queues)
             console.log(`  ${q.key}${q.name ? `  (${q.name})` : ''}  ${q.open_count} open`);
         if (json?.unrouted_open_count)
@@ -1220,7 +1367,7 @@ async function cmdCases(flags) {
     }
     if (!caseId) {
         const limit = flags.limit ?? '50';
-        const { status, json } = await apiGet(`${base}/cases?limit=${limit}`, token);
+        const { status, json } = await apiGet(`${base}/cases?limit=${limit}`, t);
         if (status !== 200)
             caseFail('cases', status, json);
         if (asJson) {
@@ -1228,7 +1375,7 @@ async function cmdCases(flags) {
             return;
         }
         const rows = (json?.cases ?? []);
-        console.log(`Cases in ${tenant}/${project}: ${json?.total ?? rows.length} total`);
+        console.log(`Cases in ${targetLabel(t)}: ${json?.total ?? rows.length} total`);
         if (rows.length === 0)
             console.log('  (none)');
         for (const c of rows) {
@@ -1238,7 +1385,7 @@ async function cmdCases(flags) {
         console.log('\nOne case + timeline:  octwin cases <caseId>    queues:  octwin cases --queues');
         return;
     }
-    const { status, json } = await apiGet(`${base}/cases/${encodeURIComponent(caseId)}`, token);
+    const { status, json } = await apiGet(`${base}/cases/${encodeURIComponent(caseId)}`, t);
     if (status === 404)
         die(`case '${caseId}' not found`);
     if (status !== 200)
@@ -1269,6 +1416,483 @@ async function cmdCases(flags) {
         console.log(`  Decisions: ${dispositions.map((d) => `${d.action}${d.next_status ? `→${d.next_status}` : ''}`).join(', ')}`);
     }
 }
+// ── money formatting (orders / catalog) ─────────────────────────────────────
+/** Format a MAJOR-unit decimal amount as currency — the catalog's `price` shape.
+ *  Mirrors the console's `fmtAmount` (console/src/lib/money.ts) so an amount reads
+ *  the same in the terminal as on the page. */
+function fmtAmount(value, currency) {
+    if (value == null)
+        return '—';
+    if (!currency)
+        return value.toFixed(2);
+    try {
+        return new Intl.NumberFormat('en', { style: 'currency', currency }).format(value);
+    }
+    catch {
+        return `${value.toFixed(2)} ${currency}`;
+    }
+}
+/** Format MINOR units (the offset-100 `*_minor` ints every order field is projected
+ *  to on the wire — see `toOrderView`) as currency. `fmtAmount(minor / 100, …)`. */
+function fmtMinor(minor, currency) {
+    if (minor == null)
+        return '—';
+    return fmtAmount(minor / 100, currency);
+}
+/** Human wording for a governed `source` — the layer that won the cascade
+ *  (per-project override > platform default > pack manifest default). The four
+ *  values mirror the platform's `GovernedSource` union exactly. */
+const GOVERNED_SOURCE_LABEL = {
+    project: 'this project overrides it',
+    platform: 'a PLATFORM default overrides the pack',
+    pack: 'the pack manifest value is in force',
+    unset: 'no value at any layer',
+};
+function showValue(v) {
+    if (v === undefined || v === null)
+        return '(unset)';
+    return typeof v === 'string' ? v : JSON.stringify(v);
+}
+/** Print one governed setting as `key: <effective>  [why]`, and — when the pack's
+ *  own declared value is NOT what runs — an explicit second line naming what the
+ *  pack asked for. That override is invisible from the pack source, which is the
+ *  whole reason this command exists. */
+function printGoverned(label, g) {
+    if (!g)
+        return;
+    const source = typeof g.source === 'string' ? g.source : '';
+    console.log(`    ${label.padEnd(22)} ${showValue(g.effective)}   [${GOVERNED_SOURCE_LABEL[source] ?? source ?? '?'}]`);
+    // Warn only when a higher layer displaced the pack's declared value with a
+    // DIFFERENT one. A platform default that happens to equal the pack's value has
+    // changed nothing an author needs to know about.
+    const displaced = (source === 'project' || source === 'platform')
+        && g.pack_default !== undefined
+        && JSON.stringify(g.pack_default) !== JSON.stringify(g.effective);
+    if (displaced)
+        console.log(`      ⚠ your pack declares ${showValue(g.pack_default)} — it is NOT in force`);
+    if (g.opted_out)
+        console.log('      (this workspace is opted OUT of the platform default for this key)');
+}
+/** `octwin agents [agentRef] [--prompt] [--json]` — the agent roster with the
+ *  EFFECTIVE model/memory settings and which layer won, plus (`--prompt`) the exact
+ *  system prompt the LLM sees for this project. Needs an `agents:read` token. */
+async function cmdAgents(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/agents`;
+    const ref = flags._[0];
+    const asJson = flags.json === true;
+    const wantPrompt = flags.prompt === true;
+    if (wantPrompt && !ref)
+        die('usage: octwin agents <packId::agentId> --prompt   (name the agent — `octwin agents` lists them)');
+    if (!asJson)
+        console.log(`→ Reading ${ref ? `agent ${ref}` : 'the agent roster'} from ${targetLabel(t)} …`);
+    // --prompt — the resolved system prompt (pack instructions + platform protocol +
+    // the per-project overlay). No LLM call; pure resolution server-side.
+    if (wantPrompt) {
+        const { status, json } = await apiGet(`${base}/${encodeURIComponent(ref)}/preview-prompt`, t);
+        if (status === 404)
+            die(`agent '${ref}' not found — run \`octwin agents\` for the roster`);
+        // 503 = the pack is installed but not warm on this instance yet (same trap
+        // `octwin status` explains): the agent loads on the next inbound.
+        if (status === 503)
+            die(`'${ref}' is not registered with Mastra on the instance you hit yet — it loads on the next inbound (chat once, then retry)`);
+        if (status !== 200)
+            die(`could not resolve the prompt (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        console.log(`Resolved system prompt for ${json?.agent?.pack_id}::${json?.agent?.pack_agent_id} (${json?.bytes ?? '?'} bytes`
+            + `${json?.has_overlay ? ', includes this project\'s overlay' : ', no project overlay'}):\n`);
+        console.log(json?.resolved_prompt ?? '(empty)');
+        return;
+    }
+    if (!ref) {
+        const { status, json } = await apiGet(base, t);
+        if (status !== 200)
+            die(`could not read agents (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const agents = (json?.agents ?? []);
+        if (agents.length === 0) {
+            console.log('No agents — is a pack installed on this project? (`octwin status`)');
+            return;
+        }
+        console.log(`Agents in ${targetLabel(t)}:`);
+        for (const a of agents) {
+            console.log(`  ${a.pack_id}::${a.pack_agent_id}  "${a.display_name}"${a.enabled === false ? '  [DISABLED]' : ''}`);
+            printGoverned('model', a.governed?.model);
+            if (a.last_error_at)
+                console.log(`    last error: ${a.last_error_at} — ${a.last_error_reason ?? '(no reason)'}`);
+        }
+        console.log('\nOne agent + its full settings:  octwin agents <packId::agentId>');
+        console.log('The prompt the LLM sees:         octwin agents <packId::agentId> --prompt');
+        return;
+    }
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(ref)}`, t);
+    if (status === 404)
+        die(`agent '${ref}' not found — run \`octwin agents\` for the roster`);
+    if (status !== 200)
+        die(`could not read agent (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    console.log(`${json.pack_id}::${json.pack_agent_id}  "${json.display_name}"${json.enabled === false ? '  [DISABLED]' : ''}`);
+    console.log('  Governed settings (project override > platform default > pack manifest):');
+    printGoverned('model', json.governed?.model);
+    printGoverned('memory.last_messages', json.governed?.last_messages);
+    printGoverned('working_memory', json.governed?.working_memory_enabled);
+    console.log(`  tools: ${(json.available_tools ?? []).join(', ') || '(none)'}`);
+    console.log(`  instructions overlay: ${json.instructions_overlay ? `${String(json.instructions_overlay).length} chars (project-specific)` : '(none)'}`);
+    if (json.last_invoked_at)
+        console.log(`  last invoked: ${json.last_invoked_at}`);
+    if (json.last_error_at)
+        console.log(`  last error:   ${json.last_error_at} — ${json.last_error_reason ?? '(no reason)'}`);
+    console.log(`\nThe prompt the LLM actually sees: octwin agents ${ref} --prompt`);
+}
+// ── orders: the commerce lifecycle a conversation produces ───────────────────
+/** Why a `pending` / `none` payment is usually CORRECT, not a bug. The forward
+ *  payment lifecycle is webhook-owned (`payment_status` is deliberately not
+ *  patchable — only `refund` is an operator move), and the default driver is the
+ *  gateway-less `ManualPaymentAdapter`, on which `payment_request` takes its `empty`
+ *  port and mutates nothing. Settling a payment headlessly has no path today — see
+ *  docs/BACKLOG.md → "Headless payment settle" (a `--settle` flag lands here once
+ *  the platform grows a manual-driver-only reconcile endpoint). */
+function printPaymentNote(paymentStatus) {
+    if (paymentStatus !== 'pending' && paymentStatus !== 'none')
+        return;
+    console.log(`  → payment_status '${paymentStatus}' is expected without a live gateway: the forward payment`);
+    console.log('    lifecycle is WEBHOOK-owned (not patchable), and the default `manual` driver has no hosted');
+    console.log('    checkout — so `payment_request` takes its `empty` port and the flow should offer');
+    console.log('    pay-on-delivery. Refund is the one operator-driven move.');
+}
+/** `octwin orders [referenceId] [--status s] [--payment p] [--limit n] [--json]` —
+ *  the orders a conversation created: money breakdown, payment state, allowed
+ *  transitions. Needs an `orders:read` token + the `orders` plan feature. */
+async function cmdOrders(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/orders`;
+    const referenceId = flags._[0];
+    const asJson = flags.json === true;
+    if (!asJson)
+        console.log(`→ Reading ${referenceId ? `order ${referenceId}` : 'orders'} from ${targetLabel(t)} …`);
+    if (!referenceId) {
+        const q = new URLSearchParams({ limit: flags.limit ?? '50' });
+        if (typeof flags.status === 'string')
+            q.set('status', flags.status);
+        if (typeof flags.payment === 'string')
+            q.set('payment', flags.payment);
+        const { status, json } = await apiGet(`${base}?${q.toString()}`, t);
+        if (status !== 200)
+            die(`could not read orders (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const rows = (json?.orders ?? []);
+        console.log(`Orders in ${targetLabel(t)}: ${json?.total ?? rows.length} total`);
+        if (rows.length === 0)
+            console.log('  (none — drive a cart to `cart_submit` with `octwin chat`, or seed demo data)');
+        for (const o of rows) {
+            const who = o.contact?.channel_contact_handle ?? o.contact?.display_name ?? '—';
+            console.log(`  #${o.record_number}  ${o.status}/${o.payment_status}  ${fmtMinor(o.total_minor, o.currency)}  ${who}  ${o.reference_id}`);
+        }
+        console.log('\nOne order + its money breakdown:  octwin orders <reference_id>');
+        return;
+    }
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(referenceId)}`, t);
+    if (status === 404)
+        die(`order '${referenceId}' not found (pass the opaque reference_id, not the #number)`);
+    if (status !== 200)
+        die(`could not read order (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    const o = json?.order ?? {};
+    const cur = o.currency;
+    console.log(`Order #${o.record_number}  ${o.status}  payment: ${o.payment_status}`);
+    console.log(`  reference: ${o.reference_id}${o.payment_ref ? `   payment_ref: ${o.payment_ref}` : ''}`);
+    for (const it of (o.items ?? [])) {
+        console.log(`    ${it.quantity} × ${it.name ?? it.retailer_id}  @ ${fmtMinor(it.amount_minor, it.currency || cur)}`);
+    }
+    console.log(`  subtotal ${fmtMinor(o.subtotal_minor, cur)}`
+        + `   tax ${fmtMinor(o.tax_minor, cur)}`
+        + `   shipping ${fmtMinor(o.shipping_minor, cur)}`
+        + `   discount ${fmtMinor(o.discount_minor, cur)}`);
+    console.log(`  TOTAL    ${fmtMinor(o.total_minor, cur)}`);
+    if (o.note)
+        console.log(`  note: ${o.note}`);
+    const transitions = (json?.transitions ?? []);
+    console.log(`  allowed transitions: ${transitions.join(', ') || '(none — terminal)'}`);
+    printPaymentNote(String(o.payment_status ?? ''));
+}
+// ── analytics: the generic per-entity funnel (any pipelined entity) ──────────
+const ANALYTICS_MODES = ['funnel', 'overview', 'milestones', 'trends', 'cost'];
+/** Both "unknown/non-pipelined entity" and "your role lacks the grant" answer
+ *  200 + `has_data:false` (a deliberate empty state, never a 403) — so a bare
+ *  "no data" would hide the real cause. Name both. */
+function printNoAnalyticsData(entity) {
+    console.log(`No analytics for '${entity}'. Either:`);
+    console.log(`  • '${entity}' isn't declared with a \`pipeline:\` (a funnel needs stages), or`);
+    console.log(`  • your token's role has no \`view\` grant on \`record.${entity}\`.`);
+    console.log('Run `octwin analytics` for the entities that DO carry a pipeline.');
+}
+/** `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost]
+ *  [--stage <id>] [--json]` — stage conversion over ANY pipelined XRM entity
+ *  (orders, carts, cases, bookings, or a pack's own). Needs `records:read`. */
+async function cmdAnalytics(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/xrm/analytics`;
+    const entity = flags._[0];
+    const asJson = flags.json === true;
+    const stage = typeof flags.stage === 'string' ? flags.stage : undefined;
+    const mode = ANALYTICS_MODES.find(m => flags[m] === true) ?? 'funnel';
+    if (stage && !entity)
+        die('usage: octwin analytics <entity> --stage <stageId>   (a stage belongs to an entity)');
+    if (!entity) {
+        if (!asJson)
+            console.log(`→ Reading the analytics entity list from ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}/entities`, t);
+        if (status !== 200)
+            die(`could not read analytics entities (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const ents = (json?.entities ?? []);
+        if (ents.length === 0) {
+            console.log('No pipelined entities visible — a funnel needs an entity declared with a `pipeline:`,');
+            console.log('and your role needs a `view` grant on it. (Journeys have their own analytics surface.)');
+            return;
+        }
+        console.log(`Entities with a funnel in ${targetLabel(t)}:`);
+        for (const e of ents) {
+            console.log(`  ${e.entity}  (${e.stage_count} stage(s), ${e.milestone_count} milestone(s))`);
+        }
+        console.log('\nStage conversion:  octwin analytics <entity>            (add --overview / --milestones / --trends / --cost)');
+        console.log('Who is at a stage: octwin analytics <entity> --stage <stageId>');
+        return;
+    }
+    // Stage drill-down — records CURRENTLY at a stage. A live snapshot, deliberately
+    // NOT range-filtered like the funnel's cumulative reached-≥ counts.
+    if (stage) {
+        if (!asJson)
+            console.log(`→ Reading ${entity} records at stage '${stage}' from ${targetLabel(t)} …`);
+        const limit = flags.limit ?? '50';
+        const { status, json } = await apiGet(`${base}/${encodeURIComponent(entity)}/stages/${encodeURIComponent(stage)}/records?limit=${limit}`, t);
+        if (status === 404)
+            die(`unknown stage '${stage}' for '${entity}'${errDetail(json)}`);
+        if (status !== 200)
+            die(`could not read stage records (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        if (json?.has_data === false) {
+            printNoAnalyticsData(entity);
+            return;
+        }
+        const rows = (json?.records ?? []);
+        console.log(`${entity} at '${stage}' (live snapshot): ${json?.total ?? rows.length} record(s)`);
+        for (const r of rows) {
+            const who = r.channel_contact_handle ?? r.display_name ?? '—';
+            console.log(`  #${r.record_number ?? '?'}  ${r.title ?? '(untitled)'}  ${who}${r.completed ? '  [completed]' : ''}  ${r.record_id}`);
+        }
+        return;
+    }
+    if (!asJson)
+        console.log(`→ Reading ${entity} ${mode} from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(entity)}/${mode}`, t);
+    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) {
+        printNoAnalyticsData(entity);
+        return;
+    }
+    const range = json?.range ? ` (${json.range.from} → ${json.range.to})` : '';
+    console.log(`${entity} — ${mode}${range}:`);
+    switch (mode) {
+        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(s.stage).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}%)`}`);
+            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_milestone)
+                console.log(`  top milestone: ${s.top_milestone.milestone} (${s.top_milestone.completions})`);
+            break;
+        }
+        case 'milestones':
+            for (const m of (json?.milestones ?? [])) {
+                console.log(`  ${String(m.milestone).padEnd(28)} ${String(m.completions).padStart(6)} completion(s), ${m.unique_contacts} contact(s)`);
+            }
+            break;
+        case 'trends':
+            for (const b of (json?.buckets ?? [])) {
+                console.log(`  ${b.bucket}  active ${b.active_contacts}  milestones ${b.milestone_completions}`);
+            }
+            for (const c of (json?.cohorts ?? [])) {
+                console.log(`  cohort ${c.bucket}  entered ${c.entered}  converted ${c.converted}`);
+            }
+            break;
+        case 'cost':
+            if (json?.cost_partial)
+                console.log('  ⚠ partial — some token-usage rows carry no cost');
+            for (const r of (json?.by_milestone ?? [])) {
+                console.log(`  ${String(r.id).padEnd(28)} ${r.conversations} conv, ${r.total_tokens} tokens, $${r.cost_usd}`);
+            }
+            for (const d of (json?.drivers ?? [])) {
+                console.log(`  driver flow=${d.source_flow_id ?? '—'} agent=${d.source_agent_id ?? '—'}  conversions ${d.conversions}`);
+            }
+            break;
+    }
+}
+// ── catalog: the commerce products + their WhatsApp binding ──────────────────
+/** `octwin catalog [--readiness] [--json]` — the `product` records a commerce pack
+ *  sells, their stock, and the WhatsApp catalog binding. Needs `catalog:read` + the
+ *  `catalog` plan feature. */
+async function cmdCatalog(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/catalog`;
+    const asJson = flags.json === true;
+    // --readiness makes LIVE Meta Graph calls (and 409s with no bound access token),
+    // so it's opt-in rather than part of the default read.
+    if (flags.readiness === true) {
+        if (!asJson)
+            console.log(`→ Checking WhatsApp commerce readiness for ${targetLabel(t)} (live Meta Graph calls) …`);
+        const { status, json } = await apiGet(`${base}/readiness`, t);
+        if (status === 409)
+            die(`no Meta access token on this project's WhatsApp channel — readiness needs one${errDetail(json)}`);
+        if (status !== 200)
+            die(`could not read readiness (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        const r = json?.readiness ?? {};
+        console.log(`WhatsApp commerce readiness: ${r.summary ?? '?'}`);
+        for (const c of (r.checks ?? [])) {
+            const mark = c.status === 'ok' ? '✓' : c.status === 'warn' ? '⚠' : c.status === 'skip' ? '·' : '✗';
+            console.log(`  ${mark} ${c.label}${c.detail ? ` — ${c.detail}` : ''}`);
+            if (c.solution)
+                console.log(`      → ${c.solution}`);
+        }
+        return;
+    }
+    if (!asJson)
+        console.log(`→ Reading the product catalog from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(base, t);
+    if (status !== 200)
+        die(`could not read the catalog (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    const products = (json?.products ?? []);
+    console.log(`Products in ${targetLabel(t)}: ${products.length}`);
+    if (products.length === 0)
+        console.log('  (none — a commerce pack seeds `product` records, or add them in the console Catalog)');
+    for (const p of products) {
+        // `available: null` = the SKU isn't inventory-tracked (always sellable).
+        const stock = p.available == null ? 'untracked' : `${p.available}`;
+        console.log(`  ${String(p.retailer_id).padEnd(20)} ${String(p.name ?? '').padEnd(28)} ${fmtAmount(p.price, p.currency)}`
+            + `  avail=${p.availability}  stock=${stock}  sync=${p.sync_status ?? '—'}`);
+    }
+    // A binding row can exist with no catalog_id yet (a WABA is configured but no Meta
+    // catalog picked) — that is "not bound" for selling purposes, so say so.
+    const b = json?.binding;
+    console.log(b?.catalog_id
+        ? `\nWhatsApp catalog binding: catalog ${b.catalog_id} (waba ${b.waba_id ?? '—'}), sync=${b.sync_status ?? '—'}, last=${b.last_sync_at ?? 'never'}`
+        : `\nWhatsApp catalog binding: no Meta catalog bound${b?.waba_id ? ` (waba ${b.waba_id} is configured — pick a catalog)` : ''}`
+            + ' — the catalog works web-only (`--readiness` explains what Meta needs).');
+}
+// ── scheduling: the availability engine + a slot preview ─────────────────────
+/** `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]`
+ *  — the scheduling engine's state, or the computed slots for one bookable resource
+ *  (the verification the `--seed` availability fan-out was missing). `scheduling:read`. */
+async function cmdScheduling(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags, packDir);
+    const { url } = t;
+    const base = `${url}/api/self/p/scheduling`;
+    const asJson = flags.json === true;
+    const resourceId = typeof flags.slots === 'string' ? flags.slots : undefined;
+    if (flags.slots === true)
+        die('usage: octwin scheduling --slots <resourceRecordId>   (the record id of a bookable resource)');
+    if (resourceId) {
+        const q = new URLSearchParams({ include_booked: '1' }); // full occupancy, as the operator preview does
+        if (typeof flags.from === 'string')
+            q.set('from', flags.from);
+        if (typeof flags.days === 'string')
+            q.set('days', flags.days); // server-clamped to 1–31
+        if (!asJson)
+            console.log(`→ Computing slots for resource ${resourceId} in ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}/resources/${encodeURIComponent(resourceId)}/slots?${q.toString()}`, t);
+        if (status === 404)
+            die(`resource '${resourceId}' not found (pass an XRM record id — \`octwin records <entity>\` lists them)`);
+        if (status === 400)
+            die(`that record isn't a bookable resource${errDetail(json)}`);
+        if (status !== 200)
+            die(`could not compute slots (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        if (json?.has_scheduling === false) {
+            console.log('This pack declares no `scheduling.yaml` — nothing to schedule.');
+            return;
+        }
+        const slots = (json?.slots ?? []);
+        console.log(`Slots for ${resourceId} (timezone ${json?.timezone ?? '?'}): ${slots.length}`);
+        if (slots.length === 0)
+            console.log('  (none — no availability rules cover this window; `octwin deploy --seed` seeds the demo rules)');
+        for (const s of slots) {
+            console.log(`  ${s.slot_start} → ${s.slot_end}   ${s.remaining}/${s.capacity} free`);
+        }
+        return;
+    }
+    if (!asJson)
+        console.log(`→ Reading the scheduling engine state from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(base, t);
+    if (status !== 200)
+        die(`could not read scheduling (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    if (json?.has_scheduling === false) {
+        console.log('This pack declares no `scheduling.yaml` — nothing to schedule.');
+        return;
+    }
+    console.log(`Scheduling in ${targetLabel(t)} — bookings land as '${json?.booking_entity}'`);
+    for (const rt of (json?.resource_types ?? [])) {
+        console.log(`  ${rt.entity}  ${rt.resources} resource(s), ${rt.window_days}-day booking window`);
+    }
+    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>)');
+}
 function help() {
     console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
 
@@ -1284,6 +1908,11 @@ function help() {
   octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
   octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
   octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
+  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
+  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
+  octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
+  octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
+  octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
   octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
   octwin test    [--dir .]                               # = validate --remote (the full platform check)
 
@@ -1304,7 +1933,8 @@ const COMMAND_HELP = {
   Offline structural check; --remote additionally runs the platform's FULL
   manifest + flow-DSL validation (all errors at once) — same check as deploy.`,
     login: `octwin login --url <platformUrl> --token oct_…
-  Save a deploy token (console → Settings → API tokens) for that platform url.`,
+  Save a deploy token (console → Settings → API tokens) for that platform url,
+  and echo the workspace + project pin + scopes the token reaches.`,
     whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
     deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
@@ -1335,6 +1965,35 @@ const COMMAND_HELP = {
   public asset, and print its MEDIA- handle + serve URL. --out downloads the
   bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
   width, height, bytes }. Pair with 'octwin chat --media' to drive media flows.`,
+    agents: `octwin agents [packId::agentId] [--prompt] [--json]
+  No args = the roster with each agent's EFFECTIVE model and which layer set it.
+  With an agent = every governed setting (model / memory.last_messages /
+  working_memory) plus the layer that won — an operator PLATFORM default can
+  override what your manifest declares, and this is where you see that.
+  --prompt = the exact system prompt the LLM sees for this project (pack
+  instructions + platform protocol + any project overlay). Needs agents:read.
+  The agent ref is the compound \`<packId>::<agentId>\` key or the override-row UUID.`,
+    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.`,
+    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.`,
+    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.`,
     'platform-kb': `octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
   Pull the platform capability reference (markdown + JSON catalogs) into
   .octwin/platform-kb/ for the octwin-pack authoring skill.`,
@@ -1344,6 +2003,7 @@ const COMMAND_HELP = {
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
+    CURRENT_COMMAND = command; // so an auth failure can name the scope THIS command needs
     // Per-subcommand --help/-h — intercepted BEFORE the command runs, so help can
     // never hit the network or die on auth (author-feedback A8).
     if (command && command in COMMAND_HELP && (flags.help === true || flags._.includes('-h'))) {
@@ -1358,7 +2018,7 @@ async function main() {
             await cmdValidate(flags);
             break;
         case 'login':
-            cmdLogin(flags);
+            await cmdLogin(flags);
             break;
         case 'whoami':
             await cmdWhoami(flags);
@@ -1384,6 +2044,21 @@ async function main() {
         case 'media':
             await cmdMedia(flags);
             break;
+        case 'agents':
+            await cmdAgents(flags);
+            break;
+        case 'orders':
+            await cmdOrders(flags);
+            break;
+        case 'analytics':
+            await cmdAnalytics(flags);
+            break;
+        case 'catalog':
+            await cmdCatalog(flags);
+            break;
+        case 'scheduling':
+            await cmdScheduling(flags);
+            break;
         case 'platform-kb':
             await cmdPlatformKb(flags);
             break;