octwin-cli 0.1.16 → 0.1.20

package/dist/index.js

@@ -13,11 +13,13 @@
  *   octwin login   --url <platformUrl> --token oct_…
  *   octwin whoami  [--url <url>] [--tenant <slug>]
  *   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+ *   octwin pull    <packId> [--dir <out>] [--version v] [--force]  # write a DEPLOYED pack's source back to disk
  *   octwin status  [--dir .]        # did my deploy land? which version is live?
  *   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>] [--media <file|id>] [--json]  # drive a turn via the web channel (+ send media)
+ *   octwin chat    --script <file> [--as h]   # drive a WHOLE conversation, one turn per line (the reliable way to test a flow)
  *   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)
@@ -33,20 +35,32 @@
  * tap id; replay a tap with `--tap "<tap-id>"`. `--help` on any subcommand
  * prints its usage without touching the network.
  *
- * Config resolution (deploy): flags > pack.json (in the pack dir) > env
- * (PACK_PLATFORM_URL / PACK_TENANT / PACK_PROJECT / PACK_TOKEN) > saved login.
+ * For a MULTI-STEP flow use `--script`, not chained invocations. A turn ends on
+ * a quiet gap, which can arrive before the server-side agent loop finishes — so
+ * `chat A && chat B` races it and B can land mid-turn (the agent then fills
+ * required fields with placeholder text, or starts a second workflow run).
+ * `--script` runs the turns in one process, over one connection, in order.
  *
- * The bundle uploaded is every file under the pack dir EXCEPT pack.json, dot
- * files/dirs, node_modules, and build output. The platform re-validates it
+ * Config resolution (deploy): flags > env (PACK_PLATFORM_URL / PACK_TENANT /
+ * PACK_PROJECT / PACK_TOKEN) > saved login (`octwin login` sets both the url and
+ * the token; the token carries its own tenant). Nothing is read from the pack dir.
+ *
+ * The bundle uploaded is every file under the pack dir that `classifyPackPath`
+ * calls content — excluding dot files/dirs, `node_modules/`, build output,
+ * `__snapshots__/`, `*.ts`/`*.tsx` and `*.example`. That is the SAME rule the
+ * operator's GitHub repo import applies. The platform re-validates it
  * (pure-YAML enforcement + manifest/flow Zod) and installs it onto the project.
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, cpSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, cpSync, rmSync } from 'node:fs';
 import { join, resolve, dirname, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { applyRenames } from './lib/rename.js';
 import { validatePackBundle } from './lib/validate.js';
+import { loadAllowedRenderKeys, findRenderKeyViolations, describeRenderFinding } from './lib/render-check.js';
+import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding } from './lib/args-check.js';
+import { classifyPackPath, isSkippedDir } from './lib/pack-source.js';
 // The in-package starter template ships alongside `dist/` and `src/` (both one
 // level under the package root), so `../templates/starter` resolves for the
 // built CLI and `tsx` dev alike.
@@ -217,12 +231,6 @@ async function resolveMediaPart(url, arg) {
     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']);
-/**
- * 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;
@@ -234,6 +242,11 @@ const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
  * 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).
+ *
+ * WHAT is content and WHICH half it lands in are not decided here — `classifyPackPath`
+ * decides, the same rule the operator's GitHub repo import uses. This walk only
+ * supplies the bytes. (It had its own answer once, and the two disagreed: a `*.test.ts`
+ * or `xrm.yaml.example` beside a flow imported fine and failed to deploy.)
  */
 function collectBundleFiles(packDir) {
     const files = {};
@@ -244,17 +257,14 @@ function collectBundleFiles(packDir) {
             const full = join(dir, name);
             const rel = prefix ? `${prefix}/${name}` : name;
             if (statSync(full).isDirectory()) {
-                if (SKIP_DIRS.has(name) || name.startsWith('.'))
-                    continue;
-                walk(full, rel);
+                if (!isSkippedDir(name))
+                    walk(full, rel); // prune before descending
                 continue;
             }
-            if (name === 'pack.json')
-                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 kind = classifyPackPath(rel);
+            if (kind === 'skip')
+                continue;
+            if (kind === 'blob') {
                 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`);
@@ -282,17 +292,18 @@ function readManifestIdVersion(files) {
     }
     return { id: doc.id, version: doc.version };
 }
-function readPackConfig(packDir) {
-    const p = join(packDir, 'pack.json');
-    if (!existsSync(p))
-        return {};
-    try {
-        return JSON.parse(readFileSync(p, 'utf8'));
-    }
-    catch {
-        return {};
-    }
-}
+// ── config (env + saved login) ──────────────────────────────────────────────
+/**
+ * The saved login IS the deploy target. `~/.octwin/credentials.json` is a flat
+ * map of platform url → token, plus ONE reserved key holding the url the last
+ * `octwin login` pointed at. It cannot collide with a token entry: every url key
+ * contains `://`, and `default_url` does not.
+ *
+ * A pack directory therefore holds pack content and nothing else — the deploy
+ * target is a property of the machine, not of the pack. (The retired `pack.json`
+ * was a second home for a fact `octwin login` already stated.)
+ */
+const DEFAULT_URL_KEY = 'default_url';
 function credsPath() { return join(homedir(), '.octwin', 'credentials.json'); }
 function readCreds() {
     try {
@@ -306,6 +317,8 @@ function writeCreds(map) {
     mkdirSync(join(homedir(), '.octwin'), { recursive: true });
     writeFileSync(credsPath(), JSON.stringify(map, null, 2), 'utf8');
 }
+/** The platform url of the last `octwin login` — the default target. */
+function savedDefaultUrl() { return readCreds()[DEFAULT_URL_KEY] ?? ''; }
 // ── update check (daily, fail-silent, TTY-only) ──────────────────────────────
 function updateCachePath() { return join(homedir(), '.octwin', 'update-check.json'); }
 /** True when semver `a` is strictly greater than `b` (simple x.y.z compare). */
@@ -420,7 +433,7 @@ async function notifyIfKbStale(flags) {
         const local = readLocalKb(packDir);
         if (!local?.content_hash)
             return; // never pulled → the skill already says to pull
-        const t = resolveTargetOrNull(flags, packDir);
+        const t = resolveTargetOrNull(flags);
         if (!t)
             return;
         const ctrl = new AbortController();
@@ -463,6 +476,7 @@ function commandTouchesPlatform(command, flags) {
         case 'test':
         case 'chat':
         case 'media':
+        case 'pull':
         case 'records':
         case 'cases':
         case 'logs':
@@ -496,13 +510,9 @@ function cmdInit(flags) {
         description: flags.description ?? undefined,
         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',
-    }, null, 2) + '\n', 'utf8');
+    // Repo hygiene + a README. Nothing else: the scaffold writes pack CONTENT only.
+    // The deploy target is the saved login (`octwin login --url … --token …`), and
+    // the token carries its own tenant + optional project pin.
     writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.pack-bundles/\n.octwin/\n', 'utf8');
     if (!existsSync(join(dir, 'README.md'))) {
         writeFileSync(join(dir, 'README.md'), `# ${id}\n\nA pure-YAML pack for the Octwin platform.\n\n- \`flows/tools/home.flow.yaml\` — the menu hub (your front door); add a row + tool per journey\n- Edit \`manifest.yaml\`, \`prompts/identity.md\`\n- \`octwin validate --remote\` — full platform check before deploy\n- \`octwin deploy\` — deploy + install onto your tenant\n`, 'utf8');
@@ -513,7 +523,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 in pack.json (tenant comes from your token), then:');
+    console.log('  # point the CLI at your platform (the token carries the tenant):');
     console.log('  octwin login --url <platformUrl> --token <deploy-token>');
     console.log('  octwin deploy');
 }
@@ -532,6 +542,55 @@ async function cmdValidate(flags) {
     const packDir = resolve(flags.dir ?? '.');
     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))`);
+    // Render-intent fields, checked against the pulled KB. Skipped (silently) when
+    // the author hasn't pulled the reference yet — Step 0.5 of the skill says to.
+    const allowedRenderKeys = loadAllowedRenderKeys(packDir);
+    if (allowedRenderKeys) {
+        const findings = Object.entries(files)
+            .filter(([p]) => /\.ya?ml$/i.test(p))
+            .flatMap(([p, body]) => {
+            let doc;
+            try {
+                doc = parseYaml(body);
+            }
+            catch {
+                return [];
+            } // a YAML syntax error is the structural gate's to report
+            return findRenderKeyViolations(doc, p, allowedRenderKeys);
+        });
+        if (findings.length) {
+            console.error(`✗ ${findings.length} render-intent field error${findings.length === 1 ? '' : 's'}:`);
+            for (const f of findings)
+                console.error(`  ✗ ${describeRenderFinding(f)}`);
+            die('fix these before deploying — the platform rejects them at load, and before that they rendered as nothing');
+        }
+        console.log('✓ render intents use only fields the platform renders');
+    }
+    // Primitive `args:` keys, same source and same degrade-to-no-op contract.
+    // Cannot see inside a `use:` template body (expansion is the platform's job);
+    // `--remote` covers that.
+    const argSpecs = loadPrimitiveArgSpecs(packDir);
+    if (argSpecs) {
+        const findings = Object.entries(files)
+            .filter(([p]) => /\.ya?ml$/i.test(p))
+            .flatMap(([p, body]) => {
+            let doc;
+            try {
+                doc = parseYaml(body);
+            }
+            catch {
+                return [];
+            }
+            return findArgViolations(doc, p, argSpecs);
+        });
+        if (findings.length) {
+            console.error(`✗ ${findings.length} primitive-argument error${findings.length === 1 ? '' : 's'}:`);
+            for (const f of findings)
+                console.error(`  ✗ ${describeArgFinding(f)}`);
+            die('fix these before deploying — an undeclared argument is dropped with no error at runtime');
+        }
+        console.log('✓ primitive arguments match their declared inputs');
+    }
     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.');
@@ -539,7 +598,7 @@ 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 t = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags);
     const { url } = t;
     console.log(`→ Validating against ${targetLabel(t)} @ ${url} …`);
     const res = await fetchOrDie(`${url}/api/self/p/packs/validate`, {
@@ -595,8 +654,9 @@ async function cmdLogin(flags) {
     const token = flags.token ?? process.env.PACK_TOKEN ?? die('missing --token');
     const creds = readCreds();
     creds[url] = token;
+    creds[DEFAULT_URL_KEY] = url; // login sets the default deploy target
     writeCreds(creds);
-    console.log(`✓ Saved token for ${url}`);
+    console.log(`✓ Saved token for ${url} — now the default target`);
     // 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.
@@ -623,36 +683,35 @@ function authHeaders(t) {
     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 || 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 (!token)
+ *  flags > env > saved login. Tenant is derived from the token server-side, so
+ *  only url + token are required — and `octwin login` supplies both. */
+function resolveTarget(flags) {
+    const t = readTarget(flags);
+    if (!t.url)
+        die('no platform url — run `octwin login --url <url> --token oct_…`, or pass --url / PACK_PLATFORM_URL');
+    if (!t.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 };
+    return t;
 }
 /** 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 || undefined;
-    const project = flags.project || process.env.PACK_PROJECT || cfg.project || undefined;
-    const token = flags.token ?? process.env.PACK_TOKEN ?? readCreds()[url] ?? '';
-    if (!url || !token)
-        return null;
-    return { url, token, tenant, project };
+function resolveTargetOrNull(flags) {
+    const t = readTarget(flags);
+    return t.url && t.token ? t : null;
+}
+/** The raw resolution both wrappers share — may return empty url/token. */
+function readTarget(flags) {
+    const url = (flags.url ?? process.env.PACK_PLATFORM_URL ?? savedDefaultUrl()).replace(/\/$/, '');
+    return {
+        url,
+        token: flags.token ?? process.env.PACK_TOKEN ?? readCreds()[url] ?? '',
+        tenant: flags.tenant || process.env.PACK_TENANT || undefined,
+        project: flags.project || process.env.PACK_PROJECT || undefined,
+    };
 }
 async function cmdWhoami(flags) {
-    const packDir = resolve(flags.dir ?? '.');
-    const t = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags);
     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) {
@@ -667,6 +726,73 @@ async function cmdWhoami(flags) {
             : await res.text();
     die(`token check failed (HTTP ${res.status}) — ${why}`);
 }
+/**
+ * `octwin pull <packId> [--dir <out>] [--version v] [--force]` — write a
+ * DEPLOYED pack's source back to disk.
+ *
+ * The inverse of `deploy`, and the reason it exists: a pack pushed with
+ * `octwin deploy` lives on the platform as an artifact the runtime serves but
+ * nothing hands back, so its only source copy is the machine that pushed it.
+ * Lose that machine — or inherit a pack someone else deployed — and the source is
+ * gone while the bot keeps running. `pull` closes the loop: fetch, fix, redeploy.
+ *
+ * You may pull a pack YOUR tenant owns (an operator token may pull any). A pack
+ * you merely installed from the marketplace is not yours to read.
+ *
+ * Writes into `<out>/` and refuses a non-empty directory unless `--force`, so it
+ * can't quietly clobber local edits. The pulled directory is immediately
+ * `octwin deploy`-able back to where it came from — the target is the saved
+ * login, so nothing machine-specific needs to land in the pack dir.
+ */
+async function cmdPull(flags) {
+    const packId = flags._[0] ?? '';
+    if (!packId)
+        die('usage: octwin pull <packId> [--dir <out>] [--version <v>] [--force]');
+    const outDir = resolve(flags.dir ?? packId);
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const qs = typeof flags.version === 'string' ? `?version=${encodeURIComponent(flags.version)}` : '';
+    console.log(`→ Pulling ${packId}${qs ? `@${flags.version}` : ''} from ${targetLabel(t)} @ ${url} …`);
+    const res = await fetchOrDie(`${url}/api/self/p/packs/${encodeURIComponent(packId)}/source${qs}`, { headers: authHeaders(t) }, 'pull');
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        json = text;
+    }
+    if (!res.ok) {
+        console.error(`✗ pull failed (HTTP ${res.status})`);
+        printAuthHint(res.status, url);
+        if (res.status === 403) {
+            console.error('  → a pack is pullable by the tenant that OWNS it (deployed it), or by an operator.');
+        }
+        console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
+        process.exit(1);
+    }
+    const files = json.files ?? {};
+    const blobs = json.blobs ?? {};
+    const total = Object.keys(files).length + Object.keys(blobs).length;
+    if (total === 0)
+        die(`${packId}@${json.version} has no files — nothing to write`);
+    if (existsSync(outDir) && readdirSync(outDir).length > 0 && flags.force !== true) {
+        die(`${outDir} is not empty — pass --force to overwrite it`);
+    }
+    for (const [rel, body] of Object.entries(files)) {
+        const p = join(outDir, rel);
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, body, 'utf8');
+    }
+    for (const [rel, b64] of Object.entries(blobs)) {
+        const p = join(outDir, rel);
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, Buffer.from(b64, 'base64'));
+    }
+    console.log(`✓ Pulled ${json.pack_id}@${json.version} → ${outDir}`);
+    console.log(`  ${Object.keys(files).length} file(s)${Object.keys(blobs).length ? `, ${Object.keys(blobs).length} blob(s)` : ''}   content_sha ${String(json.content_sha).slice(0, 12)}…`);
+    console.log(`\nFix it, then: octwin deploy --dir ${outDir}`);
+}
 /**
  * Read the deploy SSE stream, printing each progress frame's message live, and
  * return the terminal `done`/`error` event (or null if the stream ended without
@@ -734,11 +860,18 @@ function printDeploySuccess(id, version, t, r) {
         if (parts.length)
             console.log(`  Seeded: ${parts.join(', ')}`);
     }
+    // A redeploy rebuilds the pack's tools, and suspended flow runs live with them.
+    // Say so: otherwise the next tap on a card rendered before the deploy comes back
+    // stale and reads like a flow bug.
+    const dropped = r?.suspended_runs_dropped;
+    if (dropped > 0) {
+        console.log(`  ⓘ ${dropped} suspended run(s) invalidated — a tap on any card rendered before this deploy will report a stale run. Start those conversations again.`);
+    }
     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 t = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags);
     const { url } = t;
     const { id, version, files, blobs } = localValidate(packDir);
     const endpoint = `${url}/api/self/p/packs/deploy`;
@@ -789,7 +922,7 @@ async function cmdDeploy(flags) {
 }
 async function cmdStatus(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const t = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags);
     const { url } = t;
     const manifestPath = join(packDir, 'manifest.yaml');
     if (!existsSync(manifestPath))
@@ -845,9 +978,130 @@ async function cmdStatus(flags) {
         console.log(`  (local manifest is ${localVersion}; deployed is ${json.installed_version} — \`octwin deploy\` to push local edits.)`);
     }
 }
+/** Filesystem-safe entry filename (entry names are already tame — `record_list`,
+ *  `whatsapp`, `xrm` — but never trust a name straight into a path). */
+function kbEntryFileName(name) {
+    return name.replace(/[^A-Za-z0-9._-]/g, '_');
+}
+/** First sentence (or a hard clamp) of a possibly-long `describe` — INDEX.md needs
+ *  one scannable line per entry, not the whole contract.
+ *
+ *  Sentence detection ignores punctuation nested in brackets: primitive `describe`
+ *  text routinely inlines an envelope shape (`… { rows, total, …, refs? } …`) whose
+ *  `?` would otherwise cut the summary off mid-brace. */
+function kbOneLiner(text, max = 160) {
+    if (typeof text !== 'string' || !text.trim())
+        return '';
+    const flat = text.replace(/\s+/g, ' ').trim();
+    let depth = 0;
+    let end = -1;
+    for (let i = 0; i < flat.length; i++) {
+        const ch = flat[i];
+        if (ch === '{' || ch === '(' || ch === '[')
+            depth++;
+        else if (ch === '}' || ch === ')' || ch === ']')
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0 && (ch === '.' || ch === '!' || ch === '?')) {
+            const next = flat[i + 1];
+            if (next === undefined || next === ' ') {
+                end = i + 1;
+                break;
+            }
+        }
+    }
+    const line = end >= 40 ? flat.slice(0, end) : flat;
+    return line.length > max ? line.slice(0, max - 1).trimEnd() + '…' : line;
+}
+/** Enumerate a catalog's entries per the platform-supplied descriptor. Handles both
+ *  collection shapes in use: an ARRAY of named objects (`primitives`, keyed by
+ *  `name`) and an OBJECT MAP keyed by entry name (`declarations`, `system-entities`).
+ *  Returns [] when the descriptor doesn't fit the payload, so a shape surprise
+ *  degrades to "write the flat file" instead of throwing mid-pull. */
+function enumerateKbEntries(catalog, d) {
+    const collection = catalog?.[d.at];
+    if (Array.isArray(collection)) {
+        if (!d.by)
+            return [];
+        const out = [];
+        for (const item of collection) {
+            const name = item?.[d.by];
+            if (typeof name !== 'string' || !name)
+                return []; // not the shape we were told — bail wholesale
+            out.push({ name, summary: kbOneLiner(d.summary ? item[d.summary] : ''), value: item });
+        }
+        return out;
+    }
+    if (collection && typeof collection === 'object') {
+        return Object.entries(collection).map(([name, value]) => ({
+            name,
+            summary: kbOneLiner(d.summary ? value?.[d.summary] : ''),
+            value,
+        }));
+    }
+    return [];
+}
+/**
+ * Build `INDEX.md` — the map an authoring agent reads FIRST.
+ *
+ * The KB is ~800 KB across three dozen files; reading it whole costs more context
+ * than the pack being authored. This index is one ~7k-token read that names every
+ * doc and every catalog entry with a one-line summary and its exact path, so the
+ * agent can jump straight to the ~600-token file it actually needs.
+ */
+function buildKbIndexMarkdown(bundle, exploded) {
+    const index = bundle.index ?? [];
+    const docs = index.filter(e => e.kind === 'doc');
+    const catalogs = index.filter(e => e.kind === 'catalog');
+    const L = [];
+    L.push('# Octwin platform capability reference — INDEX');
+    L.push('');
+    L.push(`Reference version ${bundle.version ?? '?'} · content_hash \`${bundle.content_hash ?? '?'}\` · pulled ${bundle.generated_at ?? '?'}`);
+    L.push('');
+    L.push('**This is the map. Read it, then open only the specific file you need — never a whole catalog.**');
+    L.push('Everything the platform supports is here; if a step, function, field, or render intent is NOT in');
+    L.push('this index, it does not exist for a pure-YAML pack. Do not fill a gap from memory.');
+    L.push('');
+    L.push('## Start here');
+    L.push('');
+    L.push('1. `craft-capabilities.md` — how this reference fits together.');
+    L.push('2. `craft-ux.md` — what a *good* pack looks like (home hub, rich cards, confirm-before-commit).');
+    L.push('3. `craft-flows.md` — the flow DSL in practice.');
+    L.push('4. Then the tables below, on demand.');
+    L.push('');
+    L.push('## Guides & reference docs');
+    L.push('');
+    L.push('| Doc | Read it for | File |');
+    L.push('|---|---|---|');
+    for (const d of docs)
+        L.push(`| ${d.title ?? d.key} | ${kbOneLiner(d.summary)} | \`${d.key}.md\` |`);
+    L.push('');
+    L.push('## Catalogs — exact machine-readable schemas');
+    L.push('');
+    for (const c of catalogs) {
+        const entries = exploded.get(c.key);
+        L.push(`### ${c.title ?? c.key}`);
+        L.push('');
+        L.push(kbOneLiner(c.summary, 400));
+        L.push('');
+        if (!entries || entries.length === 0) {
+            L.push(`Single document: \`${c.key}.json\``);
+            L.push('');
+            continue;
+        }
+        L.push(`${entries.length} entries in \`${c.key}/\` — one file each.`);
+        L.push('');
+        L.push('| Entry | What it does | File |');
+        L.push('|---|---|---|');
+        for (const e of entries) {
+            L.push(`| \`${e.name}\` | ${e.summary.replace(/\|/g, '\\|')} | \`${c.key}/${kbEntryFileName(e.name)}.json\` |`);
+        }
+        L.push('');
+    }
+    return L.join('\n') + '\n';
+}
 async function cmdPlatformKb(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const t = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags);
     const { url } = t;
     console.log(`→ Pulling the platform capability reference from ${url} …`);
     const res = await fetchOrDie(`${url}/api/self/t/octwin-platform-kb`, {
@@ -872,27 +1126,65 @@ async function cmdPlatformKb(flags) {
     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.
+    //
+    // WIPE first: this directory is a pure cache of one pull, and now that catalogs
+    // explode into per-entry files, leftovers actively mislead. A withdrawn primitive
+    // or a retired catalog would otherwise linger as a file the authoring agent reads
+    // as current — the exact "capability that doesn't exist" failure the KB prevents.
+    //
+    // Clear the CONTENTS, not the directory itself: on Windows a directory that is
+    // any process's working directory cannot be removed (EPERM), and an author with
+    // a shell sitting in the pulled reference is not an error case worth failing a
+    // pull over. Each removal is individually tolerant for the same reason.
     const outDir = join(packDir, '.octwin', 'platform-kb');
     mkdirSync(outDir, { recursive: true });
+    for (const stale of readdirSync(outDir)) {
+        try {
+            rmSync(join(outDir, stale), { recursive: true, force: true });
+        }
+        catch { /* keep going; we overwrite below */ }
+    }
     let mdCount = 0;
-    let jsonCount = 0;
     for (const [key, val] of Object.entries(bundle.docs ?? {})) {
         if (val == null)
             continue;
         writeFileSync(join(outDir, `${key}.md`), val, 'utf8');
         mdCount++;
     }
+    // Catalogs: EXPLODE the ones the platform told us how to enumerate (one file per
+    // primitive / declaration / render intent / …), so reaching one entry costs a
+    // ~600-token read instead of parsing a 120 KB blob. Catalogs with no descriptor
+    // (or an unexpected payload shape) fall back to the flat file.
+    const byKey = new Map((bundle.index ?? []).map(e => [e.key, e]));
+    const exploded = new Map();
+    let catalogCount = 0;
+    let entryCount = 0;
     for (const [key, val] of Object.entries(bundle.sources ?? {})) {
         if (val == null)
             continue;
-        writeFileSync(join(outDir, `${key}.json`), JSON.stringify(val, null, 2) + '\n', 'utf8');
-        jsonCount++;
+        catalogCount++;
+        const descriptor = byKey.get(key)?.entries;
+        const entries = descriptor ? enumerateKbEntries(val, descriptor) : [];
+        if (entries.length === 0) {
+            writeFileSync(join(outDir, `${key}.json`), JSON.stringify(val, null, 2) + '\n', 'utf8');
+            continue;
+        }
+        const dir = join(outDir, key);
+        mkdirSync(dir, { recursive: true });
+        for (const entry of entries) {
+            writeFileSync(join(dir, `${kbEntryFileName(entry.name)}.json`), JSON.stringify(entry.value, null, 2) + '\n', 'utf8');
+        }
+        exploded.set(key, entries);
+        entryCount += entries.length;
     }
+    // The map the authoring skill reads first.
+    writeFileSync(join(outDir, 'INDEX.md'), buildKbIndexMarkdown(bundle, exploded), 'utf8');
     // Persist `content_hash` too — the staleness observer (`notifyIfKbStale`) reads
     // it back and compares against the platform's current hash to nudge a re-pull.
     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 ?? '?'})`);
+    console.log(`  ${mdCount} markdown docs + ${catalogCount} catalogs (${entryCount} entries, one file each) — reference version ${bundle.version ?? '?'}`);
+    console.log('  Start at INDEX.md — it maps every doc and every catalog entry to its file.');
     // 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) {
@@ -935,8 +1227,7 @@ function targetLabel(t) {
 }
 /** `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 t = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p`;
     const entity = flags._[0];
@@ -956,8 +1247,10 @@ async function cmdRecords(flags) {
             return;
         }
         console.log(`Entities in ${targetLabel(t)}:`);
+        // `open_count` is the non-archived, non-terminal, RBAC-scoped subset — not
+        // the entity's total. Label it, or it reads as "this entity has 2 records".
         for (const e of ents)
-            console.log(`  ${e.entity}  (${e.open_count ?? 0} records)`);
+            console.log(`  ${e.entity}  (${e.open_count ?? 0} open)`);
         console.log('\nList records:  octwin records <entity>');
         return;
     }
@@ -990,8 +1283,7 @@ async function cmdRecords(flags) {
 /** `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 t = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p`;
     const convId = flags._[0];
@@ -1165,8 +1457,135 @@ class SseFrameReader {
 const REPLAY_SETTLE_MS = 400; // quiet gap that marks the end of the connect replay burst
 const TURN_SETTLE_MS = 2_000; // quiet gap after a render = the turn finished sending
 const REPLY_TIMEOUT_MS = 45_000; // hard cap waiting for the first render of the turn
-/** `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--json]` — drive one
- *  turn through the dev web channel and print everything it rendered.
+/**
+ * Parse a `--script` file — ONE TURN PER LINE, in order:
+ *
+ *   # a comment, and blank lines, are skipped
+ *   احجز موعد                      → a typed message
+ *   tap:t:invoke:book:doctor_id=D1  → press a rendered row / button
+ *   media:./licence.jpg             → upload a file
+ *   media:./licence.jpg | here you go   → upload WITH a caption
+ *
+ * A `tap:` line keeps everything after the first colon verbatim, because a tap id
+ * is itself colon-delimited (`t:invoke:target:bindings`).
+ */
+function parseChatScript(body) {
+    const turns = [];
+    for (const raw of body.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        if (line.startsWith('tap:')) {
+            turns.push({ tap: line.slice(4).trim() });
+            continue;
+        }
+        if (line.startsWith('media:')) {
+            const rest = line.slice(6);
+            const bar = rest.indexOf('|');
+            turns.push(bar === -1
+                ? { media: rest.trim() }
+                : { media: rest.slice(0, bar).trim(), text: rest.slice(bar + 1).trim() });
+            continue;
+        }
+        turns.push({ text: line });
+    }
+    return turns;
+}
+/**
+ * Send ONE turn and print everything it rendered. Returns the new frame boundary
+ * (so the next turn only accepts frames newer than this turn's output) and how
+ * many renders arrived.
+ *
+ * Splitting this out is what makes `--script` reliable. Driving a multi-step flow
+ * by chaining shell invocations (`chat A && chat B`) races the agent loop: this
+ * command ends a turn on a QUIET GAP, and the server-side loop can still be
+ * running when the process exits, so the next invocation's inbound lands
+ * mid-turn. The agent then fills required fields with placeholder text, or starts
+ * a second workflow run. Inside one process the loop simply waits for the settle
+ * before sending the next turn, over the same SSE connection.
+ */
+async function runChatTurn(args) {
+    const { url, tenant, project, from, turn, frames, asJson } = args;
+    let boundary = args.boundary;
+    // Fresh idempotency key per turn — the platform dedups inbound on `local_id`
+    // for 5 minutes, so a reused id makes the second turn a silent no-op.
+    const localId = `cli-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const inbound = `${url}/api/web/inbound/${tenant}/${project}`;
+    let postRes;
+    if (turn.media && !turn.tap) {
+        const { blob, kind, filename } = await resolveMediaPart(url, turn.media);
+        console.log(`→ [${from}] (media:${kind}) ${filename}${turn.text ? ` — "${turn.text}"` : ''}`);
+        const form = new FormData();
+        form.append('type', kind);
+        form.append('from', from);
+        form.append('local_id', localId);
+        if (turn.text)
+            form.append('caption', turn.text);
+        form.append('file', blob, filename);
+        postRes = await fetchOrDie(inbound, { method: 'POST', body: form }, 'send media');
+    }
+    else {
+        console.log(`→ [${from}] ${turn.tap ? `(tap) ${turn.tap}` : turn.text}`);
+        const body = turn.tap
+            ? { type: 'interactive', from, tap_id: turn.tap, ...(turn.text ? { raw_title: turn.text } : {}), local_id: localId }
+            : { type: 'text', from, text: turn.text, local_id: localId };
+        postRes = await fetchOrDie(inbound, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        }, 'send message');
+    }
+    if (!postRes.ok) {
+        await frames.cancel();
+        die(`send rejected (HTTP ${postRes.status}): ${await postRes.text()}`);
+    }
+    if (!asJson)
+        console.log(`  … delivered — waiting for the reply (up to ${Math.round(REPLY_TIMEOUT_MS / 1000)}s)`);
+    // Collect THIS turn's renders (id > boundary). A turn can send several
+    // messages, so keep reading until a quiet gap after the last render.
+    const deadline = Date.now() + REPLY_TIMEOUT_MS;
+    let rendersSeen = 0;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        const f = await frames.next(rendersSeen > 0 ? TURN_SETTLE_MS : Math.min(remaining, REPLY_TIMEOUT_MS));
+        if (f === 'timeout') {
+            if (rendersSeen > 0)
+                break;
+            else
+                continue;
+        }
+        if (f === 'done')
+            break;
+        if (f.id != null && f.id <= boundary)
+            continue; // late replay stragglers
+        if (f.id != null)
+            boundary = f.id;
+        if (asJson) {
+            console.log(JSON.stringify(f.ev));
+            if (f.ev?.kind === 'render')
+                rendersSeen++;
+            continue;
+        }
+        if (f.ev?.kind !== 'render')
+            continue; // status/typing noise
+        rendersSeen++;
+        console.log(`← ${f.ev.body ?? '(no text body)'}${f.ev.hint?.type && f.ev.hint.type !== 'text' ? `   (render: ${f.ev.hint.type})` : ''}`);
+        printHint(f.ev.hint);
+    }
+    return { boundary, rendersSeen };
+}
+/** `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--script <file>] [--json]`
+ *  — drive a turn (or a whole scripted conversation) through the dev web channel
+ *  and print everything it rendered.
+ *
+ *  ONE TURN PER INVOCATION. A turn ends on a QUIET GAP (`TURN_SETTLE_MS`), which
+ *  can arrive before the server-side agent loop has actually finished — so
+ *  chaining invocations (`chat A && chat B`) races it, and the second inbound can
+ *  land mid-turn (the agent then fills required fields with placeholder text, or
+ *  starts a second workflow run). To drive a multi-step flow, use `--script`: it
+ *  runs the turns in one process over one connection, waiting for each to settle.
  *
  *  Multi-turn works: the platform keeps ONE open conversation per handle, so the
  *  same `--as` continues the same conversation. Two traps this command handles:
@@ -1176,18 +1595,19 @@ const REPLY_TIMEOUT_MS = 45_000; // hard cap waiting for the first render of the
  *  drain the replay first and only accept frames newer than it as the reply
  *  (naively printing the first render showed LAST turn's message again). */
 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(/\/$/, '');
+    // Chat needs a url but NOT a token (an explicit --tenant is enough), so it reads
+    // the raw target rather than going through the token-requiring `resolveTarget`.
+    const raw = readTarget(flags);
+    const url = raw.url;
     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 || '';
+        die('no platform url — run `octwin login --url <url> --token oct_…`, or pass --url / PACK_PLATFORM_URL');
+    let tenant = raw.tenant ?? '';
+    let project = raw.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] ?? '';
+        const token = raw.token;
         if (token) {
             try {
                 const who = await fetch(`${url}/api/self/t/whoami`, {
@@ -1203,7 +1623,7 @@ async function cmdChat(flags) {
         }
     }
     if (!tenant)
-        die('no tenant — set --tenant / PACK_TENANT / pack.json, or pass a --token to derive it');
+        die('no tenant — set --tenant / PACK_TENANT, or log in so the token can supply it');
     if (!project)
         project = 'main';
     const from = flags.as ?? 'cli-tester';
@@ -1211,10 +1631,23 @@ async function cmdChat(flags) {
     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 && !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)}`;
+    const scriptArg = typeof flags.script === 'string' ? flags.script : undefined;
+    let turns;
+    if (scriptArg) {
+        const scriptPath = resolve(scriptArg);
+        if (!existsSync(scriptPath))
+            die(`no such script file: ${scriptPath}`);
+        turns = parseChatScript(readFileSync(scriptPath, 'utf8'));
+        if (turns.length === 0)
+            die(`${scriptPath} has no turns (blank lines and # comments are skipped)`);
+    }
+    else {
+        if (!message && !tapId && !mediaArg) {
+            die('usage: octwin chat "your message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]\n' +
+                '   or: octwin chat --script <file> [--as <handle>]   (one turn per line; "tap:<id>" / "media:<path>")');
+        }
+        turns = [{ ...(message ? { text: message } : {}), ...(tapId ? { tap: tapId } : {}), ...(mediaArg ? { media: mediaArg } : {}) }];
+    }
     if (!asJson)
         console.log(`→ Connecting to ${tenant}/${project} as '${from}' …`);
     const evRes = await fetchOrDie(`${url}/api/web/events/${tenant}/${project}/${encodeURIComponent(from)}`, { headers: { accept: 'text/event-stream' } }, 'open chat stream');
@@ -1236,74 +1669,25 @@ async function cmdChat(flags) {
         if (f.id != null && f.id > boundary)
             boundary = f.id;
     }
-    // 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()}`);
-    }
-    if (!asJson)
-        console.log(`  … delivered — waiting for the reply (up to ${Math.round(REPLY_TIMEOUT_MS / 1000)}s)`);
-    // Phase 3 — collect THIS turn's renders (id > boundary). A turn can send
-    // several messages, so keep reading until a quiet gap after the last render.
-    const deadline = Date.now() + REPLY_TIMEOUT_MS;
-    let rendersSeen = 0;
-    for (;;) {
-        const remaining = deadline - Date.now();
-        if (remaining <= 0)
-            break;
-        const f = await frames.next(rendersSeen > 0 ? TURN_SETTLE_MS : Math.min(remaining, REPLY_TIMEOUT_MS));
-        if (f === 'timeout') {
-            if (rendersSeen > 0)
-                break;
-            else
-                continue;
-        }
-        if (f === 'done')
-            break;
-        if (f.id != null && f.id <= boundary)
-            continue; // late replay stragglers
-        if (asJson) {
-            console.log(JSON.stringify(f.ev));
-            if (f.ev?.kind === 'render')
-                rendersSeen++;
-            continue;
+    // Phase 2+3 — run each turn in order, over the SAME connection. One turn is
+    // the normal case; `--script` drives a whole conversation.
+    let totalRenders = 0;
+    for (const [i, turn] of turns.entries()) {
+        if (turns.length > 1)
+            console.log(`\n── turn ${i + 1}/${turns.length} ──`);
+        const r = await runChatTurn({ url, tenant, project, from, turn, frames, boundary, asJson });
+        boundary = r.boundary;
+        totalRenders += r.rendersSeen;
+        if (r.rendersSeen === 0 && turns.length > 1) {
+            // Stop rather than fire the rest of the script into a conversation that
+            // isn't answering — the remaining turns would land out of context.
+            await cancel();
+            console.error(`  turn ${i + 1} produced no render after ${Math.round(REPLY_TIMEOUT_MS / 1000)}s — stopping the script here.`);
+            process.exit(1);
         }
-        if (f.ev?.kind !== 'render')
-            continue; // status/typing noise
-        rendersSeen++;
-        console.log(`← ${f.ev.body ?? '(no text body)'}${f.ev.hint?.type && f.ev.hint.type !== 'text' ? `   (render: ${f.ev.hint.type})` : ''}`);
-        printHint(f.ev.hint);
     }
     await cancel();
-    if (rendersSeen === 0) {
+    if (totalRenders === 0) {
         console.error(`  no reply after ${Math.round(REPLY_TIMEOUT_MS / 1000)}s — the pack may not be warm yet, or the turn produced no render.`);
         process.exit(1);
     }
@@ -1318,8 +1702,7 @@ 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 t = resolveTarget(flags);
     const { url } = t;
     const prompt = flags._[1];
     if (!prompt)
@@ -1374,8 +1757,7 @@ async function cmdMedia(flags) {
 /** `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 t = resolveTarget(flags, packDir);
+    const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p`;
     const caseId = flags._[0];
@@ -1517,8 +1899,7 @@ function printGoverned(label, g) {
  *  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 t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/agents`;
     const ref = flags._[0];
@@ -1615,8 +1996,7 @@ function printPaymentNote(paymentStatus) {
  *  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 t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/orders`;
     const referenceId = flags._[0];
@@ -1689,8 +2069,7 @@ function printNoAnalyticsData(entity) {
  *  [--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 t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/xrm/analytics`;
     const entity = flags._[0];
@@ -1812,8 +2191,7 @@ async function cmdAnalytics(flags) {
  *  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 t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/catalog`;
     const asJson = flags.json === true;
@@ -1873,8 +2251,7 @@ async function cmdCatalog(flags) {
  *  — 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 t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/scheduling`;
     const asJson = flags.json === true;
@@ -1961,7 +2338,7 @@ Multi-turn: the platform keeps ONE open conversation per --as handle — consecu
 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.
+Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
 Per-command usage: octwin <command> --help`);
 }
 /** Per-subcommand usage — printed for `octwin <cmd> --help|-h` BEFORE any
@@ -1974,7 +2351,8 @@ const COMMAND_HELP = {
   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,
-  and echo the workspace + project pin + scopes the token reaches.`,
+  make that url the DEFAULT deploy target for every later command, and echo the
+  workspace + project pin + scopes the token reaches.`,
     whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
     deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
@@ -1992,14 +2370,37 @@ 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).`,
+    pull: `octwin pull <packId> [--dir <out>] [--version <v>] [--force]
+  Write a DEPLOYED pack's source back to disk — the inverse of deploy.
+  A pack pushed with 'octwin deploy' lives on the platform as an artifact the
+  runtime serves but nothing hands back, so its only source copy is the machine
+  that pushed it. Pull it, fix it, redeploy it.
+  Defaults to the version installed on the target project; --version overrides.
+  --dir defaults to ./<packId>; a non-empty dir needs --force.
+  The pulled dir redeploys where it came from — the target is your saved login.
+  You may pull a pack your tenant OWNS (deployed); an operator token pulls any.`,
     chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
-  Drive one turn through the dev web channel and print every render with its
+       octwin chat --script <file> [--as <handle>] [--json]
+  Drive ONE turn through the dev web channel and print every render with its
   tap ids. Same --as handle = same conversation (multi-turn works).
   --tap presses a rendered button/list row instead of sending text.
   --media uploads a local file (or a media id from 'media generate --json') as
   an image/document/audio inbound — any "message" rides as its caption; feeds a
   running media-collect flow (e.g. activate-app).
-  --json dumps the raw SSE envelopes for the turn.`,
+  --json dumps the raw SSE envelopes for the turn.
+
+  --script drives a WHOLE conversation from a file, ONE TURN PER LINE, in one
+  process over one connection — waiting for each turn to settle before sending
+  the next. Use this for any multi-step flow: chaining shell invocations races
+  the agent loop, because a turn ends on a quiet gap that can arrive while the
+  server is still working (the symptom is placeholder-filled fields or a second
+  workflow run). Blank lines and # comments are skipped:
+
+    # book an appointment end to end
+    احجز موعد
+    tap:t:invoke:book-appointment:doctor_id=D1
+    media:./licence.jpg | here is my licence
+    tap:t:resume:book-appointment:run_id=R1;_ctl_approved=true`,
     media: `octwin media generate "<prompt>" [--out <file.png>] [--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
@@ -2066,6 +2467,9 @@ async function main() {
         case 'deploy':
             await cmdDeploy(flags);
             break;
+        case 'pull':
+            await cmdPull(flags);
+            break;
         case 'status':
             await cmdStatus(flags);
             break;