foldrun 0.8.0 → 1.0.0

package/src/commands.mjs

@@ -1,6 +1,7 @@
 // CLI commands. Kept separate from bin/ so the environment is set before the
 // core is imported — single-workspace mode is read at module load.
 
+import { writeExact } from "./terminal.mjs";
 import dns from "node:dns";
 import fs from "node:fs";
 import crypto from "node:crypto";
@@ -78,7 +79,7 @@ function shippedTemplates() {
 }
 
 /** The files of one workspace: a template if asked for, else the starter. */
-async function workspaceFiles(name, from) {
+async function workspaceFiles(name, from, starter = true) {
   const { starterFiles } = await core();
   // A template is a source, a workspace is a destination. Keeping the two
   // words apart is the whole reason `templates/` is not called `examples/`:
@@ -91,7 +92,15 @@ async function workspaceFiles(name, from) {
   if (from && !source) {
     throw new Error(`no template at ${from} — pass a directory, or one that ships with foldrun: ${shippedTemplates().join(", ") || "none found"}`);
   }
-  const files = source ? templateFilesFrom(source) : starterFiles(name);
+  // Blank unless asked: the example researcher and writer met people as
+  // clutter in a workspace made for real work (owner, 2026-10-05). --starter
+  // brings them back; --from copies a template.
+  const { blankWorkspaceFiles } = /** @type {any} */ (await core());
+  const files = source
+    ? templateFilesFrom(source)
+    : starter || !blankWorkspaceFiles
+      ? starterFiles(name)
+      : blankWorkspaceFiles(name);
 
   // Whatever the source, the new workspace must ignore the key that decrypts
   // its secrets. A template does not carry one — it is a source, not a
@@ -206,7 +215,11 @@ function report(where, written, outside, wsDir, files) {
   console.log(`
   ${c.bold("Next")}
     foldrun check ${rel}${" ".repeat(Math.max(1, 16 - rel.length))}${c.dim("validate it — costs nothing")}
-    foldrun run ${flow ?? "publish"} --workspace ${path.relative(process.cwd(), wsDir) || "."}   ${c.dim("run the flow")}
+    ${
+      flow
+        ? `foldrun run ${flow} --workspace ${path.relative(process.cwd(), wsDir) || "."}   ${c.dim("run the flow")}`
+        : `foldrun agent import <workspace>/<agent>   ${c.dim("bring in an agent you already have — or `foldrun agent new <name>`")}`
+    }
 `);
 }
 
@@ -231,8 +244,11 @@ async function newWorkspace(name, flags, layout) {
   }
   const dir = path.join(layout.workspacesDir, name);
   if (fs.existsSync(dir)) throw new Error(`${dir} already exists`);
-  const files = await workspaceFiles(name, flags.from);
+  const files = await workspaceFiles(name, flags.from, flags.starter === true);
   writeFiles(dir, files);
+  // A workspace is a folder holding agents/ or flows/; a blank one has
+  // neither file yet, so the folders are made for it to be found as one.
+  for (const sub of ["agents", "flows"]) fs.mkdirSync(path.join(dir, sub), { recursive: true });
   syncWorkspaceBundles(dir);
   report(dir, files.map((f) => f.path), [], dir, files);
   return 0;
@@ -252,7 +268,7 @@ function workspaceDirFor(flags, layout) {
   if (typeof flags.to === "string") {
     if (!layout.workspacesDir || !layout.workspaces.includes(flags.to)) {
       throw new Error(
-        `no workspace called "${flags.to}" here — this ${layout.kind === "flat" ? "is a single workspace" : `account has ${layout.workspaces.join(", ") || "none"}`}`,
+        `no workspace called "${flags.to}" here — this ${layout.kind === "flat" ? "is a single workspace" : `account has ${layout.workspaces.join(", ") || "none"}`} (--platform makes it in the deployed one)`,
       );
     }
     return path.join(layout.workspacesDir, flags.to);
@@ -328,7 +344,7 @@ async function scaffoldCmd(kind, positional, flags, layout) {
 
   // The other verbs are dispatched before this — `agent run` and `tool test`
   // go to the platform — so anything left here should have been `new`.
-  const alsoVerbs = { agents: ["run", "link", "unlink"], tools: ["test"], flows: ["add", "rm-step", "dup-step", "show", "run", "rotate-hook", "set", "trigger", "move-step", "copy-step", "paste", "draft"] }[kind] ?? [];
+  const alsoVerbs = { agents: ["run", "link", "unlink", "import", "ls"], tools: ["test"], flows: ["ls", "add", "rm-step", "dup-step", "show", "run", "hook", "rotate-hook", "set", "trigger", "move-step", "copy-step", "paste", "draft"] }[kind] ?? [];
   const verb = positional[0];
   if (verb !== "new") {
     const verbs = ["new", ...alsoVerbs].join(", ");
@@ -341,6 +357,10 @@ async function scaffoldCmd(kind, positional, flags, layout) {
   if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
     throw new Error(`"${name}" is not a ${one} name — kebab-case only, e.g. ${KINDS[kind].placeholder}`);
   }
+  // --platform: the dashboard's New button, on the deployed workspace —
+  // nothing is written here. `--to` alone still names a workspace of this
+  // folder, as it always has.
+  if (flags.platform === true) return platformScaffold(kind, name, flags, layout);
 
   const dir = workspaceDirFor(flags, layout);
   let files;
@@ -375,6 +395,74 @@ async function scaffoldCmd(kind, positional, flags, layout) {
   return 0;
 }
 
+/**
+ * `foldrun agent new <name> --platform`, `flow new … --platform`, `tool new
+ * … --platform` — the dashboard's New button on a deployed workspace: the
+ * platform writes its own template (POST …/agents, …/flows, …/assets), so
+ * what lands is what the canvas would have made, as a revision.
+ */
+async function platformScaffold(kind, name, flags, layout) {
+  const one = { agents: "agent", flows: "flow", tools: "tool" }[kind];
+  const url = platformFor(flags, `${one} new --platform`);
+  const ws = platformWorkspace(flags, layout, `${one} new ${name} --platform`);
+  let route = `/api/workspaces/${enc(ws)}/${kind}`;
+  let body;
+  if (kind === "agents") {
+    body = { name, ...(typeof flags.description === "string" ? { description: flags.description } : {}), ...(typeof flags.model === "string" ? { model: flags.model } : {}) };
+  } else if (kind === "flows") {
+    if (flags.pattern !== undefined && !NEW_FLOW_SHAPES.includes(flags.pattern)) {
+      throw new Error(`--pattern takes ${NEW_FLOW_SHAPES.join(", ")} — not "${flags.pattern}"`);
+    }
+    body = { name, ...(typeof flags.pattern === "string" ? { pattern: flags.pattern } : {}) };
+  } else {
+    // A script tool, as `tool new` makes here — the platform's own default
+    // with no template is an http one.
+    route = `/api/workspaces/${enc(ws)}/assets`;
+    const template = typeof flags.template === "string" ? flags.template : typeof flags.transport === "string" ? flags.transport : "script";
+    body = { kind: "tools", name, template, ...(typeof flags.language === "string" ? { language: flags.language } : {}) };
+  }
+  const r = await remoteCall(url, flags, route, { method: "POST", body: JSON.stringify(body) });
+  console.log(`\n  ${c.green("created")} ${one} ${c.bold(name)} in ${ws} ${c.dim(`on ${url}`)}`);
+  console.log(`    ${c.dim(r.path ?? "")}${r.pattern ? c.dim(` · ${r.pattern}`) : ""}`);
+  console.log(`\n  ${c.dim(`foldrun source cat ${r.path ?? "<path>"} --to ${ws} · foldrun check --to ${ws} · foldrun pull ${ws} brings it here`)}\n`);
+  return 0;
+}
+
+/** The shapes the platform's New flow offers (core's store FLOW_PATTERNS). */
+const NEW_FLOW_SHAPES = ["pipeline", "review-loop", "fan-out", "debate", "router"];
+
+/**
+ * `foldrun agent ls` / `flow ls` — what is deployed in a workspace (GET
+ * …/agents, …/flows): the list the dashboard draws, from a terminal.
+ */
+async function remoteListCmd(kind, flags, layout) {
+  const one = kind === "agents" ? "agent" : "flow";
+  const url = platformFor(flags, `${one} ls`);
+  const ws = platformWorkspace(flags, layout, `${one} ls`);
+  const r = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/${kind}`);
+  const list = r[kind] ?? [];
+  if (flags.json === true) {
+    console.log(JSON.stringify(list, null, 2));
+    return 0;
+  }
+  if (!list.length) {
+    console.log(`\n  ${c.dim(`no ${kind} in ${ws} on ${url} — \`foldrun ${one} new <name> --platform --to ${ws}\` makes one`)}\n`);
+    return 0;
+  }
+  const w = Math.max(...list.map((x) => x.name.length));
+  console.log();
+  for (const x of list) {
+    if (kind === "agents") {
+      console.log(`  ${c.bold(pad(x.name, w))}  ${pad(x.model ?? "", 8)} ${c.dim(firstLine(x.description ?? "", 80))}`);
+    } else {
+      const when = x.trigger === "schedule" && x.schedule ? `schedule ${x.schedule}${x.timezone ? ` ${x.timezone}` : ""}` : (x.trigger ?? "manual");
+      console.log(`  ${c.bold(pad(x.name, w))}  ${c.dim(when)}`);
+    }
+  }
+  console.log(`\n  ${c.dim(`${list.length} ${list.length === 1 ? one : kind} · ${ws} · ${url}`)}\n`);
+  return 0;
+}
+
 // ---------------------------------------------------------------- check
 
 // The Agent Skills spec constrains the `name` field and requires a non-empty
@@ -623,8 +711,10 @@ async function platformLibrary(flags) {
     return new Set((body.entries ?? []).map((e) => e.name).filter(Boolean));
   };
   try {
-    const [tools, skills] = await Promise.all([names("tools"), names("skills")]);
-    return { url, tools, skills, warning: null };
+    // Hooks are newer than the library route on some platforms: a platform
+    // that does not list them leaves the set empty rather than failing check.
+    const [tools, skills, hooks] = await Promise.all([names("tools"), names("skills"), names("hooks").catch(() => new Set())]);
+    return { url, tools, skills, hooks, warning: null };
   } catch (err) {
     return { url, tools: new Set(), skills: new Set(), warning: `could not read the library on ${url} (${err instanceof Error ? err.message : err}) — tools defined there will be reported missing` };
   }
@@ -685,6 +775,11 @@ async function checkAccount(layout, flags) {
   const problems = [];
   const note = (level, where, message) => problems.push({ level, where, message });
   validateSkills(path.join(layout.accountRoot, "library"), note);
+  const hc = await hooksCore();
+  for (const p of hc ? hc.checkHooksDir(path.join(layout.accountRoot, "library", "hooks"), "account") : []) {
+    const m = /^(hooks\/[^/:]+(?:\/hook\.md)?): (.*)$/s.exec(p);
+    note("error", m ? m[1] : "hooks/", m ? m[2] : p);
+  }
   const counts = LIBRARY_KINDS.map((k) => ({ kind: k, n: files.filter((f) => f.kind === k).length })).filter((x) => x.n > 0);
   console.log(`\n  ${c.bold("library")}  ${c.dim(counts.length ? counts.map((x) => `${x.n} ${x.kind}`).join(" · ") : "empty")}`);
   for (const p of problems) {
@@ -777,7 +872,10 @@ async function checkProblems(workspace, flags = {}) {
   }
   for (const s of platform.skills) skillNames.add(s);
 
-  if (agentNames.size === 0) note("error", "agents/", "no agents — a workspace needs at least one");
+  // A blank workspace is legal — `foldrun new` and the dashboard make one —
+  // so this is a nudge, as the deploy's warning is; a flow naming a missing
+  // agent is still an error below.
+  if (agentNames.size === 0) note("warn", "agents/", "no agents yet — `foldrun agent new <name>`, or `foldrun agent import <workspace>/<agent>`");
 
   // What format does this workspace target?
   const agentsMd = path.join(workspace, "AGENTS.md");
@@ -793,7 +891,13 @@ async function checkProblems(workspace, flags = {}) {
     for (const w of readLimits(readAgentsMd(workspace)?.data?.limits).problems) note("error", "AGENTS.md", w);
   }
 
+  const { unopenedFrontmatter } = /** @type {any} */ (await core());
   for (const a of agents) {
+    // A frontmatter block with no opening `---` is read as prose: no tools,
+    // the default model (seo-digest's editor, 20 Sep to 5 Oct 2026).
+    const agentFile = path.join(workspace, "agents", a.name, "agent.md");
+    const unopened = unopenedFrontmatter && fs.existsSync(agentFile) ? unopenedFrontmatter(fs.readFileSync(agentFile, "utf8")) : null;
+    if (unopened) note("error", `agents/${a.name}/agent.md`, unopened, 1);
     if (!a.description) note("warn", `agents/${a.name}`, "no description — other agents and people read it");
 
     // A timezone nobody can read. The deploy already refuses it; check has to
@@ -957,6 +1061,8 @@ async function checkProblems(workspace, flags = {}) {
     }
   }
 
+  await checkHooks(workspace, agents, libraryDir(T), platform, note);
+
   // A script tool whose `run:` resolves to nothing parses, counts, and is
   // offered to the agent — then fails inside a turn. Checking it here is the
   // difference between a typo found in CI and a flow that quietly stops
@@ -1066,6 +1172,68 @@ async function checkProblems(workspace, flags = {}) {
   return { problems, summary };
 }
 
+/**
+ * Hooks, checked with core's own reader so check and a run agree: a hook
+ * folder that is not a hook, a `hooks:` name that resolves to nothing (a run
+ * refuses that step rather than run it unguarded), and a tool.call hook on an
+ * agent whose web search or fetch the model provider runs on its own servers
+ * — those calls never pass foldrun's dispatch, so the hook never sees them.
+ * A core from before hooks has no reader, and then there is nothing to say.
+ */
+async function checkHooks(workspace, agents, libraryRoot, platform, note) {
+  const h = await hooksCore();
+  if (!h) return;
+  for (const p of h.checkHooksDir(path.join(workspace, "hooks"), "workspace")) {
+    const m = /^(hooks\/[^/:]+(?:\/hook\.md)?): (.*)$/s.exec(p);
+    note("error", m ? m[1] : "hooks/", m ? m[2] : p);
+  }
+  const matter = (await import("gray-matter")).default;
+  const front = (file) => {
+    try {
+      return fs.existsSync(file) ? matter(fs.readFileSync(file, "utf8")).data ?? {} : {};
+    } catch {
+      return {}; // an unreadable file is reported by its own check
+    }
+  };
+  const exists = (n) =>
+    fs.existsSync(path.join(workspace, "hooks", n)) || fs.existsSync(path.join(libraryRoot, "hooks", n)) || platform.hooks?.has(n);
+  const missing = (where, names) => {
+    for (const n of names) {
+      if (!exists(n)) note("error", where, `hooks: [${n}] — no hooks/${n}/hook.md in this workspace or the account library`);
+    }
+  };
+  const accountNames = h.hookNames(front(path.join(path.dirname(libraryRoot), "AGENTS.md")).hooks);
+  const workspaceNames = h.hookNames(front(path.join(workspace, "AGENTS.md")).hooks);
+  missing("account AGENTS.md", accountNames);
+  missing("AGENTS.md", workspaceNames);
+
+  let resolveSearch = null;
+  try {
+    ({ resolveSearch } = /** @type {any} */ (await import("@foldrun/core/providers")));
+  } catch {
+    // no provider table: the provider-side search warning is skipped
+  }
+  for (const a of agents) {
+    const f = front(path.join(workspace, "agents", a.name, "agent.md"));
+    const own = h.hookNames(f.hooks);
+    missing(`agents/${a.name}`, own);
+    if (!resolveSearch || !f.web || typeof f.web !== "object" || Array.isArray(f.web)) continue;
+    const { hooks } = h.resolveHooks({ workspaceRoot: workspace, libraryRoot, names: [...accountNames, ...workspaceNames, ...own] });
+    const gates = hooks.filter((x) => x.on === "tool.call").map((x) => x.name);
+    if (!gates.length) continue;
+    for (const action of ["search", "fetch"]) {
+      if (f.web[action] === undefined) continue;
+      const r = resolveSearch(f.web[action], action);
+      if (!r?.provider || r.error || r.shape === "direct") continue;
+      note(
+        "warn",
+        `agents/${a.name}`,
+        `web.${action}: ${r.provider} runs on the model provider's servers, so tool.call hook${gates.length === 1 ? "" : "s"} ${gates.join(", ")} never see${gates.length === 1 ? "s" : ""} those calls — leave web.${action}: unset (or name a ${action} API) for foldrun's own dispatch, which hooks guard`,
+      );
+    }
+  }
+}
+
 /** The web tool the platform's gallery serves: built in, and the only
  *  built-in that takes a provider. */
 const WEB_TOOL = "web";
@@ -1811,7 +1979,47 @@ export function semverNewer(a, b) {
   for (let i = 0; i < 3; i++) if (x.n[i] !== y.n[i]) return x.n[i] > y.n[i];
   if (x.pre && !y.pre) return false;
   if (!x.pre && y.pre) return true;
-  return (x.pre ?? "") > (y.pre ?? "");
+  if (!x.pre) return false;
+  // SemVer 2.0.0 §11: dot-separated identifiers compared one by one — numbers
+  // as numbers (rc.10 > rc.9), a number before a word, and a shorter list
+  // before a longer one it begins.
+  const xs = x.pre.slice(1).split(".");
+  const ys = y.pre.slice(1).split(".");
+  for (let i = 0; i < Math.max(xs.length, ys.length); i++) {
+    if (xs[i] == null || ys[i] == null) return ys[i] == null;
+    const xn = /^\d+$/.test(xs[i]);
+    const yn = /^\d+$/.test(ys[i]);
+    if (xn && yn) {
+      if (Number(xs[i]) !== Number(ys[i])) return Number(xs[i]) > Number(ys[i]);
+    } else if (xn !== yn) return yn;
+    else if (xs[i] !== ys[i]) return xs[i] > ys[i];
+  }
+  return false;
+}
+
+/**
+ * Is `latest` an update worth telling someone running `current` about? Newer,
+ * and not a pre-release offered to someone on a stable release: npm keeps
+ * pre-releases off `latest`, so `npm i -g foldrun@latest` would not even
+ * install it.
+ * @param {string} latest @param {string} current
+ */
+export function updateTo(latest, current) {
+  // The whole header must be a version: it is printed, and a platform that
+  // could append to it could write to the terminal.
+  if (!/^v?\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(String(latest ?? "").trim())) return false;
+  const pre = (v) => /^v?\d+\.\d+\.\d+-/.test(String(v ?? "").trim());
+  return semverNewer(latest, current) && !(pre(latest) && !pre(current));
+}
+
+/**
+ * Text from a platform, made safe to print: no escape sequences or other
+ * control characters, so a hostile or broken server cannot move the cursor,
+ * retitle the terminal, write the clipboard (OSC 52) or disguise a link.
+ * @param {unknown} s
+ */
+export function printable(s) {
+  return String(s ?? "").replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
 }
 
 const UPDATE_EVERY_MS = 24 * 60 * 60 * 1000;
@@ -1831,14 +2039,14 @@ function updateNotice(res) {
     if (env("FOLDRUN_NO_UPDATE_NOTICE")) return;
     if (!(process.stderr.isTTY || env("FOLDRUN_FORCE_TTY") === "1")) return;
     const latest = res.headers.get("x-foldrun-cli");
-    if (!latest || !semverNewer(latest, CLI_VERSION)) return;
+    if (!latest || !updateTo(latest, CLI_VERSION)) return;
     noticeDone = true;
     const file = path.join(credentialsDir(), "version-check.json");
     try {
       const last = JSON.parse(fs.readFileSync(file, "utf8"));
       if (Date.now() - Date.parse(last.notifiedAt) < UPDATE_EVERY_MS) return;
     } catch {}
-    const platform = res.headers.get("x-foldrun-version");
+    const platform = printable(res.headers.get("x-foldrun-version") ?? "") || null;
     console.error(`  ${c.dim(`foldrun ${latest} is out (this is ${CLI_VERSION})${platform ? `, released with platform ${platform}` : ""} — npm i -g foldrun@latest`)}`);
     fs.mkdirSync(credentialsDir(), { recursive: true });
     fs.writeFileSync(file, JSON.stringify({ notifiedAt: new Date().toISOString(), cli: latest, platform }) + "\n");
@@ -1872,7 +2080,7 @@ async function versionCmd(flags) {
     }
   }
   const latestCli = platform?.packages?.cli ?? null;
-  const behind = latestCli ? semverNewer(latestCli, CLI_VERSION) : false;
+  const behind = latestCli ? updateTo(latestCli, CLI_VERSION) : false;
   if (flags.json === true) {
     console.log(JSON.stringify({ cli: CLI_VERSION, core, platform: platform ?? (url ? { url, error: unreachable } : null) }, null, 2));
     if (behind) console.error(`foldrun ${latestCli} is out (this is ${CLI_VERSION}) — npm i -g foldrun@latest`);
@@ -3529,7 +3737,7 @@ async function auditCmd(positional, flags) {
     q.set("format", "csv");
     const { bytes, name } = await remoteBytes(url, flags, `/api/audit?${q}`, "the audit log");
     if (typeof flags.file !== "string") {
-      process.stdout.write(bytes);
+      writeExact(bytes);
       return 0;
     }
     return writeDownload(bytes, name ?? "audit.csv", flags, "the audit log");
@@ -3605,7 +3813,7 @@ async function sourceCmd(positional, flags) {
   if (verb === "cat" || verb === "read" || verb === "get") {
     if (!a) throw new Error("which file? foldrun source cat flows/daily.md --to <workspace>");
     const { content } = await remoteCall(url, flags, `${base}?path=${encodeURIComponent(a)}`);
-    process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+    writeExact(content.endsWith("\n") ? content : `${content}\n`);
     return 0;
   }
   if (verb === "put" || verb === "write") {
@@ -3630,7 +3838,25 @@ async function sourceCmd(positional, flags) {
     console.log(`\n  ${c.green("✓")} removed ${a}\n`);
     return 0;
   }
-  throw new Error(`source: unknown verb "${verb}" — ls, cat, put, mv, rm`);
+  if (verb === "new") {
+    // The dashboard's New button for any document (POST …/assets): the
+    // platform writes the template — a tool folder, a skill, knowledge,
+    // memory, a script — at workspace scope, or inside one agent (--agent).
+    const kinds = ["tools", "knowledge", "memory", "skills", "scripts", "agents", "flows", "evals"];
+    if (!kinds.includes(a) || !b) throw new Error(`\`foldrun source new <kind> <name> --to <workspace>\` — kind is ${kinds.join(", ")} (--agent <name>, --template, --language)`);
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(b)) throw new Error(`"${b}" is not a name — kebab-case only`);
+    const body = {
+      kind: a,
+      name: b,
+      ...(typeof flags.agent === "string" ? { agent: flags.agent } : {}),
+      ...(typeof flags.template === "string" ? { template: flags.template } : {}),
+      ...(typeof flags.language === "string" ? { language: flags.language } : {}),
+    };
+    const r = await remoteCall(url, flags, `/api/workspaces/${encodeURIComponent(ws)}/assets`, { method: "POST", body: JSON.stringify(body) });
+    console.log(`\n  ${c.green("✓")} ${ws}/${r.path ?? b}  ${c.dim(`a new ${a.replace(/s$/, "")}${flags.agent ? ` for ${flags.agent}` : ""} · revision recorded`)}\n`);
+    return 0;
+  }
+  throw new Error(`source: unknown verb "${verb}" — ls, cat, put, new, mv, rm`);
 }
 
 // ------------------------------------------------- the account, as a whole
@@ -3964,6 +4190,7 @@ async function reportRuntimes(url, workspace, flags, { waitSeconds = 0 } = {}) {
       r.python && r.python !== true ? `python ${r.python}` : null,
       ...(r.packages ?? []),
       ...(r.npm ?? []).map((n) => `npm:${n}`),
+      ...(r.system ?? []).map((n) => `apt:${n}`),
     ].filter(Boolean).join(", ") || "python";
     const who = c.dim(`(${(r.agents ?? []).join(", ")})`);
     const mark =
@@ -4034,6 +4261,7 @@ function printIncidents(report) {
  * open GET /api/status; exits 1 when the platform does not answer.
  */
 async function platformStatusCmd(flags) {
+  if (flags.history === true) return platformHistoryCmd(flags);
   const url = remoteUrl(flags) ?? DEFAULT_PLATFORM;
   const { report, error } = await fetchPlatformStatus(url, flags);
   if (flags.json === true) {
@@ -4059,6 +4287,43 @@ async function platformStatusCmd(flags) {
   return 0;
 }
 
+/**
+ * `foldrun status --platform --history [--days n]` — what the status page
+ * draws as bars: each component's uptime per day over the window (1–90,
+ * default 90), and the incidents in it. The open GET /api/status/history.
+ */
+async function platformHistoryCmd(flags) {
+  const url = remoteUrl(flags) ?? DEFAULT_PLATFORM;
+  const days = flags.days === undefined ? 90 : Number(flags.days);
+  if (!Number.isInteger(days) || days < 1 || days > 90) throw new Error(`--days is a whole number from 1 to 90 — not "${flags.days}"`);
+  const res = await remoteFetch(url, `/api/status/history?days=${days}`, {}, { seconds: timeoutSeconds(flags) });
+  /** @type {any} */
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new HttpError(body.error ?? `/api/status/history → HTTP ${res.status}`, res.status, body);
+  if (flags.json === true) {
+    console.log(JSON.stringify(body, null, 2));
+    return 0;
+  }
+  const share = (u) => (u === null || u === undefined ? "  —   " : `${(u * 100).toFixed(u === 1 ? 0 : 2)}%`.padStart(6));
+  const mark = (d) => (d.uptime === null ? c.dim("·") : d.outage ? c.red("▮") : d.degraded || d.maintenance ? c.amber("▮") : c.green("▮"));
+  const comps = body.components ?? [];
+  const wide = Math.max(0, ...comps.map((x) => x.name.length));
+  console.log(`\n  ${c.bold(`last ${body.days ?? days} day${(body.days ?? days) === 1 ? "" : "s"}`)}  ${c.dim(`${url} · a sample every ${body.sampleMinutes ?? 5} minutes · uptime is the share not in outage`)}\n`);
+  for (const comp of comps) console.log(`  ${comp.name.padEnd(wide)}  ${share(comp.uptime)}  ${(comp.days ?? []).map(mark).join("")}`);
+  const incidents = body.incidents ?? [];
+  if (incidents.length) {
+    console.log(`\n  ${c.dim("incidents and maintenance")}`);
+    for (const i of incidents) {
+      const span = `${String(i.startsAt).slice(0, 16).replace("T", " ")}Z${i.resolvedAt ? ` → ${String(i.resolvedAt).slice(0, 16).replace("T", " ")}Z` : " · open"}`;
+      console.log(`  ${i.kind === "incident" ? (i.impact === "major" ? c.red("!") : c.amber("!")) : c.dim("~")} ${c.bold(i.title)}  ${c.dim(`${i.kind === "incident" ? `${i.impact} incident` : "maintenance"} · ${span}`)}`);
+    }
+  } else {
+    console.log(`\n  ${c.dim("no incidents in the window")}`);
+  }
+  console.log(`\n  ${c.dim("▮ a day: green up, amber degraded or maintenance, red an outage, · no samples · --days <n>, --json")}\n`);
+  return 0;
+}
+
 async function statusCmd(layout, flags, only) {
   if (flags.platform === true) return platformStatusCmd(flags);
   const { isSourcePath, accountTreeFrom } = await core();
@@ -4191,7 +4456,21 @@ async function workspacesCmd(positional, flags, layout) {
   const [verb, name] = positional;
   const url = flags.local === true ? undefined : remoteUrl(flags);
 
-  if (verb === "new" || verb === "add") return newWorkspace(name, flags, layout);
+  if (verb === "new" || verb === "add") {
+    if (flags.platform !== true) return newWorkspace(name, flags, layout);
+    // The dashboard's Create workspace: blank (an AGENTS.md), or with
+    // --starter the example researcher, writer and publish flow.
+    if (!url) throw new Error("--platform needs a platform — pass --url, or `foldrun login` first");
+    if (!name) throw new Error("which workspace? `foldrun workspaces new <name> --platform`");
+    assertName(name);
+    const r = await remoteCall(url, flags, "/api/workspaces", {
+      method: "POST",
+      body: JSON.stringify(flags.starter === true ? { name, starter: true } : { name, template: true }),
+    });
+    console.log(`\n  ${c.green("✓")} ${c.bold(r.name ?? name)} ${c.dim(`on ${url} — ${r.agents ?? 0} agent${r.agents === 1 ? "" : "s"}, ${r.flows ?? 0} flow${r.flows === 1 ? "" : "s"}`)}`);
+    console.log(`  ${c.dim(`foldrun agent new <name> --platform --to ${r.name ?? name} · foldrun pull ${r.name ?? name}`)}\n`);
+    return 0;
+  }
 
   if (verb === "rm" || verb === "remove" || verb === "delete") {
     if (!name) throw new Error("which workspace? `foldrun workspaces rm <name>`");
@@ -4220,7 +4499,7 @@ async function workspacesCmd(positional, flags, layout) {
     return 0;
   }
   if (verb && verb !== "ls" && verb !== "list") {
-    throw new Error(`workspaces: unknown verb "${verb}" — ls, new <name>, rm <name>`);
+    throw new Error(`workspaces: unknown verb "${verb}" — ls, show <name>, new <name>, rm <name>, demo`);
   }
 
   const here = layout.workspaces;
@@ -4234,6 +4513,23 @@ async function workspacesCmd(positional, flags, layout) {
     }
   }
   const all = [...new Set([...here, ...there])].sort();
+  // --json: for a script — `foldrun workspaces --json | jq -r '.workspaces[].name'`.
+  // The table's footer once read as a workspace called "is" to a loop that
+  // parsed it. Unreachable platform: still the list, with `error`, exit 1.
+  if (flags.json === true) {
+    console.log(
+      JSON.stringify(
+        {
+          platform: url ?? null,
+          workspaces: all.map((n) => ({ name: n, here: here.includes(n), platform: there.includes(n) })),
+          ...(reach ? { error: reach } : {}),
+        },
+        null,
+        2,
+      ),
+    );
+    return reach ? 1 : 0;
+  }
   if (!all.length) {
     console.log(`\n  ${c.dim("no workspaces — `foldrun new <name>` makes one")}\n`);
     return 0;
@@ -4522,7 +4818,7 @@ async function storageCmd(positional, flags, layout) {
     if (bytes.includes(0)) {
       throw new Error(`${rel} is not text (${humanBytes(bytes.length)}) — \`foldrun storage cat ${rel} --preview\` reads what is in it, \`foldrun storage get ${rel}\` writes it to a file`);
     }
-    process.stdout.write(bytes.toString("utf8"));
+    writeExact(bytes);
     return 0;
   }
 
@@ -4643,7 +4939,7 @@ async function triggersCmd(flags, layout) {
   const ws = typeof flags.to === "string" ? flags.to : layout?.kind === "empty" ? null : takeWorkspace([], layout);
   if (!ws) throw new Error("which workspace? `foldrun triggers --to <workspace>` — or run it inside one");
   const days = Number(flags.since) > 0 ? Math.floor(Number(flags.since)) : 7;
-  const body = await remoteCall(url, flags, `/api/workspaces/${ws}/triggers?since=${days}`);
+  const body = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/triggers?days=${days}`);
   const rows = body.flows ?? [];
   if (!rows.length) {
     console.log(`\n  ${c.dim(`no trigger fired in ${ws} in the last ${body.days ?? days} day${(body.days ?? days) === 1 ? "" : "s"} — a flow fires when its frontmatter says trigger: schedule, webhook, watch, storage or email`)}\n`);
@@ -4750,6 +5046,65 @@ async function providersCmd(url, flags) {
   return broken ? 1 : 0;
 }
 
+/**
+ * `foldrun account model` — the account's own model key: what every step
+ * runs on unless a provider: block names another (/api/account/model).
+ *
+ *   foldrun account model                                   what is set, what runs
+ *   foldrun account model set <provider> --key <api key>    a preset (anthropic,
+ *       openrouter, openai, groq, …) or `custom --base-url https://… --format openai`
+ *   foldrun account model remove
+ *
+ * `--key -` reads the key from stdin, so it stays out of the shell's history.
+ * The platform refuses a Claude login token for any account not allowed its
+ * own credential: bring an API key.
+ */
+async function accountModelCmd(url, positional, flags) {
+  const verb = positional[0];
+  const show = (r) => {
+    const runs =
+      r.runsOn === "account"
+        ? `${c.green("✓")} your own key — ${c.bold(r.provider ?? "custom")} ${c.dim(`${r.keyHint ?? ""} · ${r.baseUrl ?? ""} · ${r.format ?? ""}`)}`
+        : r.runsOn === "platform"
+          ? `${c.yellow("·")} the platform's credential ${c.dim("(this account is allowed it)")}`
+          : `${c.red("✗")} no key — runs on this account are refused until one is set`;
+    console.log(`\n  ${runs}`);
+    console.log(`\n  ${c.dim("foldrun account model set <provider> --key <api key> · remove · a provider: block in AGENTS.md wins over it")}\n`);
+  };
+  if (!verb) {
+    const r = await remoteCall(url, flags, "/api/account/model");
+    if (flags.json === true) console.log(JSON.stringify(r, null, 2));
+    else show(r);
+    return r.runsOn === "none" ? 1 : 0;
+  }
+  if (verb === "remove") {
+    const r = await remoteCall(url, flags, "/api/account/model", { method: "DELETE" });
+    if (flags.json === true) console.log(JSON.stringify(r, null, 2));
+    else show(r);
+    return 0;
+  }
+  if (verb !== "set") throw new Error("`foldrun account model`, `foldrun account model set <provider> --key <api key>`, or `foldrun account model remove`");
+  const provider = positional[1];
+  if (!provider) throw new Error("which provider? `foldrun account model set anthropic --key …` (a preset name, or `custom --base-url https://… --format openai`)");
+  let apiKey = typeof flags.key === "string" ? flags.key : "";
+  if (apiKey === "-") apiKey = fs.readFileSync(0, "utf8").trim();
+  if (!apiKey) throw new Error("--key <api key> (or --key - to read it from stdin)");
+  const body = {
+    provider,
+    apiKey,
+    ...(typeof flags["base-url"] === "string" ? { baseUrl: flags["base-url"] } : {}),
+    ...(typeof flags.format === "string" ? { format: flags.format } : {}),
+  };
+  const r = await remoteCall(url, flags, "/api/account/model", {
+    method: "PUT",
+    body: JSON.stringify(body),
+    headers: { "idempotency-key": crypto.randomUUID() },
+  });
+  if (flags.json === true) console.log(JSON.stringify(r, null, 2));
+  else show(r);
+  return 0;
+}
+
 // --------------------------------------------------------------- billing
 
 /**
@@ -4847,9 +5202,10 @@ async function accountCmd(positional, flags) {
     return 0;
   }
   if (verb === "providers") return providersCmd(url, flags);
+  if (verb === "model") return accountModelCmd(url, positional.slice(1), flags);
   if (verb === "export") return accountExportCmd(url, flags);
   if (verb !== "set" && verb !== "clear") {
-    throw new Error(`unknown account verb "${verb}" — \`foldrun account\` shows them, \`set\` and \`clear\` change one, \`providers\` checks the model keys, \`export\` downloads everything`);
+    throw new Error(`unknown account verb "${verb}" — \`foldrun account\` shows them, \`set\` and \`clear\` change one, \`model\` is the account's own model key, \`providers\` checks the model keys, \`export\` downloads everything`);
   }
 
   const key = positional[1];
@@ -5160,6 +5516,12 @@ const waitingSteps = (run) =>
     .map((s, i) => ({ step: s, index: i }))
     .filter(({ step }) => step.status === "awaiting-approval" && step.waitFor !== "event");
 
+/** The steps of a run parked on `wait: event` — what `approve --payload` releases. */
+const eventSteps = (run) =>
+  (run.steps ?? [])
+    .map((s, i) => ({ step: s, index: i }))
+    .filter(({ step }) => step.status === "awaiting-approval" && step.waitFor === "event");
+
 // ------------------------------------------------------------- approvals
 
 /**
@@ -5252,17 +5614,23 @@ async function decideCmd(decision, runId, flags, layout) {
   }
   const ws = await workspaceOfRun(url, flags, layout, runId);
   const run = await remoteCall(url, flags, `/api/workspaces/${ws}/runs/${runId}`);
-  const waiting = waitingSteps(run);
+  // --payload releases a `wait: event` step as its event URL would, so those
+  // are the steps it chooses from; every other decision is a person's gate.
+  const payload = flags.payload === undefined ? undefined : eventPayload(flags.payload);
+  if (payload !== undefined && decision !== "approve") throw new Error("--payload releases a `wait: event` step — it cannot go with reject");
+  const waiting = payload === undefined ? waitingSteps(run) : eventSteps(run);
   if (!waiting.length) {
     throw new Error(
-      `${runId} in ${ws} is ${run.status} — no step of it is waiting on a person. \`foldrun approvals\` lists the ones that are`,
+      payload === undefined
+        ? `${runId} in ${ws} is ${run.status} — no step of it is waiting on a person. \`foldrun approvals\` lists the ones that are`
+        : `${runId} in ${ws} is ${run.status} — no step of it is waiting on \`wait: event\`, which is what --payload releases`,
     );
   }
 
   const only = flags.step === undefined ? null : Number(flags.step) - 1;
   if (only !== null && !waiting.some(({ index }) => index === only)) {
     throw new Error(
-      `step ${flags.step} of ${runId} is not waiting on a person — ${waiting.map(({ index }) => index + 1).join(", ")} ${waiting.length === 1 ? "is" : "are"}`,
+      `step ${flags.step} of ${runId} is not waiting on ${payload === undefined ? "a person" : "`wait: event`"} — ${waiting.map(({ index }) => index + 1).join(", ")} ${waiting.length === 1 ? "is" : "are"}`,
     );
   }
   const chosen = only === null ? waiting : waiting.filter(({ index }) => index === only);
@@ -5287,7 +5655,12 @@ async function decideCmd(decision, runId, flags, layout) {
     return 1;
   }
 
-  const body = { decision, ...(note ? { note, ...(decision === "reject" ? { reason: note } : {}) } : {}), ...(only === null ? {} : { step: only }) };
+  const body = {
+    decision,
+    ...(note ? { note, ...(decision === "reject" ? { reason: note } : {}) } : {}),
+    ...(only === null ? {} : { step: only }),
+    ...(payload === undefined ? {} : { payload }),
+  };
   const answer = await remoteCall(url, flags, `/api/workspaces/${ws}/runs/${runId}/approve`, {
     method: "POST",
     body: JSON.stringify(body),
@@ -5300,6 +5673,23 @@ async function decideCmd(decision, runId, flags, layout) {
   return 0;
 }
 
+/** `--payload` for a `wait: event` step: text, or `@file`; JSON is sent as
+ *  JSON, anything else as the text it is — what the event URL would take. */
+function eventPayload(value) {
+  if (value === true) throw new Error("--payload needs a value — text, JSON, or @file");
+  let text = String(value);
+  if (text.startsWith("@")) {
+    const file = path.resolve(text.slice(1));
+    if (!fs.existsSync(file)) throw new Error(`--payload ${text}: no such file`);
+    text = fs.readFileSync(file, "utf8");
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
 // ------------------------------------------------------------------ stop
 
 /**
@@ -5844,6 +6234,308 @@ async function checkRemote(flags, layout) {
   }
 }
 
+// ---------------------------------------------------------------- hooks
+
+/**
+ * Core's hooks module — readHookDef, runHook, the event list — or null on a
+ * core from before hooks, where `check` then says nothing about them and the
+ * `hook` verbs say which core they need.
+ */
+async function hooksCore() {
+  try {
+    return /** @type {any} */ (await import("@foldrun/core/hooks"));
+  } catch {
+    return null;
+  }
+}
+async function needHooksCore() {
+  const h = await hooksCore();
+  if (!h) throw new Error("this CLI's @foldrun/core has no hooks — update it (npm i -g foldrun@latest)");
+  return h;
+}
+
+/** The account library a hook verb works on: the folder beside workspaces/. */
+const libraryRootOf = (layout) => path.join(layout.accountRoot, "library");
+
+/** What a new run.mjs answers, per event: a gate allows, a watcher notes nothing. */
+const HOOK_ANSWER = {
+  "tool.call": `{ decision: "allow" }`,
+  "tool.result": `{}`,
+  "step.start": `{}`,
+  "step.end": `{}`,
+};
+
+/** A sample event per kind, for `hook test` with no --event. */
+const HOOK_SAMPLE = {
+  "tool.call": { tool: { name: "Bash", input: { command: "ls" } } },
+  "tool.result": { tool: { name: "Bash", input: { command: "ls" }, result: "agent.md\n" } },
+  "step.start": { prompt: "Find three sources." },
+  "step.end": { reply: "Done." },
+};
+
+function hookRunTemplate(name, on) {
+  return `// ${name} — a foldrun hook (on: ${on}). Self-contained: Node's built-ins only,
+// no relative imports — it runs from a copy taken when the step starts.
+//
+// In:  one JSON object on stdin — the event:
+//        { event, hook, run_id, step, agent, workspace,
+//          tool: { name, input }        (tool.call, tool.result; + result on tool.result)
+//          prompt                       (step.start)
+//          reply                        (step.end) }
+// Out: one JSON object on stdout, the last line printed:
+//        tool.call    { decision: "allow" | "deny", reason, input, note }
+//                     input replaces the tool's whole input; a deny needs a reason
+//        step.start   { context, note }   context is added to the step's prompt
+//        step.end     { reply, note }     reply replaces the step's reply
+//        tool.result  { note }            a line on the run's trail
+// Exit 0 with an answer. Exit 2 denies, with stderr as the reason.
+// Anything else is a failure: a gate (tool.call, step.start) that fails
+// refuses; a watcher (tool.result, step.end) that fails is recorded.
+// No secrets and no model key reach this process.
+
+let raw = "";
+for await (const chunk of process.stdin) raw += chunk;
+const event = JSON.parse(raw || "{}");
+
+// Decide here. This one allows everything.
+void event;
+console.log(JSON.stringify(${HOOK_ANSWER[on]}));
+`;
+}
+
+/** `foldrun hook <ls|add|test|rm>` — hooks in this workspace and the library. */
+async function hookCmd(positional, flags, layout) {
+  const [verb = "ls"] = positional;
+  if (verb === "ls" || verb === "list") return hookLsCmd(flags, layout);
+  if (verb === "add" || verb === "new") return hookAddCmd(positional, flags, layout);
+  if (verb === "test") return hookTestCmd(positional, flags, layout);
+  if (verb === "rm") return hookRmCmd(positional, flags, layout);
+  throw new Error(`unknown hook verb "${verb}" — ls, add <name> --on <event>, test <name>, rm <name>`);
+}
+
+/** Every hook folder here, the workspace's first, each read the way a run reads it. */
+async function hooksHere(flags, layout) {
+  const h = await needHooksCore();
+  const ws = workspaceDirFor(flags, layout);
+  const out = [];
+  const seen = new Set();
+  for (const [root, scope] of [[ws, "workspace"], [libraryRootOf(layout), "account"]]) {
+    for (const dir of h.listHookDirs(path.join(root, "hooks"))) {
+      const name = path.basename(dir);
+      const def = h.readHookDef(dir, scope);
+      const row = "error" in def
+        ? { name, scope, error: def.error }
+        : { name, scope, on: def.on, tool: def.tool ?? null, timeout: def.timeoutSec, description: def.description ?? null };
+      // A workspace hook of the same name is the one a run resolves.
+      out.push({ ...row, ...(seen.has(name) ? { shadowed: true } : {}) });
+      seen.add(name);
+    }
+  }
+  return { h, ws, hooks: out };
+}
+
+/** `hook ls --to <ws>`: the DEPLOYED workspace's hooks and what they did
+ *  lately — GET /api/workspaces/<ws>/hooks, the dashboard's Hooks panel. */
+async function hookLsRemote(flags) {
+  const url = platformFor(flags, "hook ls");
+  const ws = String(flags.to);
+  const q = new URLSearchParams();
+  if (flags.all === true) q.set("all", "1");
+  if (flags.runs !== undefined) q.set("runs", String(flags.runs));
+  const r = /** @type {{ hooks: any[], recent: any[] }} */ (await remoteCall(url, flags, `/api/workspaces/${encodeURIComponent(ws)}/hooks${q.size ? `?${q}` : ""}`));
+  if (flags.json === true) {
+    console.log(JSON.stringify(r, null, 2));
+    return 0;
+  }
+  const hooks = r.hooks ?? [];
+  if (!hooks.length) console.log(`\n  ${c.dim(`no hooks in ${ws} or the account library`)}`);
+  else {
+    console.log();
+    const w = Math.max(...hooks.map((x) => x.name.length));
+    for (const x of hooks) {
+      const where = x.scope === "account" ? "library" : "workspace";
+      if (x.error) {
+        console.log(`  ${c.red("✗")} ${c.bold(x.name.padEnd(w))}  ${c.dim(where.padEnd(9))}  ${x.error}`);
+        continue;
+      }
+      const on = (x.onFor ?? []).length ? `on for ${x.onFor.join(", ")}` : "turned on by nobody";
+      const note = x.shadowed ? "(the workspace's own of this name is the one that runs)" : `${on}${x.description ? ` — ${x.description}` : ""}`;
+      console.log(`  ${c.green("✓")} ${c.bold(x.name.padEnd(w))}  ${c.dim(where.padEnd(9))}  ${String(x.on).padEnd(11)}  ${String(x.tool ?? "*").padEnd(12)}  ${c.dim(note)}`);
+    }
+  }
+  const recent = r.recent ?? [];
+  console.log(`\n  ${c.bold("lately")}  ${c.dim(recent.length ? `${recent.length} ${flags.all === true ? "hook decision" : "deny, rewrite or failure"}${recent.length === 1 ? "" : "s"}, newest first` : flags.all === true ? "no hook ran" : "nothing denied, rewritten or failed (--all for every decision)")}`);
+  for (const e of recent.slice(0, 20)) {
+    const rec = e.record ?? {};
+    console.log(`  ${c.dim(String(e.t).slice(0, 16).replace("T", " "))}  ${rec.hook} ${rec.did} ${rec.event}${rec.tool ? ` ${rec.tool}` : ""}  ${c.dim(`${e.runId} step ${e.step} ${e.agent}`)}${rec.reason ? ` — ${firstLine(rec.reason, 80)}` : ""}`);
+  }
+  console.log(`\n  ${c.dim("--runs <n> reads further back (default 50) · --all for every decision · --json")}\n`);
+  return hooks.some((x) => x.error) ? 1 : 0;
+}
+
+async function hookLsCmd(flags, layout) {
+  if (typeof flags.to === "string") return hookLsRemote(flags);
+  const { hooks } = await hooksHere(flags, layout);
+  if (flags.json === true) {
+    console.log(JSON.stringify(hooks, null, 2));
+    return 0;
+  }
+  if (!hooks.length) {
+    console.log(`\n  ${c.dim("no hooks — `foldrun hook add <name> --on tool.call` makes one")}\n`);
+    return 0;
+  }
+  console.log();
+  const w = Math.max(...hooks.map((x) => x.name.length));
+  for (const x of hooks) {
+    const where = x.scope === "account" ? "library" : "workspace";
+    if (x.error) {
+      console.log(`  ${c.red("✗")} ${c.bold(x.name.padEnd(w))}  ${c.dim(where.padEnd(9))}  ${x.error}`);
+      continue;
+    }
+    const what = `${x.on.padEnd(11)}  ${(x.tool ?? "*").padEnd(12)}`;
+    const note = x.shadowed ? c.dim("(the workspace's own of this name is the one that runs)") : c.dim(x.description ?? "");
+    console.log(`  ${c.green("✓")} ${c.bold(x.name.padEnd(w))}  ${c.dim(where.padEnd(9))}  ${what}  ${note}`);
+  }
+  console.log(`\n  ${c.dim("an agent turns one on with hooks: [name]; AGENTS.md hooks: turns it on for every agent under it")}\n`);
+  return hooks.some((x) => x.error) ? 1 : 0;
+}
+
+async function hookAddCmd(positional, flags, layout) {
+  const h = await needHooksCore();
+  const name = positional[1];
+  if (!name) throw new Error("which hook? `foldrun hook add <name> --on tool.call|tool.result|step.start|step.end`");
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) {
+    throw new Error(`"${name}" is not a hook name — lowercase letters, digits and dashes, e.g. no-rm-rf`);
+  }
+  const on = flags.on;
+  if (typeof on !== "string" || !h.HOOK_EVENTS.includes(on)) {
+    throw new Error(`--on takes ${h.HOOK_EVENTS.join(", ")}${typeof on === "string" ? ` — not "${on}"` : ""}`);
+  }
+  const tool = typeof flags.tool === "string" ? flags.tool.trim() : undefined;
+  if (flags.tool !== undefined && !tool) throw new Error("--tool takes a tool name or pattern, like Bash, Write|Edit or mcp__*");
+  if (tool && on !== "tool.call" && on !== "tool.result") {
+    throw new Error(`--tool only means something on tool.call and tool.result, not ${on}`);
+  }
+  const root = flags.library === true ? libraryRootOf(layout) : workspaceDirFor(flags, layout);
+  const rel = `hooks/${name}`;
+  const front = [
+    "---",
+    `on: ${on}`,
+    ...(tool ? [`tool: ${/[|*:]/.test(tool) ? JSON.stringify(tool) : tool}`] : []),
+    `description: What ${name} checks, in one line.`,
+    "---",
+    "",
+    `What ${name} is for, and what it refuses or rewrites. The code is run.mjs beside this file.`,
+    "",
+  ].join("\n");
+  writeFiles(root, [
+    { path: `${rel}/hook.md`, content: front },
+    { path: `${rel}/run.mjs`, content: hookRunTemplate(name, on) },
+  ], flags.library === true ? "the library" : path.basename(root));
+  const where = path.relative(process.cwd(), path.join(root, rel)) || rel;
+  console.log(`\n  ${c.green("created")} hook ${c.bold(name)} ${c.dim(`(${on}${tool ? ` · ${tool}` : ""})`)} in ${where}\n`);
+  console.log(`    ${c.dim(`${rel}/hook.md`)}\n    ${c.dim(`${rel}/run.mjs`)}`);
+  console.log(`\n  ${c.bold("Next")}
+    edit ${path.join(where, "run.mjs")}
+    hooks: [${name}]${" ".repeat(4)}${c.dim("in an agent's frontmatter — or in AGENTS.md for every agent")}
+    foldrun hook test ${name}${" ".repeat(4)}${c.dim("run it on a sample event, here")}\n`);
+  return 0;
+}
+
+/** --event: inline JSON, or @file. */
+function readHookEvent(raw, on) {
+  if (raw === undefined) return { event: HOOK_SAMPLE[on] ?? {}, sample: true };
+  if (typeof raw !== "string") throw new Error("--event takes a JSON object, or @file");
+  const text = raw.startsWith("@") ? fs.readFileSync(raw.slice(1), "utf8") : raw;
+  let event;
+  try { event = JSON.parse(text); } catch (err) {
+    throw new Error(`--event is not JSON (${err instanceof Error ? err.message : err})`);
+  }
+  if (!event || typeof event !== "object" || Array.isArray(event)) throw new Error("--event is one JSON object — the event the hook reads on stdin");
+  return { event, sample: false };
+}
+
+function printHookAnswer(name, on, a, where) {
+  const mark = !a.ok ? c.red("✗") : a.decision === "deny" ? c.amber("■") : c.green("✓");
+  console.log(`\n  ${mark} ${c.bold(name)}  ${c.dim(`${on ?? "?"} · ${where} · ${a.ms ?? 0}ms`)}`);
+  if (!a.ok) console.log(`  ${c.red("failed")}  ${a.failure ?? "no reason given"}${on === "tool.call" || on === "step.start" ? c.dim(" — a gate that fails refuses") : ""}`);
+  if (a.decision) console.log(`  ${pad("decision", 9)} ${a.decision === "deny" ? c.amber("deny") : "allow"}`);
+  if (a.reason) console.log(`  ${pad("reason", 9)} ${a.reason}`);
+  if (a.input) console.log(`  ${pad("input", 9)} ${JSON.stringify(a.input)}`);
+  if (a.context) console.log(`  ${pad("context", 9)} ${a.context}`);
+  if (a.reply !== undefined) console.log(`  ${pad("reply", 9)} ${a.reply}`);
+  if (a.note) console.log(`  ${pad("note", 9)} ${a.note}`);
+  console.log();
+  return a.ok ? 0 : 1;
+}
+
+/**
+ * `foldrun hook test <name> [--event '<json>']` — run one hook on one event,
+ * here, the way a step runs it (core's runHook: the event on stdin, a
+ * stripped environment, its timeout). `--to <workspace>` asks the platform
+ * to run the deployed one instead.
+ */
+async function hookTestCmd(positional, flags, layout) {
+  const name = positional[1];
+  if (!name) throw new Error("which hook? `foldrun hook test <name> --event '<json>'` — `foldrun hook ls` lists them");
+  if (typeof flags.to === "string") {
+    const url = platformFor(flags, "hook test");
+    const ws = flags.to;
+    let event = {};
+    if (flags.event !== undefined) event = readHookEvent(flags.event, "tool.call").event;
+    const r = /** @type {any} */ (await remoteCall(
+      url,
+      flags,
+      `/api/workspaces/${enc(ws)}/hooks/${enc(name)}/test`,
+      { method: "POST", body: JSON.stringify({ event }) },
+    ));
+    const a = r?.answer ?? r ?? {};
+    return printHookAnswer(name, r?.on ?? a.on, { ok: a.ok !== false, ...a }, ws);
+  }
+  const h = await needHooksCore();
+  const ws = workspaceDirFor({ ...flags, to: undefined }, layout);
+  const r = h.resolveHooks({ workspaceRoot: ws, libraryRoot: libraryRootOf(layout), names: [name] });
+  if (r.missing.length) throw new Error(`no hook named ${name} in hooks/ or the library — \`foldrun hook ls\` lists them`);
+  if (r.errors.length) throw new Error(r.errors[0]);
+  const def = r.hooks[0];
+  const { event, sample } = readHookEvent(flags.event, def.on);
+  if (sample) console.log(`\n  ${c.dim(`no --event, so a sample ${def.on} event: ${JSON.stringify(event)}`)}`);
+  const full = { event: def.on, hook: def.name, run_id: null, step: null, agent: null, workspace: path.basename(ws), ...event };
+  const a = await h.runHook(def, full, { cwd: ws, env: process.env });
+  return printHookAnswer(name, def.on, a, def.scope === "account" ? "library" : path.basename(ws));
+}
+
+async function hookRmCmd(positional, flags, layout) {
+  const h = await needHooksCore();
+  const name = positional[1];
+  if (!name) throw new Error("which hook? `foldrun hook rm <name>` (--library for the account's)");
+  const root = flags.library === true ? libraryRootOf(layout) : workspaceDirFor(flags, layout);
+  const dir = path.join(root, "hooks", name);
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name) || !fs.existsSync(dir)) {
+    throw new Error(`no hooks/${name} in ${flags.library === true ? "the library" : path.basename(root)} — \`foldrun hook ls\` lists them`);
+  }
+  // Who still turns it on: they fail check, and their steps are refused.
+  const users = [];
+  const wsRoots = flags.library === true
+    ? (layout.workspacesDir ? layout.workspaces.map((w) => path.join(layout.workspacesDir, w)) : [layout.workspaceDir].filter(Boolean))
+    : [root];
+  const matter = (await import("gray-matter")).default;
+  const names = (file) => {
+    try { return h.hookNames(matter(fs.readFileSync(file, "utf8")).data?.hooks); } catch { return []; }
+  };
+  for (const w of wsRoots) {
+    if (names(path.join(w, "AGENTS.md")).includes(name)) users.push(`${path.basename(w)}/AGENTS.md`);
+    for (const a of ls(path.join(w, "agents"))) {
+      if (names(path.join(w, "agents", a, "agent.md")).includes(name)) users.push(`${path.basename(w)}/agents/${a}`);
+    }
+  }
+  const still = users.length ? ` — still turned on by ${users.join(", ")}, whose steps will be refused until it goes from their hooks:` : "";
+  if (!(await sureToDelete(flags, "hook rm", `${flags.library === true ? "library/" : ""}hooks/${name}${still}`))) return 1;
+  fs.rmSync(dir, { recursive: true, force: true });
+  console.log(`\n  ${c.green("✓")} removed hooks/${name}${users.length ? c.dim(` — take it out of: ${users.join(", ")}`) : ""}\n`);
+  return 0;
+}
+
 // ------------------------------------------- flows and teams, as the canvas edits them
 //
 // The dashboard's flow canvas turns every palette block into a small, exact
@@ -6367,6 +7059,106 @@ function hasDescription(raw) {
   return /^\s+\S/.test(lines[at + 1] ?? "");
 }
 
+/** What an import leaves behind: what the agent accumulated, not what it is.
+ *  The same rule as core's agent-import.ts. */
+const NOT_IMPORTED = /^(memory|outputs|state|workspace|\.claude)(\/|$)|^\.claude\.json$/;
+
+/**
+ * `foldrun agent import <workspace>/<agent> [--as <name>]` — bring an agent
+ * you already have in another workspace into this one: its agent.md and its
+ * own skills/, scripts/, knowledge/ — never its memory. With `--to <ws>` it
+ * is the platform's POST /api/workspaces/<ws>/agents/import; without, it
+ * copies between workspaces of this account folder, into the one you stand
+ * in (or `--workspace <name>`).
+ */
+async function agentImportCmd(positional, flags, layout) {
+  // --list: what could be imported into a deployed workspace — every other
+  // workspace this key may read, and its agents (GET …/agents/import).
+  if (flags.list === true) {
+    const url = platformFor(flags, "agent import --list");
+    const ws = platformWorkspace(flags, layout, "agent import --list");
+    const { workspaces = [] } = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/agents/import`);
+    if (flags.json === true) {
+      console.log(JSON.stringify(workspaces, null, 2));
+      return 0;
+    }
+    if (!workspaces.length) {
+      console.log(`\n  ${c.dim(`nothing to import into ${ws} — no other workspace you can read has an agent`)}\n`);
+      return 0;
+    }
+    const w = Math.max(...workspaces.flatMap((x) => (x.agents ?? []).map((a) => `${x.name}/${a.name}`.length)));
+    console.log();
+    for (const x of workspaces) {
+      for (const a of x.agents ?? []) console.log(`  ${c.bold(pad(`${x.name}/${a.name}`, w))}  ${c.dim(firstLine(a.description ?? "", 80))}`);
+    }
+    console.log(`\n  ${c.dim(`foldrun agent import <workspace>/<agent> --to ${ws} [--as <name>] copies one in`)}\n`);
+    return 0;
+  }
+  const ref = positional[1];
+  const m = typeof ref === "string" ? /^([^/]+)\/([^/]+)$/.exec(ref) : null;
+  if (!m) throw new Error("which agent? `foldrun agent import <workspace>/<agent> [--as <name>] [--to <workspace>]`");
+  const [, from, agent] = m;
+  const as = typeof flags.as === "string" && flags.as.trim() ? flags.as.trim() : null;
+
+  if (typeof flags.to === "string") {
+    const url = platformFor(flags, "agent import");
+    const body = await remoteCall(url, flags, `/api/workspaces/${encodeURIComponent(flags.to)}/agents/import`, {
+      method: "POST",
+      body: JSON.stringify({ from, agent, ...(as ? { as } : {}) }),
+    });
+    console.log(`\n  ${c.green("✓")} ${c.bold(body.name)}  ${c.dim(`from ${from} → ${flags.to}`)}`);
+    for (const f of body.files ?? []) console.log(`  ${c.dim(f)}`);
+    for (const w of body.warnings ?? []) console.log(`  ${c.amber("!")} ${w}`);
+    console.log();
+    return 0;
+  }
+
+  if (!layout.workspacesDir) {
+    throw new Error("not in an account folder — pass --to <workspace> to import on the platform");
+  }
+  const name = as ?? agent;
+  assertName(name);
+  const src = path.join(layout.workspacesDir, from, "agents", agent);
+  if (!fs.existsSync(path.join(src, "agent.md"))) {
+    throw new Error(`no agent "${agent}" in ${from} — ${layout.workspaces.includes(from) ? "" : `this account has ${layout.workspaces.join(", ") || "no workspaces"}`}`.replace(/ — $/, ""));
+  }
+  const target =
+    typeof flags.workspace === "string"
+      ? path.join(layout.workspacesDir, flags.workspace)
+      : layout.workspaceDir && layout.kind !== "empty"
+        ? layout.workspaceDir
+        : null;
+  if (!target || !fs.existsSync(target)) throw new Error("into which workspace? cd into it, or --workspace <name>");
+  if (path.resolve(target) === path.resolve(path.join(layout.workspacesDir, from)) && name === agent) {
+    throw new Error(`${agent} is already in ${from} — give the copy another name with --as`);
+  }
+  const dest = path.join(target, "agents", name);
+  if (fs.existsSync(dest)) throw new Error(`${path.basename(target)} already has an agent called "${name}" — import it under another name with --as`);
+
+  const written = [];
+  const walk = (dir, rel = "") => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (NOT_IMPORTED.test(r) || e.isSymbolicLink()) continue;
+      if (e.isDirectory()) walk(path.join(dir, e.name), r);
+      else if (e.isFile()) {
+        let content = fs.readFileSync(path.join(dir, e.name));
+        if (r === "agent.md" && name !== agent) {
+          content = Buffer.from(content.toString("utf8").replace(/^(---\r?\n(?:[\s\S]*?\r?\n)?)name:[^\n]*$/m, `$1name: ${name}`));
+        }
+        fs.mkdirSync(path.dirname(path.join(dest, r)), { recursive: true });
+        fs.writeFileSync(path.join(dest, r), content);
+        written.push(`agents/${name}/${r}`);
+      }
+    }
+  };
+  walk(src);
+  console.log(`\n  ${c.green("✓")} ${c.bold(name)}  ${c.dim(`from ${from} → ${path.basename(target)}`)}`);
+  for (const f of written) console.log(`  ${c.dim(f)}`);
+  console.log(`  ${c.dim("its memory stayed in")} ${from}${c.dim(" — `foldrun check` names any tool, skill or secret it uses that this workspace lacks")}\n`);
+  return 0;
+}
+
 /**
  * `foldrun agent link <agent> --subagent <worker> | --consult <agent> |
  * --can-ask`, and `unlink` — an agent's team, edited in its frontmatter
@@ -6560,6 +7352,27 @@ async function flowShowCmd(positional, flags, layout) {
   return errors ? 1 : 0;
 }
 
+/**
+ * `foldrun flow hook <flow>` — the flow's webhook URL as it is now, changing
+ * nothing. Before this the only way to learn it from here was rotate-hook,
+ * which broke the URL whoever was already posting to it had.
+ */
+async function flowHookCmd(positional, flags, layout) {
+  const flow = positional[1];
+  if (!flow) throw new Error("which flow? `foldrun flow hook <flow> --to <workspace>`");
+  const url = platformFor(flags, "flow hook");
+  const ws = platformWorkspace(flags, layout, `flow hook ${flow}`);
+  const r = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/hooks/${enc(flow)}`);
+  const full = r.url ?? new URL(r.path, url).toString();
+  if (flags.json) {
+    console.log(JSON.stringify({ flow, url: full, path: r.path }));
+    return 0;
+  }
+  console.log(`\n  ${c.bold(full)}`);
+  console.log(`  ${c.dim("a credential — whoever has it can start this flow; `foldrun flow rotate-hook " + flow + "` replaces it")}\n`);
+  return 0;
+}
+
 /**
  * `foldrun flow rotate-hook <flow>` — a new webhook URL for one flow. The
  * old one stops working the moment this returns, so it asks first.
@@ -6652,9 +7465,20 @@ function bulkFilter(flags) {
   if (typeof flags.status === "string") body.status = flags.status.split(",").map((s) => s.trim()).filter(Boolean);
   if (typeof flags.flow === "string") body.flow = flags.flow;
   if (flags.since !== undefined) body.since = new Date(Date.now() - parseSince(flags.since)).toISOString();
+  if (flags.until !== undefined) body.until = untilInstant(flags.until);
   return body;
 }
-const hasBulkFilter = (flags) => typeof flags.status === "string" || typeof flags.flow === "string" || flags.since !== undefined;
+const hasBulkFilter = (flags) => typeof flags.status === "string" || typeof flags.flow === "string" || flags.since !== undefined || flags.until !== undefined;
+
+/** `--until 2h` (runs started at least that long ago) or a date — as the
+ *  ISO instant runs/bulk reads. A value that is neither refuses: a clause
+ *  that silently fell out would widen the filter. */
+function untilInstant(spec) {
+  if (/^\d+(\.\d+)?\s*[smhdw]$/i.test(String(spec).trim())) return new Date(Date.now() - parseSince(spec)).toISOString();
+  const t = typeof spec === "string" ? Date.parse(spec) : NaN;
+  if (Number.isNaN(t)) throw new Error(`--until wants a span like 2h (runs started before then) or a date, 2026-10-05T09:00 — not "${spec}"`);
+  return new Date(t).toISOString();
+}
 
 /**
  * `foldrun stop|rerun --status … --since … --flow …` — one decision, many
@@ -6728,7 +7552,7 @@ async function runRmCmd(runId, flags, layout) {
 /** Where downloaded bytes go: --file (or - for stdout), else a default name. Refuses to clobber. */
 function writeDownload(bytes, fallback, flags, from) {
   if (flags.file === "-") {
-    process.stdout.write(bytes);
+    writeExact(bytes);
     return 0;
   }
   const to = typeof flags.file === "string" ? flags.file : fallback;
@@ -6764,7 +7588,7 @@ async function apiCmd(positional, flags) {
   const out = typeof flags.out === "string" ? flags.out : typeof flags.file === "string" ? flags.file : "-";
   const pretty = JSON.stringify(doc, null, 2) + "\n";
   if (out === "-") {
-    process.stdout.write(pretty);
+    writeExact(pretty);
     return 0;
   }
   fs.writeFileSync(out, pretty);
@@ -6791,6 +7615,100 @@ async function remoteBytes(url, flags, apiPath, what) {
   return { bytes: Buffer.from(await res.arrayBuffer()), name };
 }
 
+/**
+ * `foldrun export [workspace] [--flow <name> | --agent <name>]` — a deployed
+ * workspace, one flow or one agent as a .zip: the authored source it needs,
+ * never memory, state, storage or a secret's value (GET …/export). The same
+ * file the dashboard's Export downloads and `foldrun import` takes in.
+ * @param {string[]} positional @param {Record<string, any>} flags
+ */
+async function exportCmd(positional, flags, layout) {
+  const url = platformFor(flags, "export");
+  const ws = positional[0] ?? platformWorkspace(flags, layout, "export");
+  if (typeof flags.flow === "string" && typeof flags.agent === "string") throw new Error("one at a time: --flow <name> or --agent <name>");
+  const kind = typeof flags.flow === "string" ? "flow" : typeof flags.agent === "string" ? "agent" : "workspace";
+  const name = kind === "flow" ? flags.flow : kind === "agent" ? flags.agent : null;
+  const qs = name ? `?kind=${kind}&name=${enc(name)}` : "";
+  const { bytes, name: served } = await remoteBytes(url, flags, `/api/workspaces/${enc(ws)}/export${qs}`, `export ${name ? `${kind} ${name} from ` : ""}${ws}`);
+  return writeDownload(bytes, served ?? (name ? `${ws}-${kind}-${name}.zip` : `${ws}.zip`), flags, name ? `${ws} · ${kind} ${name}` : ws);
+}
+
+/**
+ * `foldrun import <file.zip> [--to <workspace>]` — take a package in: shows
+ * what it adds, would replace and still needs (POST …/import?dryRun=1), then
+ * asks, then applies. Never deletes; replacing a file needs --overwrite. A
+ * workspace package into a name that does not exist makes that workspace.
+ * @param {string[]} positional @param {Record<string, any>} flags
+ */
+async function importCmd(positional, flags, layout) {
+  const file = positional[0];
+  if (!file) throw new Error("which package? `foldrun import <file.zip> [--to <workspace>]` — `foldrun export` or the dashboard's Export makes one");
+  if (!fs.existsSync(file)) throw new Error(`${file} does not exist`);
+  const url = platformFor(flags, "import");
+  const ws = platformWorkspace(flags, layout, "import");
+  const bytes = fs.readFileSync(file);
+  const token = tokenFor(url, flags);
+  const send = async (query) => {
+    const res = await remoteFetch(
+      url,
+      `/api/workspaces/${enc(ws)}/import${query}`,
+      { method: "POST", body: bytes, headers: { "content-type": "application/zip" } },
+      { token, seconds: timeoutSeconds(flags) },
+    );
+    const text = await res.text();
+    let body = {};
+    try {
+      body = text.trim() ? JSON.parse(text) : {};
+    } catch {
+      /* not JSON — the status says enough */
+    }
+    if (!res.ok) throw new HttpError(`${body.error ?? `import → HTTP ${res.status}`}${res.status === 401 || res.status === 403 ? refusedHint(url, flags) : ""}`, res.status, body);
+    return body;
+  };
+
+  const plan = await send("?dryRun=1");
+  const what = `${plan.kind === "workspace" ? "workspace" : `${plan.kind} ${plan.name}`}${plan.from ? ` from ${plan.from}` : ""}`;
+  if (flags.json === true && flags["dry-run"] === true) {
+    console.log(JSON.stringify(plan, null, 2));
+    return 0;
+  }
+  console.log(`\n  ${c.bold(what)} → ${c.bold(ws)}${plan.creates ? c.dim("  (a new workspace)") : ""}`);
+  console.log(`  ${plan.added.length} new · ${plan.unchanged.length} identical · ${plan.overwritten.length ? c.amber(`${plan.overwritten.length} would be replaced`) : "0 replaced"}`);
+  for (const p of plan.overwritten.slice(0, 20)) console.log(`    ${c.amber("~")} ${p}`);
+  if (plan.skipped?.length) console.log(`  ${c.dim(`${plan.skipped.length} not imported (memory, state, or outside the authored folders): ${plan.skipped.slice(0, 6).join(", ")}${plan.skipped.length > 6 ? " …" : ""}`)}`);
+  const needs = [
+    ["secrets to set", plan.needs?.secrets],
+    ["tools not here or in the library", plan.needs?.tools],
+    ["skills not found", plan.needs?.skills],
+    ["scripts not found", plan.needs?.scripts],
+    ["agents it names that are not here", plan.needs?.agents],
+    ["flows it runs that are not here", plan.needs?.flows],
+  ].filter(([, v]) => v?.length);
+  for (const [k, v] of needs) console.log(`  ${c.amber("!")} ${k}: ${v.join(", ")}`);
+
+  if (flags["dry-run"] === true) {
+    console.log(`\n  ${c.dim("(--dry-run: nothing written)")}\n`);
+    return 0;
+  }
+  if (plan.added.length + plan.overwritten.length === 0) {
+    console.log(`\n  ${c.dim("nothing to import — every file is already identical")}\n`);
+    return 0;
+  }
+  if (plan.overwritten.length && flags.overwrite !== true) {
+    console.log(`\n  ${c.dim(`nothing written — ${plan.overwritten.length} file${plan.overwritten.length === 1 ? "" : "s"} would be replaced; --overwrite replaces them (History can restore them)`)}\n`);
+    return 1;
+  }
+  if (!(await confirmed(flags, "import", `Import into ${ws}? [y/N] `))) {
+    console.log(`\n  ${c.dim("nothing written")}\n`);
+    return 0;
+  }
+  const done = await send(flags.overwrite === true ? "?overwrite=1" : "");
+  console.log(`\n  ${c.green("✓")} ${(done.written ?? []).length} file${(done.written ?? []).length === 1 ? "" : "s"} written to ${c.bold(ws)}${done.revision ? c.dim(`  revision ${done.revision}`) : ""}`);
+  if (needs.length) console.log(`  ${c.dim("set what it still needs before its first run — `foldrun secrets set <NAME>` for secrets")}`);
+  console.log();
+  return 0;
+}
+
 /**
  * `foldrun report <run-id> get <agent>/<path>` — one file a run archived:
  * whatever an agent left in outputs/, copied under the run when it ended.
@@ -6853,7 +7771,7 @@ async function observeCmd(flags, layout) {
   const obs = (
     await pool(names, 8, async (ws) => {
       try {
-        return await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/observe?since=${since}`);
+        return await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/observe?days=${since}`);
       } catch (err) {
         if (typeof flags.to === "string") throw err;
         unreachable.push([ws, explain(err)]);
@@ -6957,7 +7875,7 @@ async function billingVerbCmd(positional, flags) {
     if (flags.csv === true) {
       const { bytes, name } = await remoteBytes(url, flags, `/api/billing/statement?month=${month}&format=csv`, `statement ${month}`);
       if (typeof flags.file !== "string") {
-        process.stdout.write(bytes);
+        writeExact(bytes);
         return 0;
       }
       return writeDownload(bytes, name ?? `foldrun-${month}.csv`, flags, `the ${month} statement`);
@@ -7058,7 +7976,27 @@ async function billingVerbCmd(positional, flags) {
     return 0;
   }
 
-  throw new Error(`unknown billing verb "${verb}" — statement, wallet, details or portal (bare \`foldrun billing\` is the balance)`);
+  if (verb === "credit") {
+    // A manual credit (POST /api/billing): what a self-hosted or dev install
+    // without Stripe uses to put money on the balance. Once billing is live
+    // the platform refuses it — top-ups go through checkout.
+    const amount = Number(sub);
+    if (!(amount > 0) || !Number.isFinite(amount)) throw new Error("`foldrun billing credit <usd> [--note \"…\"]` — a positive amount in USD");
+    let r;
+    try {
+      r = await remoteCall(url, flags, "/api/billing", { method: "POST", body: JSON.stringify({ usd: amount, ...(typeof flags.note === "string" ? { note: flags.note } : {}) }) });
+    } catch (err) {
+      if (err instanceof HttpError && err.status === 403 && /checkout/.test(err.message)) {
+        throw new Error(`billing is live on this platform, so credit is not added by hand — \`foldrun billing top-up ${amount}\` (${err.message})`);
+      }
+      if (err instanceof HttpError && err.status === 403) throw new Error(`billing credit is the account owner's alone (billing:manage) — ${err.message}`);
+      throw err;
+    }
+    const bal = r.balanceUsd;
+    console.log(`\n  ${c.green("✓")} credited ${usd(amount)}${bal !== undefined ? c.dim(` · balance ${usd(bal)}`) : ""}${typeof flags.note === "string" ? c.dim(` · "${flags.note}"`) : ""}\n`);
+    return 0;
+  }
+  throw new Error(`unknown billing verb "${verb}" — statement, wallet, details, portal or credit (bare \`foldrun billing\` is the balance)`);
 }
 
 /** The defaults a workspace's AGENTS.md sets, read from its source. */
@@ -7253,6 +8191,49 @@ async function notificationsCmd(positional, flags) {
   return 0;
 }
 
+/** Why a flag is what it is, as `foldrun flags` says it. */
+const FLAG_SOURCES = {
+  account: "set for this account",
+  global: "set for every account",
+  rollout: "staged rollout",
+  default: "default",
+};
+
+/**
+ * `foldrun flags` — the feature flags as they stand for this account: on or
+ * off, and what decided it (this account's override, the install-wide
+ * setting, a percentage rollout, or the default). Read-only: only the
+ * platform's super admin changes a flag, in the console, with a session —
+ * an API key never reaches those routes, so the CLI has no verb for them.
+ */
+async function flagsCmd(positional, flags) {
+  const url = platformFor(flags, "flags");
+  if (positional[0]) throw new Error("`foldrun flags` lists this account's feature flags — they are changed by the platform's super admin, not from here");
+  const r = await remoteCall(url, flags, "/api/account/flags");
+  if (flags.json === true) {
+    console.log(JSON.stringify(r, null, 2));
+    return 0;
+  }
+  const list = r.flags ?? [];
+  if (!list.length) {
+    console.log(`\n  ${c.dim("no feature flags on this platform")}\n`);
+    return 0;
+  }
+  const w = Math.max(...list.map((f) => f.name.length));
+  const sw = Math.max(...list.map((f) => why(f).length));
+  console.log("");
+  for (const f of list) {
+    const state = f.on ? c.green("on ") : c.dim("off");
+    console.log(`  ${pad(f.name, w)}  ${state}  ${c.dim(pad(why(f), sw))}  ${f.description}`);
+  }
+  console.log(`\n  ${c.dim("read-only — the platform's super admin turns flags on and off")}\n`);
+  return 0;
+  function why(f) {
+    const base = FLAG_SOURCES[f.source] ?? String(f.source ?? "");
+    return f.source === "rollout" && typeof f.rollout === "number" ? `${base} ${f.rollout}%` : base;
+  }
+}
+
 /**
  * `foldrun history [path] --to <workspace>` — every change to a deployed
  * workspace, newest first: who, what, which files. `--id <revision>` shows
@@ -7425,7 +8406,27 @@ async function backupsCmd(positional, flags) {
     console.log(`  ${request.notified ? c.dim("the platform team has been emailed; nothing is restored until they do it") : c.yellow("recorded, but the email to the platform team did not send — contact them as well")}\n`);
     return 0;
   }
-  if (verb !== "ls" && verb !== "list") throw new Error(`unknown backups verb "${verb}" — ls, request`);
+  if (verb === "requests") {
+    // Every restore this account has asked the platform team for, and where
+    // each stands (GET /api/account/backups/requests) — `backups` shows five.
+    const { requests = [] } = await remoteCall(url, flags, "/api/account/backups/requests");
+    if (flags.json === true) {
+      console.log(JSON.stringify(requests, null, 2));
+      return 0;
+    }
+    if (!requests.length) {
+      console.log(`\n  ${c.dim("no restore requests — foldrun backups request --what runs --at \"<when>\" asks for one")}\n`);
+      return 0;
+    }
+    console.log();
+    for (const r of requests) {
+      console.log(`  ${when(r.at)}  ${c.bold(r.status)}  ${r.what} · ${r.workspace ?? "every workspace"} · to ${r.target}  ${c.dim(`${r.id} · ${r.by}${r.notified ? "" : " · platform team not emailed"}`)}`);
+      if (r.note) console.log(`      ${c.dim(firstLine(r.note, 100))}`);
+    }
+    console.log(`\n  ${c.dim(`${requests.length} request${requests.length === 1 ? "" : "s"} · the platform team restores; nothing here changes until they do`)}\n`);
+    return 0;
+  }
+  if (verb !== "ls" && verb !== "list") throw new Error(`unknown backups verb "${verb}" — ls, request, requests`);
   const b = await remoteCall(url, flags, "/api/account/backups");
   if (flags.json === true) {
     console.log(JSON.stringify(b, null, 2));
@@ -7908,7 +8909,7 @@ async function scheduleTickCmd(flags) {
   return 0;
 }
 
-const LIBRARY_KINDS_CLI = ["skills", "tools", "scripts", "knowledge"];
+const LIBRARY_KINDS_CLI = ["skills", "tools", "hooks", "scripts", "knowledge", "memory"];
 
 /**
  * `foldrun library [ls [kind]] | cat <kind>/<path> | put <kind>/<path> | rm
@@ -7928,20 +8929,27 @@ async function libraryCmd(positional, flags) {
   if (verb === "ls" || verb === "list") {
     const kinds = spec ? [spec] : LIBRARY_KINDS_CLI;
     for (const k of kinds) if (!LIBRARY_KINDS_CLI.includes(k)) throw new Error(`no library kind "${k}" — ${LIBRARY_KINDS_CLI.join(", ")}`);
-    const lists = await Promise.all(kinds.map((k) => remoteCall(url, flags, `/api/library/${k}`)));
+    // Listing everything, a kind an older platform does not have yet (hooks
+    // before 11 Oct 2026) is left out rather than failing the whole list;
+    // asked for by name, it fails with the platform's own answer.
+    const lists = await Promise.all(kinds.map((k) => remoteCall(url, flags, `/api/library/${k}`).catch((err) => {
+      if (spec) throw err;
+      return null;
+    })));
     console.log();
     lists.forEach((l, n) => {
+      if (!l) return;
       const entries = l.entries ?? [];
       console.log(`  ${c.bold(kinds[n])} ${c.dim(`${entries.length}`)}`);
       for (const e of entries) console.log(`    ${pad(e.name ?? e.path ?? "", 28)} ${c.dim(firstLine(e.description ?? "", 70))}`);
     });
-    console.log(`\n  ${c.dim("foldrun library cat <kind>/<path> · put <kind>/<path> (--file, else stdin) · rm <kind>/<path>")}\n`);
+    console.log(`\n  ${c.dim("foldrun library cat <kind>/<path> · put <kind>/<path> (--file, else stdin) · new <kind>/<name> · rm <kind>/<path>")}\n`);
     return 0;
   }
   if (verb === "cat") {
     const { kind, rel } = split(spec);
     const { content } = await remoteCall(url, flags, `/api/library/${kind}?path=${enc(rel)}`);
-    process.stdout.write(content ?? "");
+    writeExact(content ?? "");
     return 0;
   }
   if (verb === "put") {
@@ -7954,6 +8962,17 @@ async function libraryCmd(positional, flags) {
     console.log(`\n  ${c.green("✓")} library/${kind}/${rel} ${c.dim(`${humanBytes(Buffer.byteLength(content))} — every workspace in the account sees it`)}\n`);
     return 0;
   }
+  if (verb === "new") {
+    // The Library page's New (POST /api/library/<kind>): the platform writes
+    // the template — a blank one, a tool of a transport, or a gallery entry
+    // under this name (--template).
+    const { kind, rel: name } = split(spec);
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) throw new Error(`"${name}" is not a name — kebab-case only, e.g. skills/house-style`);
+    const body = { name, ...(typeof flags.template === "string" ? { template: flags.template } : {}), ...(typeof flags.language === "string" ? { language: flags.language } : {}) };
+    const r = await remoteCall(url, flags, `/api/library/${kind}`, { method: "POST", body: JSON.stringify(body) });
+    console.log(`\n  ${c.green("✓")} library/${kind}/${r.path ?? name} ${c.dim("— every workspace in the account sees it")}\n`);
+    return 0;
+  }
   if (verb === "rm") {
     const { kind, rel } = split(spec);
     if (!(await sureToDelete(flags, "library rm", `library/${kind}/${rel} — every workspace that names it loses it`))) return 1;
@@ -7961,7 +8980,7 @@ async function libraryCmd(positional, flags) {
     console.log(`\n  ${c.green("✓")} removed library/${kind}/${rel}\n`);
     return 0;
   }
-  throw new Error(`unknown library verb "${verb}" — ls [kind], cat, put, rm`);
+  throw new Error(`unknown library verb "${verb}" — ls [kind], cat, put, new, rm`);
 }
 
 /**
@@ -8199,10 +9218,29 @@ async function apiVersionCmd(positional, flags) {
   console.log(`\n  ${c.bold("API version")}  ${v.effective}  ${c.dim(v.pinned ? `pinned (current is ${v.current})` : "current — not pinned")}`);
   console.log(`  ${c.dim(`served: ${(v.supported ?? []).join(", ") || "—"} · each for ${v.supportMonths ?? "?"} months after the next · this CLI sends ${API_VERSION}`)}`);
   if (l.perCredential) console.log(`  ${c.bold("rate limits")}  ${c.dim(`${l.plan} · per key ${l.perCredential.read} reads / ${l.perCredential.write} writes, per account ${l.perAccount?.read} / ${l.perAccount?.write} — every ${l.windowSeconds}s`)}`);
+  apiUsageLines(facts.usage);
   console.log(`\n  ${c.dim("foldrun api version pin YYYY-MM-DD · unpin")}\n`);
   return 0;
 }
 
+/** The account's use of the API, last 30 days: requests by version, and any
+ *  deprecated route it still calls, by whom, and when it stops. An older
+ *  platform sends no `usage`; null means it could not be read. */
+function apiUsageLines(usage) {
+  if (usage === undefined) return;
+  if (usage === null) {
+    console.log(`  ${c.bold("your use")}  ${c.dim("could not be read just now")}`);
+    return;
+  }
+  const total = (usage.versions ?? []).reduce((s, v) => s + (v.requests ?? 0), 0);
+  const day = (iso) => String(iso ?? "").slice(0, 10);
+  console.log(`  ${c.bold("your use")}  ${c.dim(total ? `last ${usage.days} days: ` + usage.versions.map((v) => `${v.version} ${v.requests} (last ${day(v.lastSeen)})`).join(" · ") : `no API requests in the last ${usage.days} days`)}`);
+  for (const d of usage.deprecated ?? []) {
+    console.log(`  ${c.amber("deprecated")}  ${d.route} — ${d.requests} request${d.requests === 1 ? "" : "s"}, last ${day(d.lastSeen)}; ${d.sunsetAt ? `stops answering ${day(d.sunsetAt)}` : "no end date yet"}${d.link ? ` · ${d.link}` : ""}`);
+    for (const who of d.callers ?? []) console.log(`    ${c.dim(`${who.credential || "an unknown caller"}: ${who.requests}, last ${day(who.lastSeen)}`)}`);
+  }
+}
+
 const THEMES_CLI = ["system", "light", "dark"];
 
 /**
@@ -8230,7 +9268,8 @@ async function preferencesCmd(positional, flags) {
   return 0;
 }
 
-/** `foldrun changelog [--limit n]` — What's new: each release and what it changed. */
+/** `foldrun changelog [--limit n]` — What's new: the API's versions, what each
+ *  broke and what is deprecated, then each release and what it changed. */
 async function changelogCmd(flags) {
   const url = platformFor(flags, "changelog");
   const limit = Number(flags.limit) > 0 ? Math.min(50, Math.floor(Number(flags.limit))) : 5;
@@ -8239,6 +9278,7 @@ async function changelogCmd(flags) {
     console.log(JSON.stringify(r, null, 2));
     return 0;
   }
+  if (r.api) apiChangelogLines(r.api);
   const releases = r.releases ?? [];
   if (!releases.length) {
     console.log(`\n  ${c.dim(`no release notes on this install (it runs ${r.version ?? "an unreleased build"})`)}\n`);
@@ -8261,6 +9301,25 @@ async function changelogCmd(flags) {
   return 0;
 }
 
+/** The API part of What's new: the current version, the breaking changes by
+ *  version, and routes on their way out. Older platforms send no `api`. */
+function apiChangelogLines(api) {
+  const p = printable;
+  const broke = (api.versions ?? []).filter((v) => v.changes?.length);
+  const deps = api.deprecations ?? [];
+  console.log(`\n  ${c.bold(`API ${p(api.current)}`)}  ${c.dim(`each version works ${Number(api.supportMonths) || 12} months or more after the next · pin: foldrun api version pin <date>`)}`);
+  if (!broke.length && !deps.length) {
+    console.log(`    ${c.dim("nothing existing code would break on, and nothing deprecated")}`);
+    return;
+  }
+  if (broke.length) console.log(`    ${c.dim("breaking changes")}`);
+  for (const v of broke) for (const ch of v.changes) console.log(`    · ${p(v.version)}  ${firstLine(p(ch), 100)}`);
+  if (deps.length) console.log(`    ${c.dim("deprecated")}`);
+  for (const d of deps) {
+    console.log(`    · ${p(d.route)} — since ${p(d.deprecatedAt)}, ${d.sunsetAt ? `stops answering ${p(d.sunsetAt)}` : "no end date yet"}${d.link ? ` · ${p(d.link)}` : ""}`);
+  }
+}
+
 /**
  * `foldrun find <query>` — the ⌘K search: workspaces, agents, flows, tools,
  * skills, knowledge, memory and runs across the account, ranked as the
@@ -8290,6 +9349,95 @@ async function findCmd(positional, flags) {
 }
 
 /** `foldrun workspaces demo` — "Try the demo pipeline": the demo workspace, made on the platform. */
+/**
+ * `foldrun workspaces show <name>` — what is deployed in one workspace (GET
+ * /api/workspaces/<name>): its agents, its flows and how they fire, and its
+ * files, counted by top-level folder.
+ */
+async function workspacesShowCmd(name, flags) {
+  const url = platformFor(flags, "workspaces show");
+  if (!name) throw new Error("which workspace? `foldrun workspaces show <name>`");
+  const r = await remoteCall(url, flags, `/api/workspaces/${enc(name)}`);
+  if (flags.json === true) {
+    console.log(JSON.stringify(r, null, 2));
+    return 0;
+  }
+  const agents = r.agents ?? [];
+  const flows = r.flows ?? [];
+  const files = r.files ?? [];
+  console.log(`\n  ${c.bold(r.name ?? name)}  ${c.dim(`on ${url} — ${agents.length} agent${agents.length === 1 ? "" : "s"}, ${flows.length} flow${flows.length === 1 ? "" : "s"}, ${files.length} file${files.length === 1 ? "" : "s"}`)}`);
+  if (agents.length) {
+    const w = Math.max(...agents.map((a) => a.name.length));
+    console.log(`\n  ${c.dim("agents")}`);
+    for (const a of agents) console.log(`  ${c.bold(pad(a.name, w))}  ${pad(a.model ?? "", 8)} ${c.dim(firstLine(a.description ?? "", 70))}`);
+  }
+  if (flows.length) {
+    const w = Math.max(...flows.map((f) => f.name.length));
+    console.log(`\n  ${c.dim("flows")}`);
+    for (const f of flows) {
+      const fires = f.trigger === "schedule" && f.schedule ? `schedule ${f.schedule}${f.timezone ? ` ${f.timezone}` : ""}` : (f.trigger ?? "manual");
+      console.log(`  ${c.bold(pad(f.name, w))}  ${c.dim(fires)}`);
+    }
+  }
+  if (files.length) {
+    const by = new Map();
+    for (const f of files) {
+      const top = f.includes("/") ? `${f.slice(0, f.indexOf("/"))}/` : f;
+      by.set(top, (by.get(top) ?? 0) + 1);
+    }
+    console.log(`\n  ${c.dim("files")}`);
+    console.log(`  ${[...by].map(([k, n]) => (n > 1 || k.endsWith("/") ? `${k} ${c.dim(String(n))}` : k)).join("  ")}`);
+  }
+  console.log(`\n  ${c.dim(`foldrun source ls --to ${r.name ?? name} lists every file · --json for the whole document`)}\n`);
+  return 0;
+}
+
+/**
+ * `foldrun eval new <name> --to <workspace>` — the Evals page's New: the
+ * platform writes an eval whose agent is the workspace's first (POST
+ * …/evals). Edit the cases, then `foldrun eval <name> --to` runs it.
+ */
+async function evalNewCmd(name, flags, layout) {
+  const url = platformFor(flags, "eval new");
+  const ws = platformWorkspace(flags, layout, `eval new ${name}`);
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) throw new Error(`"${name}" is not an eval name — kebab-case only, e.g. researcher-quality`);
+  const r = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals`, { method: "POST", body: JSON.stringify({ name }) });
+  console.log(`\n  ${c.green("created")} eval ${c.bold(name)} in ${ws} ${c.dim(`on ${url}`)}`);
+  console.log(`    ${c.dim(r.path ?? `evals/${name}.md`)}`);
+  console.log(`\n  ${c.dim(`its cases are placeholders: foldrun source cat ${r.path ?? `evals/${name}.md`} --to ${ws}, then foldrun eval ${name} --to ${ws}`)}\n`);
+  return 0;
+}
+
+/**
+ * `foldrun team` — who is in the account, their role and which workspaces
+ * they may open (GET /api/team). Read-only on purpose: inviting, changing a
+ * role, removing someone and transferring the account are a person's acts,
+ * and the platform refuses them from a key.
+ */
+async function teamCmd(positional, flags) {
+  if (positional[0]) {
+    throw new Error("`foldrun team` lists the members — invites, role changes, removals and transfer are done by a signed-in person in Settings → Team; the platform refuses them from a key");
+  }
+  const url = platformFor(flags, "team");
+  const { members = [] } = await remoteCall(url, flags, "/api/team");
+  if (flags.json === true) {
+    console.log(JSON.stringify(members, null, 2));
+    return 0;
+  }
+  if (!members.length) {
+    console.log(`\n  ${c.dim("no members visible to this key")}\n`);
+    return 0;
+  }
+  const w = Math.max(...members.map((m) => m.email.length));
+  console.log();
+  for (const m of members) {
+    const scope = m.workspaces === null || m.workspaces === undefined ? "every workspace" : m.workspaces.length ? m.workspaces.join(", ") : "no workspaces";
+    console.log(`  ${c.bold(pad(m.email, w))}  ${pad(m.owner ? "owner" : m.role, 7)} ${c.dim(scope)}  ${c.dim(m.createdAt ? `joined ${String(m.createdAt).slice(0, 10)}` : "")}`);
+  }
+  console.log(`\n  ${c.dim(`${members.length} member${members.length === 1 ? "" : "s"} · invites, roles and removals: Settings → Team in the dashboard (a person's, never a key's)`)}\n`);
+  return 0;
+}
+
 async function workspacesDemoCmd(flags) {
   const url = platformFor(flags, "workspaces demo");
   const r = await remoteCall(url, flags, "/api/workspaces", { method: "POST", body: JSON.stringify({ demo: true }) });
@@ -8378,7 +9526,7 @@ function printPreview(p, rel) {
     case "text":
     case "html":
     case "svg":
-      process.stdout.write(`${p.text ?? p.html ?? p.svg ?? ""}`.replace(/\n?$/, "\n"));
+      writeExact(`${p.text ?? p.html ?? p.svg ?? ""}`.replace(/\n?$/, "\n"));
       if (p.truncated) out(c.dim("… (truncated)"));
       return;
     case "table":
@@ -8496,10 +9644,15 @@ export async function run(command, positional, flags, workspace, layout) {
           : check(workspace, flags);
     case "pull":
       return pullCmd(layout, flags, positional[0]);
+    case "export":
+      return exportCmd(positional, flags, layout);
+    case "import":
+      return importCmd(positional, flags, layout);
     case "status":
       return statusCmd(layout, flags, positional[0]);
     case "workspaces":
       if (positional[0] === "demo") return workspacesDemoCmd(flags);
+      if (positional[0] === "show") return workspacesShowCmd(positional[1], flags);
       return workspacesCmd(positional, flags, layout);
     case "extract":
       return extract(workspace, flags);
@@ -8509,6 +9662,9 @@ export async function run(command, positional, flags, workspace, layout) {
       needsOne(layout, "run");
       return runTarget(positional[0], flags);
     case "eval":
+      // `eval new <name>` makes one on the platform; an eval called "new"
+      // still runs as `foldrun eval new` with nothing after it.
+      if (positional[0] === "new" && positional[1]) return evalNewCmd(positional[1], flags, layout);
       // --to names a deployed workspace: its evals run there.
       if (typeof flags.to === "string") return remoteEvalsCmd(positional[0], flags, layout);
       needsOne(layout, "eval");
@@ -8528,6 +9684,8 @@ export async function run(command, positional, flags, workspace, layout) {
       return webhooksCmd(positional, flags, layout);
     case "notifications":
       return notificationsCmd(positional, flags);
+    case "flags":
+      return flagsCmd(positional, flags);
     case "history":
       if (positional[0] === "restore") return historyRestoreCmd(positional, flags, layout);
       return historyCmd(positional, flags, layout);
@@ -8537,6 +9695,8 @@ export async function run(command, positional, flags, workspace, layout) {
       return restoreCmd(positional, flags);
     case "backups":
       return backupsCmd(positional, flags);
+    case "team":
+      return teamCmd(positional, flags);
     case "onboarding":
       return onboardingCmd(flags);
     case "probe":
@@ -8609,6 +9769,8 @@ export async function run(command, positional, flags, workspace, layout) {
       // `new` scaffolds one here; `run` runs one there. The noun is the same
       // thing in both cases, which is why they share a command.
       if (positional[0] === "link" || positional[0] === "unlink") return agentLinkCmd(positional, flags, layout);
+      if (positional[0] === "import") return agentImportCmd(positional, flags, layout);
+      if (positional[0] === "ls" || positional[0] === "list") return remoteListCmd("agents", flags, layout);
       return positional[0] === "run"
         ? agentRunCmd(positional, flags, layout)
         : scaffoldCmd("agents", positional, flags, layout);
@@ -8621,17 +9783,22 @@ export async function run(command, positional, flags, workspace, layout) {
       if (positional[0] === "show") return flowShowCmd(positional, flags, layout);
       if (positional[0] === "run") return invoke(positional[1], flags);
       if (positional[0] === "rotate-hook") return rotateHookCmd(positional, flags, layout);
+      if (positional[0] === "hook") return flowHookCmd(positional, flags, layout);
       if (positional[0] === "set") return flowSetCmd(positional, flags, layout);
       if (positional[0] === "trigger") return flowTriggerCmd(positional, flags, layout);
       if (positional[0] === "move-step") return flowMoveStepCmd(positional, flags, layout);
       if (positional[0] === "copy-step") return flowCopyStepCmd(positional, flags, layout);
       if (positional[0] === "paste") return flowPasteCmd(positional, flags, layout);
       if (positional[0] === "draft") return flowDraftCmd(positional, flags, layout);
+      if (positional[0] === "ls" || positional[0] === "list") return remoteListCmd("flows", flags, layout);
       return scaffoldCmd("flows", positional, flags, layout);
     case "tool":
       return positional[0] === "test"
         ? toolTestCmd(positional, flags, layout)
         : scaffoldCmd("tools", positional, flags, layout);
+    case "hook":
+    case "hooks":
+      return hookCmd(positional, flags, layout);
     case "invoke":
       return invoke(positional[0], flags);
     case "source":