octwin-cli 0.1.15 → 0.1.16

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.16] - 2026-07-26
+
+### Added
+- **A pack can ship committed images.** `jpg`/`jpeg`/`png`/`webp`/`gif`/`pdf` files in your pack
+  directory now travel as a separate `blobs` half of the bundle (base64 on the wire, `bytea` in
+  storage) instead of being rejected as "not an allowed pack file type". Declare each one under the
+  manifest's `static_assets: [{ file, key }]` and reference it from `config:` with the
+  `$pack_asset:<key>` sentinel — the platform uploads it to the media system at install and the
+  sentinel resolves to the served URL. `octwin validate` reports the image count alongside the file
+  count.
+- **The size ceilings fail locally, before upload** — 2 MB per file, 32 MB of binary per pack,
+  mirroring the server. `svg` stays rejected: it is script-capable and these assets are served to
+  browsers.
+
+### Fixed
+- **Committed images were silently corrupted.** `collectBundleFiles` read *every* file with
+  `readFileSync(full, 'utf8')`, so a JPEG went through a lossy UTF-8 decode and arrived mangled
+  server-side — a deploy that "succeeded" and rendered a broken image. Binary files now split off
+  into `blobs` and keep their bytes.
+- **`octwin status` reported `loaded=(none)` for every pack, always.** It printed a `loaded_version`
+  field that stopped existing when reload moved to content-sha keying, which also meant the
+  version-drift warning underneath it could never fire. It now prints the **content sha** the
+  instance has loaded and the one the catalog holds (with the artifact's `origin`), and warns off the
+  platform's own `up_to_date` flag. The sha is the more useful fact anyway: re-publishing the *same*
+  version changes it, which is exactly the author's inner loop. A pack that is live and current but
+  **withdrawn** from the catalog now says so, rather than reporting a clean bill of health.
+
 ## [0.1.15] - 2026-07-25
 
 ### Added

package/README.md

@@ -65,7 +65,7 @@ octwin status               # "✓ live and current" once it's warm
 | `octwin login` | Save a deploy token for a platform URL (stored in `~/.octwin/credentials.json`). `--url`, `--token`. |
 | `octwin whoami` | Verify the saved/passed token is valid for a tenant. `--url`, `--tenant`. |
 | `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. |
-| `octwin status` | Report what the platform has live for this pack — installed vs. loaded version, and its flows. |
+| `octwin status` | Report what the platform has live for this pack — installed version, the **content sha** the instance loaded vs. the one the catalog holds (a redeploy of the *same* version changes it), and its flows. |
 | `octwin chat "msg"` | Drive a turn through the dev web channel and print **every render with its tap ids**. `--as <handle>` picks the test user; `--tap "<tap-id>"` presses a rendered button/list row; `--json` dumps the raw envelopes. |
 | `octwin logs` | List recent conversations (handle, status, last activity; `--as` filters), or show one conversation's full event timeline — including what each turn rendered. `--json` for raw payloads. |
 | `octwin records` | Inspect the pack's XRM data (needs a `records:read` token). No args = list entities. |

package/dist/index.js

@@ -218,9 +218,27 @@ async function resolveMediaPart(url, arg) {
 }
 // ── 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. */
+/**
+ * Binary extensions the platform accepts as artifact BLOBS (mirrors
+ * `ALLOWED_BINARY_EXT` server-side). Deliberately no `svg` — script-capable.
+ */
+const BINARY_EXT = new Set(['jpg', 'jpeg', 'png', 'webp', 'gif', 'pdf']);
+/** Per-blob / total ceilings, mirroring the server so oversize fails LOCALLY. */
+const MAX_BLOB_BYTES = 2 * 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
+/**
+ * Collect a pack directory into its two halves: `files` (`{ relPath: utf8 }`) and
+ * `blobs` (`{ relPath: base64 }`).
+ *
+ * Every file used to be read with `readFileSync(full, 'utf8')`, which silently
+ * MANGLED any committed image — the bytes went through a lossy UTF-8 decode and
+ * arrived corrupt. Binary files now split off into `blobs`, transported as base64
+ * (transport only; they land in `bytea` server-side).
+ */
 function collectBundleFiles(packDir) {
     const files = {};
+    const blobs = {};
+    let totalBlobBytes = 0;
     const walk = (dir, prefix) => {
         for (const name of readdirSync(dir)) {
             const full = join(dir, name);
@@ -235,11 +253,24 @@ function collectBundleFiles(packDir) {
                 continue; // deploy config, not part of the pack
             if (name.startsWith('.'))
                 continue; // .gitignore etc. — not pack content
+            const ext = name.slice(name.lastIndexOf('.') + 1).toLowerCase();
+            if (BINARY_EXT.has(ext)) {
+                const buf = readFileSync(full);
+                if (buf.byteLength > MAX_BLOB_BYTES) {
+                    die(`'${rel}' is ${(buf.byteLength / 1024 / 1024).toFixed(1)} MB — the per-file limit is ${MAX_BLOB_BYTES / 1024 / 1024} MB`);
+                }
+                totalBlobBytes += buf.byteLength;
+                blobs[rel] = buf.toString('base64');
+                continue;
+            }
             files[rel] = readFileSync(full, 'utf8');
         }
     };
     walk(packDir, '');
-    return files;
+    if (totalBlobBytes > MAX_ARTIFACT_BYTES) {
+        die(`binary payload is ${(totalBlobBytes / 1024 / 1024).toFixed(1)} MB — the per-pack limit is ${MAX_ARTIFACT_BYTES / 1024 / 1024} MB`);
+    }
+    return { files, blobs };
 }
 function readManifestIdVersion(files) {
     const raw = files['manifest.yaml'];
@@ -487,20 +518,20 @@ function cmdInit(flags) {
     console.log('  octwin deploy');
 }
 function localValidate(packDir) {
-    const files = collectBundleFiles(packDir);
+    const { files, blobs } = collectBundleFiles(packDir);
     const { id, version } = readManifestIdVersion(files);
-    const r = validatePackBundle(id, files);
+    const r = validatePackBundle(id, files, blobs);
     if (!r.ok) {
         for (const e of r.errors)
             console.error(`  ✗ ${e}`);
         die(`bundle validation failed (${r.errors.length} error${r.errors.length === 1 ? '' : 's'})`);
     }
-    return { id, version, files };
+    return { id, version, files, blobs };
 }
 async function cmdValidate(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const { id, version, files } = localValidate(packDir); // offline structural gate first (fast, no server/token)
-    console.log(`✓ ${id}@${version} passes the offline structural check (${Object.keys(files).length} files)`);
+    const { id, version, files, blobs } = localValidate(packDir); // offline structural gate first (fast, no server/token)
+    console.log(`✓ ${id}@${version} passes the offline structural check (${Object.keys(files).length} files, ${Object.keys(blobs).length} image(s))`);
     if (flags.remote !== true) {
         console.log('  Run `octwin validate --remote` to run the platform\'s FULL manifest + flow-DSL validation');
         console.log('  (all errors at once) before you deploy.');
@@ -514,7 +545,7 @@ async function cmdValidate(flags) {
     const res = await fetchOrDie(`${url}/api/self/p/packs/validate`, {
         method: 'POST',
         headers: { 'content-type': 'application/json', ...authHeaders(t) },
-        body: JSON.stringify({ files }),
+        body: JSON.stringify({ files, blobs }),
     }, 'remote validate');
     const text = await res.text();
     let json;
@@ -709,7 +740,7 @@ async function cmdDeploy(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const t = resolveTarget(flags, packDir);
     const { url } = t;
-    const { id, version, files } = localValidate(packDir);
+    const { id, version, files, blobs } = localValidate(packDir);
     const endpoint = `${url}/api/self/p/packs/deploy`;
     const seed = flags.seed === true;
     console.log(`→ Deploying ${id}@${version} (${Object.keys(files).length} files) to ${targetLabel(t)}${seed ? ' — with demo seed' : ''} …`);
@@ -718,7 +749,7 @@ async function cmdDeploy(flags) {
         // 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', ...authHeaders(t) },
-        body: JSON.stringify({ files, seed }),
+        body: JSON.stringify({ files, blobs, 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).
@@ -790,13 +821,22 @@ async function cmdStatus(flags) {
     }
     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)'}`);
+    // Reads the CONTENT SHA, not a version string. It printed `loaded=${json.loaded_version}` — a
+    // field that stopped existing when reload moved to sha keying, so this line always said
+    // `(none)` and the drift warning below could never fire. The sha is also the more useful fact:
+    // re-publishing the SAME version changes it, which is exactly the author's inner loop.
+    const shortSha = (s) => (typeof s === 'string' && s ? s.slice(0, 12) + '…' : '(none)');
+    console.log(`  live on instance  : registered=${json.registered}  loaded=${shortSha(json.loaded_content_sha)}`);
+    console.log(`  catalog artifact  : ${shortSha(json.catalog_content_sha)}${json.origin ? `  origin=${json.origin}` : ''}`);
     console.log(`  flows             : ${(json.flows ?? []).join(', ') || '(none)'}`);
     if (!json.registered) {
         console.log('\n… not warm on the instance you hit yet — it loads on the next inbound (chat once, then re-check).');
     }
-    else if (json.loaded_version && json.installed_version && json.loaded_version !== json.installed_version) {
-        console.log(`\n⚠ instance has ${json.loaded_version} but the project is bound to ${json.installed_version} — a redeploy lands on the next turn.`);
+    else if (json.up_to_date === false) {
+        console.log('\n⚠ this instance is running an OLDER artifact than the catalog holds — it picks up the current one on the next inbound turn (chat once, then re-check).');
+    }
+    else if (json.catalog_status === 'withdrawn') {
+        console.log('\n⚠ live and current, but the pack is WITHDRAWN from the catalog — existing installs keep running; new installs are refused.');
     }
     else {
         console.log('\n✓ live and current.');
@@ -1894,110 +1934,110 @@ async function cmdScheduling(flags) {
     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)
-
-  octwin --version                                      # print the CLI version (+ any upgrade notice)
-  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
-  octwin validate [--dir .] [--remote]                  # --remote runs the platform's FULL schema check (all errors at once)
-  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
-  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
-  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-  octwin status  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
-  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>] [--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)
-
-Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
-\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
-button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
-Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
-octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
-Config (deploy): flags > pack.json > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login.
+    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
+
+  octwin --version                                      # print the CLI version (+ any upgrade notice)
+  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+  octwin validate [--dir .] [--remote]                  # --remote runs the platform's FULL schema check (all errors at once)
+  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
+  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
+  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+  octwin status  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
+  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>] [--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)
+
+Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
+\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
+button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
+Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
+octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
+Config (deploy): flags > pack.json > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login.
 Per-command usage: octwin <command> --help`);
 }
 /** Per-subcommand usage — printed for `octwin <cmd> --help|-h` BEFORE any
  *  network/auth work (a --help that 401s is worse than no help at all). */
 const COMMAND_HELP = {
-    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   Scaffold a pure-YAML starter pack into <dir>.`,
-    validate: `octwin validate [--dir .] [--remote]
-  Offline structural check; --remote additionally runs the platform's FULL
+    validate: `octwin validate [--dir .] [--remote]
+  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,
+    login: `octwin login --url <platformUrl> --token oct_…
+  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>]
+    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]
-  Upload the pack bundle, validate server-side, install onto the project.
+    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+  Upload the pack bundle, validate server-side, install onto the project.
   --seed additionally applies the pack's demo seed (streams progress).`,
-    status: `octwin status [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
+    status: `octwin status [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
   Show installed vs live version + the flow list for this pack.`,
-    records: `octwin records [entity] [id] [--limit 50]
-  Inspect the pack's XRM data. No args = list entities. Cases/tickets are
+    records: `octwin records [entity] [id] [--limit 50]
+  Inspect the pack's XRM data. No args = list entities. Cases/tickets are
   casework, not XRM — use \`octwin cases\` for those.`,
-    cases: `octwin cases [caseId] [--queues] [--limit 50] [--json]
-  Inspect casework (support tickets): the inbox, one case + its timeline
+    cases: `octwin cases [caseId] [--queues] [--limit 50] [--json]
+  Inspect casework (support tickets): the inbox, one case + its timeline
   (+ applicable decisions), or --queues for queue keys + open counts.`,
-    logs: `octwin logs [conversationId] [--as <handle>] [--json]
-  No id = recent conversations (handle, status, last activity; --as filters).
-  With id = the full event timeline including what each turn rendered.
+    logs: `octwin logs [conversationId] [--as <handle>] [--json]
+  No id = recent conversations (handle, status, last activity; --as filters).
+  With id = the full event timeline including what each turn rendered.
   --json = raw events (verbatim payloads).`,
-    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).
+    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,
+    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.`,
-    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.
+    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,
+    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
+    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: `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
+    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
+    '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.`,
-    test: `octwin test [--dir .]
+    test: `octwin test [--dir .]
   Alias for \`octwin validate --remote\` — the full platform check.`,
 };
 async function main() {

package/dist/lib/validate.js

@@ -8,9 +8,20 @@
  * uploading. The **server re-validates authoritatively** on deploy — this local
  * copy is a fast pre-check, not the source of truth — and it omits the server's
  * in-repo shadow check (there is no `src/packs` in a developer's own repo).
+ *
+ * The duplication is deliberate: `octwin-cli` is published to npm and must not
+ * import the platform. `validate-parity.test.ts` asserts the two copies agree on
+ * every rule, so a divergence fails the build rather than surfacing as "it passed
+ * locally but the deploy rejected it".
  */
-/** Declarative file extensions a pure-YAML pack may contain. */
+/** Declarative TEXT extensions a pure-YAML pack may contain. */
 const ALLOWED_EXT = new Set(['yaml', 'yml', 'md', 'sql', 'json']);
+/** Binary extensions that travel as artifact BLOBS (base64 on the wire, bytea in
+ *  storage). No `svg` — it is script-capable and these are served to browsers. */
+const ALLOWED_BINARY_EXT = new Set(['jpg', 'jpeg', 'png', 'webp', 'gif', 'pdf']);
+/** Ceilings, mirrored from the server so oversize fails LOCALLY before upload. */
+const MAX_BLOB_BYTES = 2 * 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
 /** Extensions/paths that mean executable code or a non-YAML capability — rejected. */
 const CODE_EXT = new Set(['ts', 'js', 'mjs', 'cjs', 'jsx', 'tsx', 'node', 'wasm', 'sh', 'bash', 'exe', 'py', 'rb']);
 /** Normalize to forward slashes + strip a leading `./`. */
@@ -28,13 +39,15 @@ function ext(p) {
  * no path traversal or absolute paths, declarative extensions only. Returns all
  * violations at once.
  */
-export function validatePackBundle(packId, files) {
+export function validatePackBundle(packId, files, 
+/** `{ relPath: base64 }` — the binary half, as the CLI collects it. */
+blobs = {}) {
     const errors = [];
     if (!/^[a-z][a-z0-9-]*$/.test(packId)) {
         errors.push(`pack id '${packId}' must be lowercase ASCII with hyphens (e.g. 'my-pack')`);
     }
     const paths = Object.keys(files);
-    if (paths.length === 0)
+    if (paths.length === 0 && Object.keys(blobs).length === 0)
         errors.push('bundle is empty');
     if (!paths.some(p => norm(p) === 'manifest.yaml')) {
         errors.push('bundle is missing manifest.yaml at its root');
@@ -62,10 +75,43 @@ export function validatePackBundle(packId, files) {
             errors.push(`'${p}': executable code is not allowed (pure-YAML packs only)`);
             continue;
         }
+        if (ALLOWED_BINARY_EXT.has(e)) {
+            errors.push(`'${p}': binary files travel as blobs, not in the text file map`);
+            continue;
+        }
         if (!ALLOWED_EXT.has(e)) {
-            errors.push(`'${p}': not an allowed pack file type (.yaml/.yml/.md/.sql only)`);
+            errors.push(`'${p}': not an allowed pack file type (.yaml/.yml/.md/.sql/.json, or an image: ${[...ALLOWED_BINARY_EXT].join('/')})`);
+            continue;
+        }
+    }
+    // Blobs — same rules the server applies to the decoded bytes. Sizes are derived
+    // from the base64 length (3 bytes per 4 chars, minus padding) so this needs no
+    // Buffer and stays platform-free.
+    let totalBlobBytes = 0;
+    for (const raw of Object.keys(blobs)) {
+        const p = norm(raw);
+        if (p.startsWith('/') || /^[a-zA-Z]:/.test(p) || p.split('/').includes('..')) {
+            errors.push(`unsafe blob path '${raw}' (absolute or traversal)`);
+            continue;
+        }
+        const e = ext(p);
+        if (!ALLOWED_BINARY_EXT.has(e)) {
+            errors.push(`'${p}': not an allowed image type (${[...ALLOWED_BINARY_EXT].join('/')}; SVG is rejected — it is script-capable)`);
             continue;
         }
+        const b64 = blobs[raw];
+        const size = Math.floor(b64.replace(/=+$/, '').length * 3 / 4);
+        totalBlobBytes += size;
+        if (size > MAX_BLOB_BYTES) {
+            errors.push(`'${p}': ${(size / 1024 / 1024).toFixed(1)} MB exceeds the ${MAX_BLOB_BYTES / 1024 / 1024} MB per-file limit`);
+        }
+        if (files[raw] !== undefined) {
+            errors.push(`'${p}': present as BOTH a text file and a blob — pick one`);
+        }
+    }
+    if (totalBlobBytes > MAX_ARTIFACT_BYTES) {
+        errors.push(`binary payload ${(totalBlobBytes / 1024 / 1024).toFixed(1)} MB exceeds the ` +
+            `${MAX_ARTIFACT_BYTES / 1024 / 1024} MB per-pack limit`);
     }
     return { ok: errors.length === 0, errors };
 }

package/package.json

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