@factiii/runner 0.12.1 → 0.13.0

package/dist/cli.js

@@ -3984,7 +3984,7 @@ var require_has_flag = __commonJS({
 var require_supports_color = __commonJS({
   "../../node_modules/debug/node_modules/supports-color/index.js"(exports2, module2) {
     "use strict";
-    var os7 = require("os");
+    var os8 = require("os");
     var hasFlag = require_has_flag();
     var env = process.env;
     var forceColor;
@@ -4022,7 +4022,7 @@ var require_supports_color = __commonJS({
       }
       const min = forceColor ? 1 : 0;
       if (process.platform === "win32") {
-        const osRelease = os7.release().split(".");
+        const osRelease = os8.release().split(".");
         if (Number(process.versions.node.split(".")[0]) >= 8 && Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
           return Number(osRelease[2]) >= 14931 ? 3 : 2;
         }
@@ -12928,7 +12928,8 @@ function hostSpacePaths(spaceDir) {
     state: import_path.default.join(spaceDir, "state"),
     backups: import_path.default.join(spaceDir, "backups"),
     builds: import_path.default.join(spaceDir, "builds"),
-    bin: import_path.default.join(spaceDir, "bin")
+    bin: import_path.default.join(spaceDir, "bin"),
+    scratchpad: import_path.default.join(spaceDir, "scratchpad")
   };
 }
 function worktreeFor(paths, workName) {
@@ -13885,6 +13886,7 @@ function hostTarget(spaceDir, extraEnv) {
       const env = {};
       const ports = readSpacePorts(spaceDir);
       if (ports.length) env.FACTIII_PORTS = ports.join(",");
+      env.SCRATCHPAD = paths.scratchpad;
       return { ...env, ...extraEnv?.() };
     },
     agentEnv() {
@@ -14145,6 +14147,9 @@ function createEventSink(send, spaceSlug, notify) {
     emitBareFsChange(postId, change) {
       send(channel(`bare-fs:${postId}`), change);
     },
+    emitScratchpad(payload) {
+      send(channel("scratchpad"), payload);
+    },
     emitActivityUpdate(activity) {
       send(channel("activity-update"), activity);
     }
@@ -14161,6 +14166,18 @@ var import_promises5 = __toESM(require("fs/promises"));
 var import_os2 = __toESM(require("os"));
 var import_path7 = __toESM(require("path"));
 
+// ../../shared/all/domains/products.ts
+var TRONS_PER_USD = 1e6;
+var TRONS_PER_CENT = TRONS_PER_USD / 100;
+var FOUNDERS_REFUND_WINDOW_DAYS = 60;
+var FOUNDERS_REFUND_POLICY = `Refundable within ${FOUNDERS_REFUND_WINDOW_DAYS} days of purchase \u2014 after that, all sales are final.`;
+
+// ../../shared/all/domains/autoTopUp.ts
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var MONTH_MS = 30 * DAY_MS;
+var CLAIM_STALE_MS = 5 * 60 * 1e3;
+var MIN_THRESHOLD_TRONS = TRONS_PER_CENT;
+
 // ../../shared/all/domains/posts.ts
 var postDataSort = /* @__PURE__ */ ((postDataSort2) => {
   postDataSort2["DAILY"] = "DAILY";
@@ -14363,7 +14380,11 @@ var checkPurchaseSchema = external_exports.object({
   productId: external_exports.string(),
   type: external_exports.enum(["STRIPE", "GOOGLE", "APPLE"]),
   receivedPrice: external_exports.number().int().min(0, "Received price must be a positive integer in cents"),
-  currency: external_exports.string().length(3).default("USD")
+  currency: external_exports.string().length(3).default("USD"),
+  // Explicit consent to keep this card for auto top-up. Card-network rules
+  // require the buyer to agree before a card may be charged while they are not
+  // present, so this must come from a checkbox they ticked — never a default.
+  saveCardForAutoTopUp: external_exports.boolean().default(false)
 });
 var creditPurchaseSchema = external_exports.object({
   orderId: external_exports.string(),
@@ -14666,6 +14687,19 @@ var skillFrontmatterSchema = external_exports.object({
 }).strict();
 var skillAgentSchema = external_exports.enum(["claude", "codex"]);
 var skillScopeSchema = external_exports.enum(["global", "repo"]);
+var autoTopUpSchema = external_exports.object({
+  enabled: external_exports.boolean(),
+  productId: external_exports.number().int().positive(),
+  thresholdTrons: external_exports.number().int().min(MIN_THRESHOLD_TRONS),
+  dailyCapCents: external_exports.number().int().min(0),
+  monthlyCapCents: external_exports.number().int().min(0),
+  // Alerts. `alertBalanceTrons` is null when the low-balance warning is off;
+  // it works independently of `enabled`, since with auto top-up off it is the
+  // only safety net there is.
+  alertOnTopUp: external_exports.boolean(),
+  alertBalanceTrons: external_exports.number().int().min(MIN_THRESHOLD_TRONS).nullable(),
+  alertNearCap: external_exports.boolean()
+});
 
 // ../../shared/all/helpers/board-agent-core/host-deploy.ts
 var import_child_process3 = require("child_process");
@@ -17984,6 +18018,7 @@ var TerminalModeEngine = class {
       paths.worktrees,
       paths.repo,
       paths.workspace,
+      paths.scratchpad,
       `${paths.root}/drops`
     ];
     const watcher = new WorkspaceWatcher(
@@ -19825,6 +19860,204 @@ async function getDriveRoot(accessToken) {
   };
 }
 
+// ../../shared/all/helpers/scratchpad.ts
+var SCRATCHPAD_MAX_BYTES = 12e6;
+var SCRATCHPAD_MAX_ITEMS = 200;
+var SCRATCHPAD_CHUNK_BYTES = 512 * 1024;
+var SCRATCHPAD_MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024;
+var KIND_BY_EXT = {
+  png: "image",
+  jpg: "image",
+  jpeg: "image",
+  gif: "image",
+  webp: "image",
+  avif: "image",
+  bmp: "image",
+  svg: "image",
+  mp4: "video",
+  webm: "video",
+  mov: "video",
+  m4v: "video",
+  mp3: "audio",
+  wav: "audio",
+  m4a: "audio",
+  ogg: "audio",
+  aac: "audio",
+  flac: "audio",
+  pdf: "pdf",
+  html: "html",
+  htm: "html",
+  md: "markdown",
+  markdown: "markdown",
+  url: "link"
+};
+function scratchpadExt(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0 || dot === name.length - 1) return "";
+  return name.slice(dot + 1).toLowerCase();
+}
+function scratchpadKind(name) {
+  return KIND_BY_EXT[scratchpadExt(name)] ?? "text";
+}
+function isSafeScratchpadName(name) {
+  if (!name || name.length > 255) return false;
+  if (name.startsWith(".")) return false;
+  return /^[A-Za-z0-9][A-Za-z0-9._ -]*$/.test(name);
+}
+
+// ../../shared/all/helpers/board-agent-core/scratchpad-store.ts
+function shEscape2(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+var STAT_META = `stat -f '%m %z' "$f" 2>/dev/null || stat -c '%Y %s' "$f" 2>/dev/null`;
+var TOO_LARGE = "Scratchpad item is too large to open here.";
+var ScratchpadStore = class {
+  /**
+   * @param target Resolved per call, never held: the space's exec target is
+   *               rebuilt as the space provisions, and a captured one would go
+   *               on pointing at the tree it was built for.
+   * @param emit   Tells connected clients the directory moved. Carries a
+   *               timestamp only: the panel refetches the whole listing.
+   */
+  constructor(target, emit) {
+    this.target = target;
+    this.emit = emit;
+    this.watcher = null;
+  }
+  dir() {
+    return this.target().paths.scratchpad;
+  }
+  /**
+   * Everything on the scratchpad, newest first.
+   *
+   * Dotfiles are skipped: the panel is a display surface, and `.DS_Store` is
+   * not something anyone drew. So are subdirectories: the scratchpad is flat,
+   * which is what lets a name be an id everywhere else in this file.
+   */
+  async list() {
+    const dir = this.dir();
+    this.startWatching();
+    const out = await this.target().run([
+      "sh",
+      "-c",
+      `mkdir -p ${shEscape2(dir)} && cd ${shEscape2(dir)} && for f in *; do
+          [ -f "$f" ] || continue
+          meta=$(${STAT_META}) || continue
+          echo "$meta $f"
+        done | LC_ALL=C sort -rn | head -n ${SCRATCHPAD_MAX_ITEMS}`
+    ]);
+    const items = [];
+    for (const line of out.split("\n")) {
+      const match = /^(\d+) (\d+) (.+)$/.exec(line);
+      if (!match) continue;
+      const [, mtime, size, name] = match;
+      if (!isSafeScratchpadName(name)) continue;
+      const bytes = Number(size);
+      items.push({
+        name,
+        kind: scratchpadKind(name),
+        size: bytes,
+        // stat reports seconds; every other timestamp on the wire is ms.
+        modifiedAt: Number(mtime) * 1e3,
+        tooLarge: bytes > SCRATCHPAD_MAX_BYTES
+      });
+    }
+    return items;
+  }
+  /**
+   * One item's bytes, base64. Capped: past SCRATCHPAD_MAX_BYTES the panel is
+   * told to show the path instead, so a 4GB screen recording cannot pin the
+   * data channel for minutes.
+   *
+   * One shell, not a size check and then a read: the panel opens every card at
+   * once, so a second spawn per item is a doubled cost on the whole listing -
+   * and a file that changed between the two calls would have been read past
+   * the cap anyway.
+   */
+  async read(name) {
+    const file = shEscape2(this.resolve(name));
+    const content = await this.target().sh(
+      // Unquoted `$(wc -c)` on purpose: BSD wc pads its count with spaces,
+      // which `[ -gt ]` will not parse. `base64 -w 0` is GNU-only (BSD
+      // spells it -b), so unwrap with tr rather than asking it not to wrap.
+      `[ -f ${file} ] || exit 1
+         if [ $(wc -c < ${file}) -gt ${SCRATCHPAD_MAX_BYTES} ]; then
+           echo '${TOO_LARGE}' >&2; exit 1
+         fi
+         base64 < ${file} | tr -d '
+'`
+    ).catch((err) => {
+      const text = err instanceof Error ? err.message : "";
+      throw new Error(
+        text.includes(TOO_LARGE) ? TOO_LARGE : "Could not read that item."
+      );
+    });
+    return { content: content.trim(), encoding: "base64" };
+  }
+  /**
+   * One byte range of an item, base64. What a download is built out of.
+   *
+   * No size cap here, unlike `read`: the cap exists because a preview holds
+   * the whole file in one message, and a range does not. `tail | head` rather
+   * than `dd`, which needs a GNU-only flag to promise a full block over a pipe.
+   */
+  async readChunk(name, offset, length) {
+    if (!Number.isInteger(offset) || offset < 0) {
+      throw new Error("Invalid scratchpad offset.");
+    }
+    if (!Number.isInteger(length) || length <= 0 || length > SCRATCHPAD_CHUNK_BYTES) {
+      throw new Error("Invalid scratchpad chunk length.");
+    }
+    const file = shEscape2(this.resolve(name));
+    const content = await this.target().sh(
+      // `tail -c +N` counts from 1, so the first byte is offset 0 plus one.
+      `[ -f ${file} ] || exit 1
+         tail -c +${offset + 1} ${file} | head -c ${length} | base64 | tr -d '
+'`
+    ).catch(() => {
+      throw new Error("Could not read that item.");
+    });
+    return { content: content.trim(), encoding: "base64" };
+  }
+  async remove(name) {
+    await this.target().run(["rm", "-f", "--", this.resolve(name)]);
+  }
+  /** Files only, and only at the top level: whatever put a directory in there
+   *  is not something this panel drew, and `rm -rf` on an agent-writable path
+   *  is a worse tool than this job needs. */
+  async clear() {
+    const dir = shEscape2(this.dir());
+    await this.target().run([
+      "sh",
+      "-c",
+      `mkdir -p ${dir} && cd ${dir} && find . -maxdepth 1 -type f -delete`
+    ]);
+  }
+  destroy() {
+    const watcher = this.watcher;
+    this.watcher = null;
+    if (watcher) void watcher.close();
+  }
+  /** Idempotent: every panel that opens calls `list`, and they must not stack
+   *  watchers on one directory. */
+  startWatching() {
+    if (this.watcher) return;
+    const watcher = new WorkspaceWatcher(this.dir(), () => {
+      this.emit({ at: Date.now() });
+    });
+    this.watcher = watcher;
+    watcher.start();
+  }
+  /** Absolute path for a name the agent chose. Flat by construction: the name
+   *  is validated, never joined with anything a caller supplied. */
+  resolve(name) {
+    if (!isSafeScratchpadName(name)) {
+      throw new Error("Invalid scratchpad item name.");
+    }
+    return `${this.dir()}/${name}`;
+  }
+};
+
 // ../../shared/all/helpers/board-agent-core/space-core.ts
 var import_promises10 = require("fs/promises");
 var import_path14 = __toESM(require("path"));
@@ -20340,7 +20573,7 @@ var SpaceCore = class {
         status("Preparing workspace\u2026");
         const { paths } = target;
         await target.sh(
-          `mkdir -p ${paths.root} ${paths.worktrees} ${paths.state} ${paths.backups} ${paths.builds} ${paths.bin}`
+          `mkdir -p ${paths.root} ${paths.worktrees} ${paths.state} ${paths.backups} ${paths.builds} ${paths.bin} ${paths.scratchpad}`
         );
         await allocateSpacePorts(this.spaceDir());
         await this.ensureSecretsBridge().catch(() => void 0);
@@ -20683,6 +20916,10 @@ var BoardAgentEngine = class _BoardAgentEngine {
     this.emitter = options.emitter;
     this.claude = new ClaudeModeEngine(this.core, this.emitter);
     this.terminal = new TerminalModeEngine(this.core, this.emitter);
+    this.scratchpad = new ScratchpadStore(
+      () => this.core.target(),
+      (payload) => this.emitter.emitScratchpad(payload)
+    );
     this.gate.subscribe(() => this.projectGateOntoRun());
   }
   /** Everything the runner does for this space that isn't a card session, so
@@ -21659,6 +21896,22 @@ var BoardAgentEngine = class _BoardAgentEngine {
   bareListExposed(p) {
     return this.terminal.bareListExposed(p);
   }
+  // ── Scratchpad (→ the space's display surface) ──
+  scratchpadList() {
+    return this.scratchpad.list();
+  }
+  scratchpadRead(p) {
+    return this.scratchpad.read(p.name);
+  }
+  scratchpadReadChunk(p) {
+    return this.scratchpad.readChunk(p.name, p.offset, p.length);
+  }
+  scratchpadDelete(p) {
+    return this.scratchpad.remove(p.name);
+  }
+  scratchpadClear() {
+    return this.scratchpad.clear();
+  }
   // ── Cross-mode coordinators ──
   async cardExecute(payload) {
     const {
@@ -21988,6 +22241,7 @@ ${c.content.trim() || "(no description)"}`
     void this.codexLogin?.cancel();
     this.claude.destroy();
     this.terminal.destroy();
+    this.scratchpad.destroy();
     this.core.destroy();
   }
   /** Route one action/payload to the right engine method, for both transports.
@@ -22318,6 +22572,24 @@ ${c.content.trim() || "(no description)"}`
         return await this.bareListExposed(
           payload
         );
+      case "scratchpadList":
+        return await this.scratchpadList();
+      case "scratchpadRead":
+        return await this.scratchpadRead(
+          payload
+        );
+      case "scratchpadReadChunk":
+        return await this.scratchpadReadChunk(
+          payload
+        );
+      case "scratchpadDelete":
+        await this.scratchpadDelete(
+          payload
+        );
+        return void 0;
+      case "scratchpadClear":
+        await this.scratchpadClear();
+        return void 0;
       case "secureStatus":
         return this.secureStatus();
       default:
@@ -22329,11 +22601,58 @@ ${c.content.trim() || "(no description)"}`
 // ../../shared/all/helpers/board-agent-core/index-service.ts
 var import_child_process5 = require("child_process");
 var import_crypto7 = require("crypto");
-var import_fs5 = require("fs");
+var import_fs6 = require("fs");
 var import_promises11 = __toESM(require("fs/promises"));
 var import_net3 = require("net");
-var import_path16 = require("path");
+var import_path17 = require("path");
 var import_util7 = require("util");
+
+// ../../shared/all/helpers/board-agent-core/node-version.ts
+var import_fs5 = require("fs");
+var import_os4 = __toESM(require("os"));
+var import_path16 = require("path");
+var MIN_INDEX_NODE_MAJOR = 20;
+var MAX_INDEX_NODE_MAJOR = 24;
+var NODE_OVERRIDE_ENV = "FACTIII_INDEX_NODE";
+function nodeMajor(version) {
+  return Number(version.replace(/^v/, "").split(".")[0]);
+}
+function indexNodeSupported(version = process.versions.node) {
+  const major = nodeMajor(version);
+  return !Number.isNaN(major) && major >= MIN_INDEX_NODE_MAJOR && major <= MAX_INDEX_NODE_MAJOR;
+}
+function candidateNodes() {
+  const paths = [];
+  const home = import_os4.default.homedir();
+  const nvmRoot = (0, import_path16.join)(home, ".nvm", "versions", "node");
+  try {
+    const versions = (0, import_fs5.readdirSync)(nvmRoot).filter((v) => indexNodeSupported(v)).sort((a, b) => nodeMajor(b) - nodeMajor(a));
+    for (const v of versions) paths.push((0, import_path16.join)(nvmRoot, v, "bin", "node"));
+  } catch {
+  }
+  for (const prefix of ["/opt/homebrew/opt", "/usr/local/opt"]) {
+    for (let major = MAX_INDEX_NODE_MAJOR; major >= MIN_INDEX_NODE_MAJOR; major -= 1) {
+      paths.push((0, import_path16.join)(prefix, `node@${major}`, "bin", "node"));
+    }
+  }
+  return paths;
+}
+function findIndexNode() {
+  const override = process.env[NODE_OVERRIDE_ENV];
+  if (override && (0, import_fs5.existsSync)(override)) return override;
+  if (indexNodeSupported()) return process.execPath;
+  return candidateNodes().find((p) => (0, import_fs5.existsSync)(p)) ?? null;
+}
+function unsupportedNodeMessage() {
+  return `The OneDrive index needs Node ${MIN_INDEX_NODE_MAJOR}-${MAX_INDEX_NODE_MAJOR} (pinned 24.11.1); this host runs Node ${process.versions.node} and has no supported Node installed. It compiles better-sqlite3 from source, and that build fails on Node ${MAX_INDEX_NODE_MAJOR + 1}+.
+
+Install one:  nvm install 24.11.1
+or point the runner at an existing one:  export ${NODE_OVERRIDE_ENV}=/path/to/node
+
+Everything else on this runner works meanwhile \u2014 only OneDrive search is off.`;
+}
+
+// ../../shared/all/helpers/board-agent-core/index-service.ts
 var execFileAsync4 = (0, import_util7.promisify)(import_child_process5.execFile);
 var IndexService = class {
   constructor(opts) {
@@ -22386,27 +22705,25 @@ var IndexService = class {
       await this.waitReady(this.port);
       return;
     }
-    await this.installDeps();
+    const nodeBin = findIndexNode();
+    if (!nodeBin) throw new Error(unsupportedNodeMessage());
+    await this.installDeps(nodeBin);
     const port = await this.stablePort();
     const log = await this.openLog();
-    this.proc = (0, import_child_process5.spawn)(
-      process.execPath,
-      [(0, import_path16.join)(this.opts.indexDir, "index.js")],
-      {
-        cwd: this.opts.indexDir,
-        env: {
-          ...process.env,
-          NODE_ENV: "production",
-          PORT: String(port),
-          CONTROL_TOKEN: this.opts.controlToken,
-          EMBED_URL: this.opts.embedUrl(),
-          INDEX_DATA_DIR: this.opts.dataDir
-        },
-        stdio: log ? ["ignore", log, log] : "ignore",
-        // Own process group so stop() reaps it; nothing else reaps orphans here.
-        detached: true
-      }
-    );
+    this.proc = (0, import_child_process5.spawn)(nodeBin, [(0, import_path17.join)(this.opts.indexDir, "index.js")], {
+      cwd: this.opts.indexDir,
+      env: {
+        ...process.env,
+        NODE_ENV: "production",
+        PORT: String(port),
+        CONTROL_TOKEN: this.opts.controlToken,
+        EMBED_URL: this.opts.embedUrl(),
+        INDEX_DATA_DIR: this.opts.dataDir
+      },
+      stdio: log ? ["ignore", log, log] : "ignore",
+      // Own process group so stop() reaps it; nothing else reaps orphans here.
+      detached: true
+    });
     this.proc.on("exit", () => {
       this.proc = null;
       this.ready = null;
@@ -22420,31 +22737,58 @@ var IndexService = class {
   async openLog() {
     try {
       await import_promises11.default.mkdir(this.opts.dataDir, { recursive: true });
-      return (0, import_fs5.openSync)((0, import_path16.join)(this.opts.dataDir, "index.log"), "a");
+      return (0, import_fs6.openSync)((0, import_path17.join)(this.opts.dataDir, "index.log"), "a");
     } catch {
       return null;
     }
   }
-  /** Install the index's native deps against THIS node on first start, so a
-   *  platform needing node-gyp fails here rather than at query time. */
-  async installDeps() {
+  /** Install the index's native deps against the node that will RUN it, so a
+   *  platform needing node-gyp fails here rather than at query time.
+   *
+   *  The deps are compiled per ABI, so they are only reusable under the node
+   *  that built them. The stamp records which ABI is on disk and forces a
+   *  rebuild when the interpreter changes — otherwise a host that switches
+   *  node versions loads a binding built for the old one and dies with
+   *  "compiled against a different Node.js version". */
+  async installDeps(nodeBin) {
     const dir = this.opts.indexDir;
-    if ((0, import_fs5.existsSync)((0, import_path16.join)(dir, "node_modules"))) return;
+    const { stdout } = await execFileAsync4(nodeBin, [
+      "-p",
+      "process.versions.modules"
+    ]);
+    const abi = stdout.trim();
+    const stamp = (0, import_path17.join)(dir, ".node-abi");
+    if ((0, import_fs6.existsSync)((0, import_path17.join)(dir, "node_modules"))) {
+      const built = await import_promises11.default.readFile(stamp, "utf-8").catch(() => "");
+      if (built.trim() === abi) return;
+      await import_promises11.default.rm((0, import_path17.join)(dir, "node_modules"), { recursive: true, force: true });
+    }
     await import_promises11.default.copyFile(
-      (0, import_path16.join)(dir, "image-package.json"),
-      (0, import_path16.join)(dir, "package.json")
+      (0, import_path17.join)(dir, "image-package.json"),
+      (0, import_path17.join)(dir, "package.json")
     );
     await execFileAsync4(
       "npm",
       ["install", "--omit=dev", "--no-audit", "--no-fund"],
-      { cwd: dir }
+      {
+        cwd: dir,
+        // npm resolves node-gyp's target from the node running it, so the
+        // chosen interpreter has to lead PATH or the build targets the wrong ABI.
+        env: {
+          ...process.env,
+          PATH: `${(0, import_path17.dirname)(nodeBin)}:${process.env.PATH ?? ""}`
+        }
+      }
     );
+    await import_promises11.default.writeFile(stamp, `${abi}
+`, "utf-8").catch(() => {
+    });
   }
   /** The port to listen on, kept stable across restarts. The URL goes into the
    *  CLIs' persistent MCP config, so a fresh port each start would leave every
    *  registration pointing at a dead one. */
   async stablePort() {
-    const file = (0, import_path16.join)(this.opts.dataDir, ".port");
+    const file = (0, import_path17.join)(this.opts.dataDir, ".port");
     const saved = Number(await import_promises11.default.readFile(file, "utf-8").catch(() => ""));
     if (Number.isInteger(saved) && saved > 0 && await isFree(saved)) {
       return saved;
@@ -22619,25 +22963,25 @@ async function pairWithBrowser(serverUrl) {
 }
 
 // src/config.ts
-var import_fs9 = __toESM(require("fs"));
-var import_os6 = __toESM(require("os"));
-var import_path21 = __toESM(require("path"));
+var import_fs10 = __toESM(require("fs"));
+var import_os7 = __toESM(require("os"));
+var import_path22 = __toESM(require("path"));
 
 // src/secureFile.ts
 var import_crypto10 = __toESM(require("crypto"));
-var import_fs8 = __toESM(require("fs"));
-var import_path20 = __toESM(require("path"));
+var import_fs9 = __toESM(require("fs"));
+var import_path21 = __toESM(require("path"));
 
 // src/keychain.ts
 var import_child_process7 = require("child_process");
 var import_crypto8 = __toESM(require("crypto"));
-var import_fs6 = __toESM(require("fs"));
-var import_os4 = __toESM(require("os"));
-var import_path17 = __toESM(require("path"));
+var import_fs7 = __toESM(require("fs"));
+var import_os5 = __toESM(require("os"));
+var import_path18 = __toESM(require("path"));
 var SERVICE = "factiii-runner";
 var ACCOUNT = "config-encryption-key";
-var DPAPI_KEY_FILE = import_path17.default.join(
-  import_os4.default.homedir(),
+var DPAPI_KEY_FILE = import_path18.default.join(
+  import_os5.default.homedir(),
   ".factiii-runner",
   "config-key.dpapi"
 );
@@ -22717,7 +23061,7 @@ function linuxWrite(key) {
 function winRead() {
   let wrapped;
   try {
-    wrapped = import_fs6.default.readFileSync(DPAPI_KEY_FILE, "utf-8").trim();
+    wrapped = import_fs7.default.readFileSync(DPAPI_KEY_FILE, "utf-8").trim();
   } catch {
     return { state: "missing" };
   }
@@ -22742,8 +23086,8 @@ function winWrite(key) {
     "-Command",
     `ConvertTo-SecureString -String '${key.toString("base64")}' -AsPlainText -Force | ConvertFrom-SecureString`
   ]);
-  import_fs6.default.mkdirSync(import_path17.default.dirname(DPAPI_KEY_FILE), { recursive: true });
-  import_fs6.default.writeFileSync(DPAPI_KEY_FILE, `${out.trim()}
+  import_fs7.default.mkdirSync(import_path18.default.dirname(DPAPI_KEY_FILE), { recursive: true });
+  import_fs7.default.writeFileSync(DPAPI_KEY_FILE, `${out.trim()}
 `, { mode: 384 });
 }
 function keychainBackend() {
@@ -22905,22 +23249,22 @@ function keychainStatus() {
 
 // src/secureStore.ts
 var import_crypto9 = __toESM(require("crypto"));
-var import_fs7 = __toESM(require("fs"));
-var import_path19 = __toESM(require("path"));
+var import_fs8 = __toESM(require("fs"));
+var import_path20 = __toESM(require("path"));
 
 // src/paths.ts
-var import_os5 = __toESM(require("os"));
-var import_path18 = __toESM(require("path"));
-var CONFIG_DIR = import_path18.default.join(import_os5.default.homedir(), ".factiii-runner");
+var import_os6 = __toESM(require("os"));
+var import_path19 = __toESM(require("path"));
+var CONFIG_DIR = import_path19.default.join(import_os6.default.homedir(), ".factiii-runner");
 function safeSlug(spaceSlug) {
   return spaceSlug.replace(/[^a-zA-Z0-9_.-]/g, "_");
 }
 function spaceDirPath(spaceSlug) {
-  return import_path18.default.join(CONFIG_DIR, safeSlug(spaceSlug));
+  return import_path19.default.join(CONFIG_DIR, safeSlug(spaceSlug));
 }
 
 // src/secureStore.ts
-var VAULT_KEY_FILE = import_path19.default.join(CONFIG_DIR, "vault-key.json");
+var VAULT_KEY_FILE = import_path20.default.join(CONFIG_DIR, "vault-key.json");
 var SCRYPT_N2 = 1 << 15;
 var MIN_PASSWORD_LENGTH = 8;
 var SecureStoreError = class extends Error {
@@ -22993,7 +23337,7 @@ function unseal(box, key) {
 function readVaultFile() {
   try {
     const parsed = JSON.parse(
-      import_fs7.default.readFileSync(VAULT_KEY_FILE, "utf-8")
+      import_fs8.default.readFileSync(VAULT_KEY_FILE, "utf-8")
     );
     return parsed.v === 1 ? parsed : null;
   } catch {
@@ -23001,11 +23345,11 @@ function readVaultFile() {
   }
 }
 function writeVaultFile(file) {
-  import_fs7.default.mkdirSync(CONFIG_DIR, { recursive: true });
+  import_fs8.default.mkdirSync(CONFIG_DIR, { recursive: true });
   const tmp = `${VAULT_KEY_FILE}.${process.pid}.tmp`;
-  import_fs7.default.writeFileSync(tmp, `${JSON.stringify(file, null, 2)}
+  import_fs8.default.writeFileSync(tmp, `${JSON.stringify(file, null, 2)}
 `, { mode: 384 });
-  import_fs7.default.renameSync(tmp, VAULT_KEY_FILE);
+  import_fs8.default.renameSync(tmp, VAULT_KEY_FILE);
 }
 var unlockedDek = null;
 function createVault(machineKey) {
@@ -23242,15 +23586,15 @@ function parseEnvelope(raw) {
   }
 }
 function atomicWrite(filePath, body) {
-  import_fs8.default.mkdirSync(import_path20.default.dirname(filePath), { recursive: true });
+  import_fs9.default.mkdirSync(import_path21.default.dirname(filePath), { recursive: true });
   const tmp = `${filePath}.${process.pid}.tmp`;
-  import_fs8.default.writeFileSync(tmp, body, { mode: 384 });
-  import_fs8.default.renameSync(tmp, filePath);
+  import_fs9.default.writeFileSync(tmp, body, { mode: 384 });
+  import_fs9.default.renameSync(tmp, filePath);
 }
 function readSecureBuffer(filePath) {
   let raw;
   try {
-    raw = import_fs8.default.readFileSync(filePath, "utf-8");
+    raw = import_fs9.default.readFileSync(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -23307,7 +23651,7 @@ function writeSecureJson(filePath, value2) {
 function readBootJson(filePath) {
   let raw;
   try {
-    raw = import_fs8.default.readFileSync(filePath, "utf-8");
+    raw = import_fs9.default.readFileSync(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -23357,8 +23701,8 @@ function writeBootJson(filePath, value2) {
 }
 
 // src/config.ts
-var CONFIG_DIR2 = import_path21.default.join(import_os6.default.homedir(), ".factiii-runner");
-var CONFIG_FILE = import_path21.default.join(CONFIG_DIR2, "config.json");
+var CONFIG_DIR2 = import_path22.default.join(import_os7.default.homedir(), ".factiii-runner");
+var CONFIG_FILE = import_path22.default.join(CONFIG_DIR2, "config.json");
 function readRunnerConfig() {
   return readBootJson(CONFIG_FILE);
 }
@@ -23366,7 +23710,7 @@ function writeRunnerConfig(config) {
   writeBootJson(CONFIG_FILE, config);
 }
 function configExists() {
-  return import_fs9.default.existsSync(CONFIG_FILE);
+  return import_fs10.default.existsSync(CONFIG_FILE);
 }
 
 // src/promptPassword.ts
@@ -23459,7 +23803,54 @@ function currentVersion() {
     return "0.0.0";
   }
 }
+function hostSatisfiesTarget() {
+  let engines = "";
+  try {
+    const res = (0, import_node_child_process.spawnSync)(
+      "npm",
+      ["view", `${PACKAGE_NAME}@latest`, "engines.node"],
+      { encoding: "utf-8", shell: process.platform === "win32" }
+    );
+    if (res.status !== 0) return { ok: true, reason: "" };
+    engines = (res.stdout ?? "").trim();
+  } catch {
+    return { ok: true, reason: "" };
+  }
+  if (!engines) return { ok: true, reason: "" };
+  const major = Number(process.versions.node.split(".")[0]);
+  if (Number.isNaN(major)) return { ok: true, reason: "" };
+  const min = /(?:>=|\^|~)\s*v?(\d+)/.exec(engines);
+  if (min && major < Number(min[1])) {
+    return {
+      ok: false,
+      reason: `it needs Node ${engines} and this host runs Node ${process.versions.node}`
+    };
+  }
+  const lessThan = /<\s*v?(\d+)/.exec(engines);
+  if (lessThan && major >= Number(lessThan[1])) {
+    return {
+      ok: false,
+      reason: `it needs Node ${engines} and this host runs Node ${process.versions.node}`
+    };
+  }
+  const atMost = /<=\s*v?(\d+)/.exec(engines);
+  if (atMost && major > Number(atMost[1])) {
+    return {
+      ok: false,
+      reason: `it needs Node ${engines} and this host runs Node ${process.versions.node}`
+    };
+  }
+  return { ok: true, reason: "" };
+}
 function installLatest() {
+  const fit = hostSatisfiesTarget();
+  if (!fit.ok) {
+    console.error(
+      `[update] refusing to install ${PACKAGE_NAME}@latest: ${fit.reason}.
+[update] Staying on ${currentVersion()}. Install a supported Node (nvm install 24.11.1) and restart the runner to update.`
+    );
+    return false;
+  }
   console.log(`[update] installing ${PACKAGE_NAME}@latest...`);
   const res = (0, import_node_child_process.spawnSync)("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
     stdio: "inherit",
@@ -23480,9 +23871,9 @@ var import_node_child_process2 = require("node:child_process");
 
 // src/daemon.ts
 var import_crypto11 = require("crypto");
-var import_fs11 = __toESM(require("fs"));
+var import_fs12 = __toESM(require("fs"));
 var import_node_datachannel = require("node-datachannel");
-var import_path23 = __toESM(require("path"));
+var import_path24 = __toESM(require("path"));
 
 // ../../node_modules/engine.io-client/build/esm-debug/transports/polling-xhr.node.js
 var XMLHttpRequestModule = __toESM(require_XMLHttpRequest(), 1);
@@ -26981,18 +27372,18 @@ Object.assign(lookup, {
 });
 
 // src/agent-adapter.ts
-var import_fs10 = __toESM(require("fs"));
-var import_path22 = __toESM(require("path"));
+var import_fs11 = __toESM(require("fs"));
+var import_path23 = __toESM(require("path"));
 function credsDir(spaceSlug) {
-  return import_path22.default.join(spaceDirPath(spaceSlug), ".creds");
+  return import_path23.default.join(spaceDirPath(spaceSlug), ".creds");
 }
 function githubPath(spaceSlug) {
-  return import_path22.default.join(credsDir(spaceSlug), "github.json");
+  return import_path23.default.join(credsDir(spaceSlug), "github.json");
 }
 function connectionPath(spaceSlug) {
-  return import_path22.default.join(credsDir(spaceSlug), "onedrive.json");
+  return import_path23.default.join(credsDir(spaceSlug), "onedrive.json");
 }
-var RUNNER_CONFIG_PATH = import_path22.default.join(CONFIG_DIR, "runner-config.json");
+var RUNNER_CONFIG_PATH = import_path23.default.join(CONFIG_DIR, "runner-config.json");
 function writeJson(filePath, value2) {
   writeSecureJson(filePath, value2);
 }
@@ -27008,14 +27399,14 @@ function fillDefaults(config) {
 }
 function configDirNames() {
   try {
-    return import_fs10.default.readdirSync(CONFIG_DIR, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    return import_fs11.default.readdirSync(CONFIG_DIR, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
   } catch {
     return [];
   }
 }
 function provisionedSpaceSlugs() {
   return configDirNames().filter(
-    (name) => import_fs10.default.existsSync(import_path22.default.join(CONFIG_DIR, name, "bin"))
+    (name) => import_fs11.default.existsSync(import_path23.default.join(CONFIG_DIR, name, "bin"))
   );
 }
 var migrated = false;
@@ -27029,7 +27420,7 @@ function migrateToSpaceFolders() {
   }
 }
 function readLegacy(filePath) {
-  if (!import_fs10.default.existsSync(filePath)) return { readable: true, value: null };
+  if (!import_fs11.default.existsSync(filePath)) return { readable: true, value: null };
   const value2 = readSecureJson(filePath);
   return { readable: value2 !== null, value: value2 };
 }
@@ -27047,14 +27438,14 @@ function migrateOnce() {
   const consumed = [];
   let strayFiles = [];
   try {
-    strayFiles = import_fs10.default.readdirSync(CONFIG_DIR).filter((f) => f.startsWith("space-") && f.endsWith(".json")).filter((f) => !f.endsWith(".onedrive.json"));
+    strayFiles = import_fs11.default.readdirSync(CONFIG_DIR).filter((f) => f.startsWith("space-") && f.endsWith(".json")).filter((f) => !f.endsWith(".onedrive.json"));
   } catch {
     strayFiles = [];
   }
   for (const name of strayFiles) {
     const slug = name.slice("space-".length, -".json".length);
     const parsed = readLegacy(
-      import_path22.default.join(CONFIG_DIR, name)
+      import_path23.default.join(CONFIG_DIR, name)
     );
     if (!parsed.readable) continue;
     if (parsed.value) strays[slug] = parsed.value;
@@ -27067,7 +27458,7 @@ function migrateOnce() {
     ...provisionedSpaceSlugs()
   ]);
   for (const slug of slugs) {
-    if (import_fs10.default.existsSync(githubPath(slug))) continue;
+    if (import_fs11.default.existsSync(githubPath(slug))) continue;
     const over = boards[slug] ?? strays[slug] ?? {};
     if (!Object.keys(over).length && !Object.keys(base).length) continue;
     const merged = fillDefaults({
@@ -27078,32 +27469,32 @@ function migrateOnce() {
       githubToken: over.githubToken || base.githubToken,
       provider: over.provider || base.provider
     });
-    import_fs10.default.mkdirSync(credsDir(slug), { recursive: true });
+    import_fs11.default.mkdirSync(credsDir(slug), { recursive: true });
     writeJson(githubPath(slug), merged);
   }
   let odFiles = [];
   try {
-    odFiles = import_fs10.default.readdirSync(CONFIG_DIR).filter((f) => f.startsWith("space-") && f.endsWith(".onedrive.json"));
+    odFiles = import_fs11.default.readdirSync(CONFIG_DIR).filter((f) => f.startsWith("space-") && f.endsWith(".onedrive.json"));
   } catch {
     odFiles = [];
   }
   for (const name of odFiles) {
     const slug = name.slice("space-".length, -".onedrive.json".length);
-    if (import_fs10.default.existsSync(connectionPath(slug))) {
+    if (import_fs11.default.existsSync(connectionPath(slug))) {
       consumed.push(name);
       continue;
     }
-    const conn = readLegacy(import_path22.default.join(CONFIG_DIR, name));
+    const conn = readLegacy(import_path23.default.join(CONFIG_DIR, name));
     if (!conn.readable) continue;
     if (conn.value) {
-      import_fs10.default.mkdirSync(credsDir(slug), { recursive: true });
+      import_fs11.default.mkdirSync(credsDir(slug), { recursive: true });
       writeJson(connectionPath(slug), conn.value);
     }
     consumed.push(name);
   }
   for (const name of [...consumed, "runner-config.json"]) {
     try {
-      import_fs10.default.rmSync(import_path22.default.join(CONFIG_DIR, name), { force: true });
+      import_fs11.default.rmSync(import_path23.default.join(CONFIG_DIR, name), { force: true });
     } catch {
     }
   }
@@ -27115,14 +27506,14 @@ function encryptStrayPlaintextConfigs() {
   const OURS = /^(config|runner-config|space-.*)\.json(\.bak-\d+)?$/;
   let names = [];
   try {
-    names = import_fs10.default.readdirSync(CONFIG_DIR).filter((f) => OURS.test(f));
+    names = import_fs11.default.readdirSync(CONFIG_DIR).filter((f) => OURS.test(f));
   } catch {
     return;
   }
   for (const name of names) {
-    const filePath = import_path22.default.join(CONFIG_DIR, name);
+    const filePath = import_path23.default.join(CONFIG_DIR, name);
     try {
-      const raw = import_fs10.default.readFileSync(filePath, "utf-8");
+      const raw = import_fs11.default.readFileSync(filePath, "utf-8");
       if (!raw.startsWith("{")) continue;
       writeSecureJson(filePath, JSON.parse(raw));
     } catch {
@@ -27145,7 +27536,7 @@ async function getConfiguredConnections() {
     for (const slug of listConfiguredSlugs()) {
       if (kinds.has("git") && kinds.has("onedrive")) break;
       if (readBoard(slug).githubToken) kinds.add("git");
-      if (import_fs10.default.existsSync(connectionPath(slug))) kinds.add("onedrive");
+      if (import_fs11.default.existsSync(connectionPath(slug))) kinds.add("onedrive");
     }
   } catch {
     return [];
@@ -27157,7 +27548,7 @@ function listConfiguredSlugs() {
   try {
     migrateToSpaceFolders();
     return configDirNames().filter(
-      (slug) => import_fs10.default.existsSync(githubPath(slug)) || import_fs10.default.existsSync(connectionPath(slug))
+      (slug) => import_fs11.default.existsSync(githubPath(slug)) || import_fs11.default.existsSync(connectionPath(slug))
     );
   } catch {
     return [];
@@ -27176,7 +27567,7 @@ var localConfigProvider = {
   // which is what makes disconnect stick.
   writeConfig(spaceSlug, config) {
     migrateToSpaceFolders();
-    import_fs10.default.mkdirSync(credsDir(spaceSlug), { recursive: true });
+    import_fs11.default.mkdirSync(credsDir(spaceSlug), { recursive: true });
     writeJson(githubPath(spaceSlug), config);
   },
   readOneDriveConnection(spaceSlug) {
@@ -27190,7 +27581,7 @@ var localConfigProvider = {
   writeOneDriveConnection(spaceSlug, connection) {
     const filePath = connectionPath(spaceSlug);
     if (!connection) {
-      import_fs10.default.rmSync(filePath, { force: true });
+      import_fs11.default.rmSync(filePath, { force: true });
       return;
     }
     writeJson(filePath, connection);
@@ -27213,9 +27604,10 @@ var localConfigProvider = {
       "builds",
       "secrets",
       "claude",
-      "codex"
+      "codex",
+      "scratchpad"
     ]) {
-      import_fs10.default.mkdirSync(import_path22.default.join(dir, sub), { recursive: true });
+      import_fs11.default.mkdirSync(import_path23.default.join(dir, sub), { recursive: true });
     }
     return dir;
   }
@@ -27389,15 +27781,15 @@ async function startDaemon(config) {
     }
   );
   const indexCandidates = [
-    import_path23.default.join(__dirname, "..", "index"),
-    import_path23.default.join(__dirname, "..", "..", "index", "image")
+    import_path24.default.join(__dirname, "..", "index"),
+    import_path24.default.join(__dirname, "..", "..", "index", "image")
   ];
-  const indexDir = indexCandidates.find((p) => import_fs11.default.existsSync(p)) ?? indexCandidates[0];
+  const indexDir = indexCandidates.find((p) => import_fs12.default.existsSync(p)) ?? indexCandidates[0];
   const odIndex = new IndexService({
     controlToken: (0, import_crypto11.createHash)("sha256").update(config.authToken).digest("hex"),
     embedUrl: () => config.serverUrl,
     indexDir,
-    dataDir: import_path23.default.join(CONFIG_DIR, "index-data")
+    dataDir: import_path24.default.join(CONFIG_DIR, "index-data")
   });
   void odIndex.ensureRunning().catch((err) => {
     console.error(
@@ -28013,27 +28405,24 @@ ${err.fix}`);
   console.error("");
   process.exit(1);
 }
-var MAX_SUPPORTED_NODE_MAJOR = 24;
-function assertSupportedNode() {
-  const major = Number(process.versions.node.split(".")[0]);
-  if (Number.isNaN(major) || major <= MAX_SUPPORTED_NODE_MAJOR) return;
-  console.error(
+function warnUnsupportedNode() {
+  if (indexNodeSupported()) return;
+  const alternative = findIndexNode();
+  console.warn(
     `
-factiii-runner needs Node 20\u2013${MAX_SUPPORTED_NODE_MAJOR} (pinned 24.11.1); you are on Node ${process.versions.node}.
-The bundled OneDrive index compiles better-sqlite3 from source, and that build fails on Node 25+.
-
-Switch with nvm:  nvm install 24.11.1 && nvm use 24.11.1
-then relaunch:    factiii-runner start
-`
+Node ${process.versions.node} is outside the range the OneDrive index supports (${MIN_INDEX_NODE_MAJOR}-${MAX_INDEX_NODE_MAJOR}, pinned 24.11.1).` + (alternative ? `
+The index will run under ${alternative}. Everything else is unaffected.
+` : `
+OneDrive search will be unavailable until a supported Node is installed (nvm install 24.11.1). Everything else works.
+`)
   );
-  process.exit(1);
 }
 import_node_dns.default.setDefaultResultOrder("ipv4first");
 var program2 = new Command();
 program2.name("factiii-runner").description("Factiii Runner - run Board AI agents on remote servers").version(currentVersion());
 program2.command("setup").description("Verify the host toolchain and pair this runner").option("-s, --server <url>", "API server URL", "https://api.factiii.com").action(async (opts) => {
   try {
-    assertSupportedNode();
+    warnUnsupportedNode();
     await setup(opts.server);
   } catch (err) {
     console.error(
@@ -28062,7 +28451,7 @@ program2.command("connect").description("Pair this runner with a Factiii account
   }
 });
 program2.command("start").description("Start the runner daemon").action(async () => {
-  assertSupportedNode();
+  warnUnsupportedNode();
   if (!configExists()) {
     console.error('No config found. Run "factiii-runner setup" first.');
     process.exit(1);
@@ -28108,8 +28497,7 @@ program2.command("status").description("Show current runner configuration").acti
   console.log(`Token:   \xB7\xB7\xB7\xB7${config.authToken.slice(-4)}`);
 });
 program2.command("doctor").description("Show where each host tool resolves, for a failed environment").action(async () => {
-  const nodeMajor = Number(process.versions.node.split(".")[0]);
-  const nodeNote = nodeMajor > MAX_SUPPORTED_NODE_MAJOR ? "  (UNSUPPORTED \u2014 use 24.11.1)" : "";
+  const nodeNote = indexNodeSupported() ? "" : `  (OneDrive index needs ${MIN_INDEX_NODE_MAJOR}-${MAX_INDEX_NODE_MAJOR}; ${findIndexNode() ?? "no supported node found"})`;
   console.log(`${"node".padEnd(14)} ${process.execPath} v${process.versions.node}${nodeNote}`);
   const report = await reportToolchain(hostTarget(CONFIG_DIR));
   for (const tool of report.tools) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factiii/runner",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Factiii Runner, run Board AI agents on a machine you control. Pairs with the Factiii web/mobile clients over WebRTC.",
   "license": "ISC",
   "keywords": [

package/plugin/factiii/skills/scratchpad/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: scratchpad
+description: Show the user something, or hand them a file, through the board's Scratchpad panel - by writing to $SCRATCHPAD. Anything you put there renders beside the terminal (image, screenshot, chart, video, audio, page, link, text) and can be saved to their machine or phone. TRIGGER when the user asks to see, show, preview, display or look at something; when you produce an image/diagram/chart/screenshot/recording; when you have a URL worth opening; when an answer is easier to look at than to read in a terminal; and whenever you need to GIVE the user a file - an export, a report, a bundle, a CSV, a log, a dump, anything they asked you to generate, save, download or send them. Writing it to $SCRATCHPAD is how a file gets off the runner and to the user.
+---
+
+# scratchpad
+
+The terminal you are running in has a panel beside it. Anything you put in the
+`$SCRATCHPAD` directory shows up there, drawn rather than printed: images
+render, video and audio play, links become clickable, text and markdown are
+shown as they are.
+
+```bash
+cp chart.png "$SCRATCHPAD/"
+```
+
+That is the whole interface. There is no command to run, nothing to install,
+and nothing to tell the panel: it is watching the directory and updates on
+its own within a second.
+
+## What renders as what
+
+The **extension decides**, so name the file for what it is:
+
+| Write | You get |
+|---|---|
+| `.png .jpg .gif .webp .svg` | the image, click-to-open-full-size |
+| `.mp4 .webm .mov` | a video player |
+| `.mp3 .wav .m4a .ogg` | an audio player |
+| `.html` | the page itself, rendered in a sandboxed frame |
+| `.md` `.txt` and anything unlisted | the text as-is |
+| `.url` | a clickable link (put the URL on the first line) |
+
+A link:
+
+```bash
+echo "https://example.com/the-thing" > "$SCRATCHPAD/preview.url"
+```
+
+A note, when the answer is a shape rather than a sentence:
+
+```bash
+cat > "$SCRATCHPAD/rollout-plan.md" <<'MD'
+# Rollout
+1. staging, behind the flag
+2. 10% of prod for a day
+3. everyone
+MD
+```
+
+## Handing a file to the user
+
+Every item on the panel has a Save button, and the panel pulls the file off the
+runner for them. So the scratchpad is not only for looking at: it is how you
+give someone a file.
+
+```bash
+cp coverage-report.csv "$SCRATCHPAD/"
+zip -qr "$SCRATCHPAD/failing-run-logs.zip" logs/
+pg_dump "$DATABASE_URL" > "$SCRATCHPAD/schema-before-migration.sql"
+```
+
+A file meant for keeping does not have to render well. A `.zip` shows as
+nothing much and a `.csv` as raw text, which is fine, because the user is going
+to save it rather than read it in a narrow column. Name it for what it is so
+they know what they are saving, and say in one line that it is there.
+
+Nothing else you can do reaches the user's disk. If you write a file into the
+workspace and tell them where it is, they have to go and get it themselves,
+which on a phone means they cannot.
+
+## Rules
+
+- **Flat, plain names.** Letters, numbers, dots, dashes, spaces and
+  underscores; no subdirectories, and never a leading dot. A name the panel
+  cannot show is a drawing the user never sees.
+- **Newest is shown first.** Rewriting a file under the same name replaces its
+  card and moves it to the top, which is how you update a drawing rather than
+  pile up `chart-2.png`, `chart-3.png`.
+- **Under 12MB to be shown inline.** A bigger file is still listed, and the
+  user can download it from the panel, but it will not render on the stage.
+  Trim a recording if you want it watched rather than saved.
+- **The board is shared.** One scratchpad per board, not per session, and it
+  survives the session that drew on it. Clean up what has gone stale:
+  `rm "$SCRATCHPAD/old-thing.png"`.
+
+## When to reach for it
+
+Use it whenever the answer is easier to look at than to read: a screenshot of
+the change you just made, a generated chart, a diagram, a recorded repro, a
+preview URL you just exposed, a table too wide for an 80-column shell.
+
+And use it for anything the user is meant to end up holding: the export they
+asked for, the report you generated, the logs from the run that failed, the
+backup you just took.
+
+Do not narrate it into the terminal as well. Write the file and say, in one
+line, what you put on the scratchpad - the user is looking at the panel.