octwin-cli 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -5,6 +5,51 @@ Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucket
 **Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
 repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
 
+## [0.1.14] - 2026-07-23
+
+### Fixed
+- **A failed demo seed no longer reports a clean `✓`.** `deploy` softens non-fatal
+  install steps (e.g. a demo-seed row) to warning frames, but the summary still printed
+  `✓ Deployed` and exited 0 — so a deploy that seeded ZERO records read as success (the
+  false-✓ trap). `deploy` now collects those step errors, prints `⚠ Deployed with N
+  warning(s) — data may be incomplete` with each message, and exits non-zero so CI /
+  a `deploy && chat` chain catches it.
+
+### Added
+- **`login` echoes what the token reaches.** After saving, `octwin login` calls
+  `/api/self/t/whoami` and prints the workspace, project pin, and scopes — so a fresh
+  token self-identifies without a second `octwin whoami` (best-effort; a network failure
+  never fails the save).
+- **`validate --remote` surfaces warnings + the data-store trap.** The remote validate now
+  renders advisory `⚠` warnings (which don't block deploy) and, for a pack declaring
+  `required_adapters: [data-store]`, reports the missing-data-store error the deploy would
+  have 409'd on — plus a warning that an `xrm.yaml` pack usually shouldn't declare that
+  adapter at all. It also now catches (offline) a list-form `entities:` block and a
+  `localized: true` field seeded with a bare string — traps that previously surfaced only
+  mid-seed at deploy.
+
+## [0.1.13] - 2026-07-22
+
+### Added
+- **A headless media loop — produce + send.** Two paired additions close the coverage hole where any
+  media-collect flow (e.g. `activate-app`'s registration / ID uploads) stalled at the upload prompt
+  because the CLI could neither *make* nor *send* an image:
+  - `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]` — AI-generates an
+    image on the platform (needs a `media:generate`-scoped token), stores it as a public asset, and prints
+    its `MEDIA-` handle + serve URL. `--out` downloads the bytes to a file (WhatsApp renders only
+    `.png`/`.jpg`); `--json` emits `{ media_id, url, mime, width, height, bytes }`.
+  - `octwin chat --media <file|media-id>` — uploads a local file (or a media id from
+    `media generate --json`) as an image/document/audio inbound; any accompanying `"message"` rides as
+    its caption. The platform's media pipeline folds the upload into a running collect, so media flows
+    are now fully drivable headlessly.
+
+### Changed
+- **The KB-drift nudge now names what changed.** With the platform serving per-entry content hashes, the
+  post-command nudge appends a `(N changed · M added · K removed)` summary instead of a bare hash pair.
+- **`octwin platform-kb` prints a changelog on pull.** Instead of only a doc/catalog count, the pull now
+  diffs the fresh index against your last pull and lists exactly which docs/catalogs were added (`+`),
+  changed (`~`), or removed (`-`) — so a replaced schema shape is visible, not silent.
+
 ## [0.1.12] - 2026-07-22
 
 ### Fixed

package/dist/index.js

@@ -17,7 +17,8 @@
  *   octwin records [entity] [id]    # inspect the pack's XRM data (records:read token)
  *   octwin cases   [caseId] [--queues]     # inspect casework (support tickets) — list / one case + timeline
  *   octwin logs    [conversationId] [--as h] [--json]  # list conversations / show one's timeline
- *   octwin chat    "msg" [--as h] [--tap <tap-id>] [--json]  # drive a turn via the web channel
+ *   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 platform-kb [pull] [--dir .]  # pull the platform capability reference for the authoring skill
  *   octwin test    [--dir .]        # = validate --remote (the full platform check)
  *
@@ -35,7 +36,7 @@
  * (pure-YAML enforcement + manifest/flow Zod) and installs it onto the project.
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, cpSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
@@ -112,6 +113,50 @@ function errDetail(json) {
     const msg = typeof json === 'string' ? json : (json.error ?? json.message ?? JSON.stringify(json));
     return msg ? ` — ${msg}` : '';
 }
+// ── media helpers (produce/send loop) ───────────────────────────────────────
+/** Extension → MIME for local files the `chat --media` sender uploads (mirrors
+ *  the platform's accepted image/document/audio MIME sets). */
+const MEDIA_MIME_BY_EXT = {
+    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp',
+    '.pdf': 'application/pdf', '.txt': 'text/plain',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.ogg': 'audio/ogg', '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.wav': 'audio/wav', '.webm': 'audio/webm', '.aac': 'audio/aac',
+};
+/** MIME → file extension (for naming a fetched-by-id media part). */
+const EXT_BY_MEDIA_MIME = {
+    'image/jpeg': 'jpg', 'image/png': 'png', 'image/gif': 'gif', 'image/webp': 'webp', 'application/pdf': 'pdf',
+};
+/** The inbound `type` the platform expects for a MIME (image/document/audio). */
+function mediaKindOf(mime) {
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    return 'document';
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Resolve a `--media` argument to an uploadable part: a local file path, OR a
+ *  media UUID (as returned by `octwin media generate --json`) fetched from the
+ *  public serve route. The cosmetic `MEDIA-…` handle is NOT fetchable (the serve
+ *  route is UUID-keyed) — use the file written by `--out`, or the `media_id`. */
+async function resolveMediaPart(url, arg) {
+    if (existsSync(arg)) {
+        const buffer = readFileSync(arg);
+        const ext = arg.slice(arg.lastIndexOf('.')).toLowerCase();
+        const mime = MEDIA_MIME_BY_EXT[ext] ?? 'application/octet-stream';
+        return { blob: new Blob([buffer], { type: mime }), kind: mediaKindOf(mime), filename: basename(arg) };
+    }
+    if (UUID_RE.test(arg)) {
+        const res = await fetchOrDie(`${url}/api/media/${arg}`, undefined, 'fetch media');
+        if (!res.ok)
+            die(`--media '${arg}' not found (HTTP ${res.status}) — pass a local file path, or a media id from 'octwin media generate --json'`);
+        const mime = res.headers.get('content-type') ?? 'application/octet-stream';
+        const buffer = Buffer.from(await res.arrayBuffer());
+        return { blob: new Blob([buffer], { type: mime }), kind: mediaKindOf(mime), filename: `${arg}.${EXT_BY_MEDIA_MIME[mime] ?? 'bin'}` };
+    }
+    die(`--media '${arg}' is neither an existing file nor a media id (UUID). The cosmetic MEDIA-… handle isn't fetchable — send the file written by 'octwin media generate --out', or pass the media_id from '--json'.`);
+}
 // ── bundle collection ───────────────────────────────────────────────────────
 const SKIP_DIRS = new Set(['.git', 'node_modules', '.pack-bundles', 'dist', '.mastra']);
 /** Collect every text file under `packDir` into a `{ relPath: content }` map. */
@@ -243,18 +288,34 @@ async function notifyIfOutdated() {
     }
     catch { /* a version check must never break the CLI */ }
 }
-// ── platform-KB drift check (observe the pulled reference, TTY-only, fail-silent) ──
-/** The `content_hash` of a previously-pulled KB in `<packDir>/.octwin/platform-kb/`,
- *  or null if nothing has been pulled yet. */
-function readLocalKbHash(packDir) {
+/** A previously-pulled KB's identity in `<packDir>/.octwin/platform-kb/index.json`
+ *  (content hash + per-entry index), or null if nothing has been pulled yet. */
+function readLocalKb(packDir) {
     try {
         const idx = JSON.parse(readFileSync(join(packDir, '.octwin', 'platform-kb', 'index.json'), 'utf8'));
-        return typeof idx.content_hash === 'string' ? idx.content_hash : null;
+        return {
+            content_hash: typeof idx.content_hash === 'string' ? idx.content_hash : null,
+            index: Array.isArray(idx.index) ? idx.index : [],
+        };
     }
     catch {
         return null;
     }
 }
+/** Diff two KB indexes by key + per-entry `hash` → added / removed / changed keys. */
+function diffKbIndex(prev, next) {
+    const prevMap = new Map(prev.map(e => [e.key, e.hash]));
+    const nextKeys = new Set(next.map(e => e.key));
+    const added = [], changed = [];
+    for (const e of next) {
+        if (!prevMap.has(e.key))
+            added.push(e.key);
+        else if (prevMap.get(e.key) !== e.hash)
+            changed.push(e.key);
+    }
+    const removed = prev.filter(e => !nextKeys.has(e.key)).map(e => e.key);
+    return { added, removed, changed };
+}
 /** Nudge (to stderr) when the platform's capability KB has changed since the last
  *  `octwin platform-kb pull`. The sibling of `notifyIfOutdated`, for the KB instead
  *  of the CLI: run only after commands that already hit the platform, so this adds
@@ -266,23 +327,36 @@ async function notifyIfKbStale(flags) {
         return;
     try {
         const packDir = resolve(flags.dir ?? '.');
-        const localHash = readLocalKbHash(packDir);
-        if (!localHash)
+        const local = readLocalKb(packDir);
+        if (!local?.content_hash)
             return; // never pulled → the skill already says to pull
         const t = resolveTargetOrNull(flags, packDir);
         if (!t)
             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)
             return;
         const meta = await res.json();
-        if (meta.content_hash && meta.content_hash !== localHash) {
-            console.error(`\n⬆ the platform capability reference changed since you last pulled it (${localHash} → ${meta.content_hash}).`);
+        if (meta.content_hash && meta.content_hash !== local.content_hash) {
+            // Per-entry summary (now that the index carries per-entry hashes) — the
+            // exact list of what changed is one `octwin platform-kb` away.
+            let summary = '';
+            if (Array.isArray(meta.index) && local.index.length) {
+                const { added, removed, changed } = diffKbIndex(local.index, meta.index);
+                const parts = [
+                    changed.length && `${changed.length} changed`,
+                    added.length && `${added.length} added`,
+                    removed.length && `${removed.length} removed`,
+                ].filter(Boolean);
+                if (parts.length)
+                    summary = ` (${parts.join(' · ')})`;
+            }
+            console.error(`\n⬆ the platform capability reference changed since you last pulled it${summary}.`);
             console.error('  Refresh it: octwin platform-kb');
         }
     }
@@ -298,6 +372,7 @@ function commandTouchesPlatform(command, flags) {
         case 'status':
         case 'test':
         case 'chat':
+        case 'media':
         case 'records':
         case 'cases':
         case 'logs':
@@ -327,10 +402,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'))) {
@@ -342,7 +418,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');
 }
@@ -368,11 +444,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();
@@ -392,6 +469,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;
@@ -411,55 +494,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 */ }
+}
+/** 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 + tenant + project + token: flags > pack.json > env > saved login. */
+/** 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
@@ -472,6 +583,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)
@@ -495,14 +611,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;
@@ -519,29 +639,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
@@ -560,11 +690,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)');
@@ -573,9 +704,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;
@@ -587,13 +718,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)'}`);
@@ -612,10 +743,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) {
@@ -631,6 +763,9 @@ async function cmdPlatformKb(flags) {
         process.exit(1);
     }
     const bundle = JSON.parse(text);
+    // Snapshot the prior pull's index BEFORE overwriting it, so we can show the
+    // author EXACTLY what changed (not just a count).
+    const prior = readLocalKb(packDir);
     // Write the reference into <packDir>/.octwin/platform-kb/ — markdown docs (the
     // skill reads these first) + JSON catalogs (precise field schemas). Gitignored.
     const outDir = join(packDir, '.octwin', 'platform-kb');
@@ -654,14 +789,31 @@ async function cmdPlatformKb(flags) {
     writeFileSync(join(outDir, 'index.json'), JSON.stringify({ version: bundle.version, content_hash: bundle.content_hash, generated_at: bundle.generated_at, index: bundle.index }, null, 2) + '\n', 'utf8');
     console.log(`✓ Pulled the Octwin platform KB → ${outDir}`);
     console.log(`  ${mdCount} markdown docs + ${jsonCount} JSON catalogs (reference version ${bundle.version ?? '?'})`);
+    // Changelog since the last pull — per-entry hashes tell us WHICH docs/catalogs
+    // moved (a schema shape being replaced shows as a `~ changed`), not just a count.
+    if (prior?.content_hash) {
+        if (prior.content_hash === bundle.content_hash) {
+            console.log('  (no content changes since your last pull)');
+        }
+        else {
+            const { added, removed, changed } = diffKbIndex(prior.index, bundle.index ?? []);
+            console.log(`  Δ changes since your last pull (${prior.content_hash} → ${bundle.content_hash ?? '?'}):`);
+            for (const k of added)
+                console.log(`    + ${k} (new)`);
+            for (const k of changed)
+                console.log(`    ~ ${k} (changed)`);
+            for (const k of removed)
+                console.log(`    - ${k} (removed)`);
+        }
+    }
     console.log('  The octwin-pack authoring skill reads these as the source of truth for what the platform supports.');
 }
 // ── records / cases / logs / chat — headless inspect + test with the deploy token ────
 /** 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 {
@@ -672,16 +824,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) {
@@ -693,7 +851,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>');
@@ -701,7 +859,7 @@ 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);
+        const { status, json } = await apiGet(`${base}/xrm/records?entity=${encodeURIComponent(entity)}&limit=${limit}`, t);
         if (status === 403)
             die('forbidden — the paged record list needs the `records` plan feature on this tenant');
         if (status !== 200) {
@@ -720,7 +878,7 @@ 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);
+    const { status, json } = await apiGet(`${base}/xrm/records/${encodeURIComponent(recordId)}`, t);
     if (status === 403)
         die('forbidden — mint a token with the `records:read` scope');
     if (status === 404)
@@ -735,15 +893,16 @@ async function cmdRecords(flags) {
  *  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)}`);
         let convs = (json?.conversations ?? []);
@@ -757,7 +916,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})` : '';
@@ -767,7 +926,7 @@ 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)
@@ -922,18 +1081,40 @@ 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;
+    const mediaArg = typeof flags.media === 'string' ? flags.media : undefined;
     const message = flags._[0];
-    if (!message && !tapId)
-        die('usage: octwin chat "your message" [--as <handle>] [--tap <tap-id>] [--json]');
+    if (!message && !tapId && !mediaArg)
+        die('usage: octwin chat "your message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]');
     // Fresh idempotency key per call (see the command doc above).
     const localId = `cli-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
     if (!asJson)
@@ -957,16 +1138,35 @@ async function cmdChat(flags) {
         if (f.id != null && f.id > boundary)
             boundary = f.id;
     }
-    // Phase 2 — send the inbound (text, or an interactive tap).
-    console.log(`→ [${from}] ${tapId ? `(tap) ${tapId}` : message}`);
-    const body = tapId
-        ? { type: 'interactive', from, tap_id: tapId, ...(message ? { raw_title: message } : {}), local_id: localId }
-        : { type: 'text', from, text: message, local_id: localId };
-    const postRes = await fetchOrDie(`${url}/api/web/inbound/${tenant}/${project}`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(body),
-    }, 'send message');
+    // Phase 2 — send the inbound (media upload, an interactive tap, or text).
+    const inbound = `${url}/api/web/inbound/${tenant}/${project}`;
+    let postRes;
+    if (mediaArg && !tapId) {
+        // Multipart upload → the platform's media pipeline sets $inbound_media, which
+        // a running collect folds into $state.<field> (docs/19 §8a). Any accompanying
+        // message rides as the media caption.
+        const { blob, kind, filename } = await resolveMediaPart(url, mediaArg);
+        console.log(`→ [${from}] (media:${kind}) ${filename}${message ? ` — "${message}"` : ''}`);
+        const form = new FormData();
+        form.append('type', kind);
+        form.append('from', from);
+        form.append('local_id', localId);
+        if (message)
+            form.append('caption', message);
+        form.append('file', blob, filename);
+        postRes = await fetchOrDie(inbound, { method: 'POST', body: form }, 'send media'); // fetch sets the multipart boundary
+    }
+    else {
+        console.log(`→ [${from}] ${tapId ? `(tap) ${tapId}` : message}`);
+        const body = tapId
+            ? { type: 'interactive', from, tap_id: tapId, ...(message ? { raw_title: message } : {}), local_id: localId }
+            : { type: 'text', from, text: message, local_id: localId };
+        postRes = await fetchOrDie(inbound, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        }, 'send message');
+    }
     if (!postRes.ok) {
         await cancel();
         die(`send rejected (HTTP ${postRes.status}): ${await postRes.text()}`);
@@ -1011,23 +1211,86 @@ async function cmdChat(flags) {
     }
     console.log(`\n(same --as '${from}' continues this conversation — timeline: octwin logs --as ${from})`);
 }
+/** `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]`
+ *  — AI-generate an image on the platform (needs a `media:generate`-scoped token),
+ *  store it as a public asset, and return its `MEDIA-` handle + serve URL. `--out`
+ *  downloads the bytes to a file (WhatsApp renders only `.png`/`.jpg`); the paired
+ *  `octwin chat --media <file|id>` feeds it into a running media-collect flow. */
+async function cmdMedia(flags) {
+    const sub = flags._[0];
+    if (sub !== 'generate')
+        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]');
+    const packDir = resolve(flags.dir ?? '.');
+    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]');
+    const asJson = flags.json === true;
+    const size = typeof flags.size === 'string' ? flags.size : undefined;
+    const out = typeof flags.out === 'string' ? flags.out : undefined;
+    if (!asJson)
+        console.log(`→ Generating an image on ${targetLabel(t)} @ ${url} …`);
+    const res = await fetchOrDie(`${url}/api/self/p/media/generate`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...authHeaders(t) },
+        body: JSON.stringify({ prompt, ...(size ? { size } : {}) }),
+    }, 'media generate');
+    const text = await res.text();
+    if (!res.ok) {
+        let j;
+        try {
+            j = JSON.parse(text);
+        }
+        catch {
+            j = text;
+        }
+        console.error(`✗ media generate failed (HTTP ${res.status})${errDetail(j)}`);
+        printAuthHint(res.status, url);
+        process.exit(1);
+    }
+    const r = JSON.parse(text);
+    const absUrl = /^https?:/i.test(r.url) ? r.url : `${url}${r.url}`;
+    // --out → download the bytes so the paired `chat --media <file>` can send them.
+    if (out) {
+        const dl = await fetchOrDie(absUrl, undefined, 'download generated image');
+        if (!dl.ok)
+            die(`could not download the generated image (HTTP ${dl.status})`);
+        writeFileSync(out, Buffer.from(await dl.arrayBuffer()));
+        const ext = out.slice(out.lastIndexOf('.')).toLowerCase();
+        if (ext !== '.png' && ext !== '.jpg' && ext !== '.jpeg') {
+            console.error(`  ⚠ '${out}' isn't a .png/.jpg — WhatsApp only renders those extensions.`);
+        }
+    }
+    if (asJson) {
+        console.log(JSON.stringify({ media_id: r.media_id, url: absUrl, mime: r.mime, width: r.width, height: r.height, bytes: r.bytes }));
+        return;
+    }
+    console.log(`✓ Generated ${r.media_ref} (${r.width}×${r.height}, ${r.mime}, ${r.bytes} bytes)`);
+    console.log(`  id:  ${r.media_id}`);
+    console.log(`  url: ${absUrl}`);
+    if (out)
+        console.log(`  saved → ${out}`);
+    console.log(`  Send it into a chat: octwin chat "here you go" --media ${out ?? r.media_id} --as <handle>`);
+}
 /** `octwin cases [caseId] [--queues]` — inspect casework (support tickets):
  *  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) => {
         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)}` : ''}`);
     };
     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) {
@@ -1035,7 +1298,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)
@@ -1044,7 +1307,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) {
@@ -1052,7 +1315,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) {
@@ -1062,7 +1325,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)
@@ -1106,7 +1369,8 @@ function help() {
   octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
   octwin cases   [caseId] [--queues] [--json]            # inspect casework (support tickets) + timelines
   octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
-  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--json]  # drive a turn + print every render
+  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 platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
   octwin test    [--dir .]                               # = validate --remote (the full platform check)
 
@@ -1127,7 +1391,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]
@@ -1145,11 +1410,19 @@ const COMMAND_HELP = {
   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).`,
-    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--json]
+    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--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.`,
+    media: `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]
+  AI-generate an image (needs a media:generate-scoped token), store it as a
+  public asset, and print its MEDIA- handle + serve URL. --out downloads the
+  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
+  width, height, bytes }. Pair with 'octwin chat --media' to drive media flows.`,
     '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.`,
@@ -1173,7 +1446,7 @@ async function main() {
             await cmdValidate(flags);
             break;
         case 'login':
-            cmdLogin(flags);
+            await cmdLogin(flags);
             break;
         case 'whoami':
             await cmdWhoami(flags);
@@ -1196,6 +1469,9 @@ async function main() {
         case 'chat':
             await cmdChat(flags);
             break;
+        case 'media':
+            await cmdMedia(flags);
+            break;
         case 'platform-kb':
             await cmdPlatformKb(flags);
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {