@tiens.nguyen/gu-cli 1.0.884 → 1.0.885

package/README.md

@@ -126,6 +126,9 @@ Ctrl-C stops the running turn. Type `/` at the prompt to see every command; Tab
 | `/mcp [list\|tools\|add\|remove\|enable\|disable\|approve\|allow\|disallow\|reconnect]` | MCP servers, and which of their tools run without asking |
 | `/hooks [list\|approve\|unapprove]` | commands gu runs on `onStart`, `onAsk`, `onToolDone`, `onTurnEnd` |
 | `/switch-skill [claude\|gu]` | use Claude Code's (`.claude`) or gu's (`.gonext`) skills, MCP servers and hooks in this folder |
+| `/skill-pack <name> [--out <file>] [--runtime <dir>]` | pack a skill with its MCP servers, hooks and code into one zip for another machine (no venvs, databases or secrets) |
+| `/skill-install <zip\|folder> [--gu] [--claude] [--dry-run]` | install a packed skill for gu and Claude Code; without gu: `node <name>/install.mjs` |
+| `/resume` | carry on the last unfinished task in this folder, Claude Code's or gu's: shows its plan, last command and next step, then asks (needs the memory skill) |
 | `/skills-copy-to-claude [--dry-run] [name…]` | copy gu's skills into Claude Code's folders |
 | `/proxy [show\|set\|on\|off\|clear\|test]` | route model calls through an HTTP proxy (local calls go direct) |
 | `/s3 [test]` | use your own S3 bucket for the RAG index and generated files |

package/gu-repl.mjs

@@ -1051,6 +1051,9 @@ const COMMANDS = [
   { name: "/hooks", usage: "/hooks [list|approve|unapprove]", desc: "hooks: commands gu runs on onStart, onAsk, onToolDone, onTurnEnd — list them, approve this project's" },
   { name: "/mcp", usage: "/mcp [list|tools|add|remove|enable|disable|approve|allow|disallow|reconnect]", desc: "MCP servers: see which connect, add one (asks step by step), choose which tools run without asking" },
   { name: "/switch-skill", usage: "/switch-skill [claude|gu]", desc: "whose skills, MCP servers and hooks this folder uses — Claude Code's (.claude) or gu's own (.gonext)" },
+  { name: "/resume", desc: "carry on the last unfinished task in this folder — Claude Code's or gu's — from where it stopped (memory skill)" },
+  { name: "/skill-pack", usage: "/skill-pack <name> [--out <file>] [--runtime <dir>]", desc: "pack a skill (gu's or Claude's) with its MCP servers, hooks and code into one zip for another machine" },
+  { name: "/skill-install", usage: "/skill-install <zip|folder> [--gu] [--claude] [--dry-run]", desc: "install a packed skill for gu and Claude Code (whichever is set up here)" },
   { name: "/skills-copy-to-claude", usage: "/skills-copy-to-claude [--dry-run] [name…]", desc: "copy gu's skills (.gonext) into Claude Code's folders (.claude), renamed to Claude's names, with their MCP servers" },
   { name: "/help", desc: "list these commands" },
   { name: "/exit", aliases: ["/quit"], desc: "quit" },
@@ -7787,6 +7790,140 @@ async function runSwitchSkillCommand(line) {
   if (barPinned()) paintBar();
 }
 
+/** "--out x" style option from a command line's words → value, or undefined. */
+function optionValue(words, flag) {
+  const i = words.indexOf(flag);
+  return i >= 0 ? words[i + 1] : undefined;
+}
+
+/**
+ * /skill-pack <name> [--out <file>] [--runtime <dir>] — one skill, with its MCP servers, hooks and
+ * the code they run, into one zip another machine installs (#281, skill-package.mjs). Shows what
+ * it found, then writes; a secret-looking line refuses the pack.
+ */
+async function runResumeCommand() {
+  const rm = await import("./resume-memory.mjs");
+  const { hooksForTurn } = await import("./hooks-config.mjs");
+  const say = (l) => console.log(GUTTER + l);
+  console.log("");
+  const r = rm.readResume({ cwd: process.cwd(), found: rm.findMemoryCli({ cwd: process.cwd(), hooksFor: hooksForTurn }) });
+  if (r.error) {
+    say(yellow(r.error) + "\n");
+    return null;
+  }
+  if (!r.resume) {
+    say(dim("Nothing to resume here: every recent session finished its plan.\n"));
+    return null;
+  }
+  for (const l of r.block.split("\n").filter((l) => !l.startsWith("If the user wants"))) say(l.startsWith("## ") ? bold(l.slice(3)) : dim(l));
+  console.log("");
+  if (!(await askYesNo(rm.resumeQuestion(r.resume), true))) {
+    console.log("");
+    return null;
+  }
+  return rm.resumePrompt(r.block, r.resume);
+}
+
+async function runSkillPackCommand(line) {
+  const sp = await import("./skill-package.mjs");
+  const words = line.trim().split(/\s+/).slice(1);
+  const out = optionValue(words, "--out");
+  const runtime = optionValue(words, "--runtime");
+  const name = words.find((w, i) => !w.startsWith("--") && !["--out", "--runtime"].includes(words[i - 1]));
+  const home = homedir();
+  const cwd = resolve(process.cwd());
+  const tilde = (p) => (String(p).startsWith(home) ? "~" + String(p).slice(home.length) : p);
+  const say = (l) => console.log(GUTTER + l);
+  console.log("");
+  if (!name) {
+    say(dim("usage: /skill-pack <name> [--out <file>] [--runtime <dir>]\n"));
+    return;
+  }
+  let plan;
+  try {
+    plan = sp.planSkillPack(name, { cwd, home, runtime });
+  } catch (err) {
+    say(red(`${err.message}\n`));
+    return;
+  }
+  const f = plan.found;
+  say(bold(`Pack ${plan.manifest.name}`) + dim(`  (${f.source === "gu" ? "gu's" : "Claude Code's"} ${f.scope === "project" ? "project" : "user"} skill)`));
+  say(dim(`  skill    ${tilde(f.skillDir)}  ${plan.skill.size} file${plan.skill.size === 1 ? "" : "s"}`));
+  if (f.runtimeDir) say(dim(`  runtime  ${tilde(f.runtimeDir)}  ${plan.runtime.size} files${f.python ? " · venv rebuilt from requirements.txt" : ""}`));
+  for (const s of f.servers) say(dim(`  MCP      ${s}`));
+  if (f.hooks.length) say(dim(`  hooks    ${f.hooks.join(", ")}`));
+  if (plan.manifest.env?.length) say(dim(`  asked on install, not packed: ${plan.manifest.env.join(", ")}`));
+  if (plan.skipped.length) say(dim(`  left out ${plan.skipped.join(", ")}`));
+  for (const w of plan.warnings) say(yellow(`  ${w}`));
+  if (plan.secrets.length) {
+    for (const s of plan.secrets) say(red(`  ✗ ${s.file}:${s.line} looks like ${s.kind}`));
+    say(red("  Not packed — remove those and run /skill-pack again.\n"));
+    return;
+  }
+  const file = resolve(out ?? `${plan.manifest.name}.zip`);
+  try {
+    const r = sp.writeSkillPack(plan, file);
+    say(`${accent("✓")} ${tilde(r.file)} ${dim(`${Math.ceil(r.bytes / 1024)} KB, ${r.count} files`)}`);
+    say(dim(`   On the other machine:  /skill-install ${file.split(/[\\/]/).pop()}`));
+    // platform-ok: shown to the user — the folder inside the zip, which unzip makes with "/" names.
+    say(dim(`   Without gu:            unzip it, then node ${plan.manifest.name}/install.mjs\n`));
+  } catch (err) {
+    say(red(`couldn't write the zip — ${err.message}\n`));
+  }
+}
+
+/**
+ * /skill-install <zip|folder> [--gu] [--claude] [--dry-run] — a packed skill onto this machine
+ * (skill-install.mjs, the same code as the package's own install.mjs). Shows the plan, then asks.
+ */
+async function runSkillInstallCommand(line) {
+  const si = await import("./skill-install.mjs");
+  const words = line.trim().split(/\s+/).slice(1);
+  const src = words.find((w) => !w.startsWith("--"));
+  const targets = si.TARGETS.filter((t) => words.includes(`--${t}`));
+  const home = homedir();
+  const tilde = (p) => String(p).split(home).join("~");
+  const say = (l) => console.log(GUTTER + l);
+  console.log("");
+  if (!src) {
+    say(dim("usage: /skill-install <zip|folder> [--gu] [--claude] [--dry-run]\n"));
+    return;
+  }
+  let plan;
+  try {
+    plan = si.planInstall(si.loadPackage(resolve(src.replace(/^~(?=\/|$)/, home))), { home, targets });
+  } catch (err) {
+    say(red(`Not installed — ${err.message}\n`));
+    return;
+  }
+  const lines = si.describePlan(plan, tilde);
+  say(bold(lines[0]));
+  for (const l of lines.slice(1)) say(l.trimStart().startsWith("!") ? yellow(l) : dim(l));
+  if (!si.planHasWork(plan)) {
+    say(dim("\n   Nothing to do — it is already installed.\n"));
+    return;
+  }
+  if (words.includes("--dry-run")) {
+    say(dim("\n   --dry-run: nothing was written.\n"));
+    return;
+  }
+  console.log(dim(`\n   ${PICK_HINT}:`));
+  const options = ["Install", "Cancel"];
+  const idx = await pickFromList(options, 0);
+  if (idx !== 0) {
+    console.log(dim("   (cancelled — nothing installed)\n"));
+    paintBar();
+    return;
+  }
+  const r = si.applyInstall(plan, { say: (l) => say(dim(l)) });
+  for (const d of r.done) say(`${accent("✓")} ${dim(tilde(d))}`);
+  for (const e of r.errors) say(red(`✗ ${e}`));
+  if (r.backups) say(dim(`   Old copies: ${tilde(r.backups)}`));
+  if (!r.errors.length) say(dim(`   ${si.nextStep(plan)}`));
+  console.log("");
+  paintBar();
+}
+
 /**
  * /skills-copy-to-claude [--dry-run] [name…] — gu's skills into Claude Code's folders (#241):
  * ~/.gonext/skills → ~/.claude/skills and ./.gonext/skills → ./.claude/skills, "gu-" names become
@@ -14808,6 +14945,13 @@ async function main() {
       console.log("\n" + GUTTER + dim(`⏺ background ${entries.length === 1 ? "shell" : "shells"} finished — ${entries.map((e) => `${e.rec.id} ${shellStatusText(e.st)}`).join(", ")} · gu asks the agent to recap`));
       lineRaw = recapQuestion(entries);
     }
+    // /resume (#285): show where the last unfinished session stopped; on "yes" the line becomes the
+    // prompt that carries it on, and the turn runs as if it had been typed.
+    if (lineRaw.trim() === "/resume") {
+      const prompt = await runResumeCommand();
+      if (!prompt) continue;
+      lineRaw = prompt;
+    }
     const line = lineRaw.trim();
     // #302: what was typed for THIS line (before expansion), and whether it was sent from a
     // stopped turn's restored question.
@@ -14995,6 +15139,14 @@ async function main() {
       await runSwitchSkillCommand(line);
       continue;
     }
+    if (line === "/skill-pack" || line.startsWith("/skill-pack ")) {
+      await runSkillPackCommand(line);
+      continue;
+    }
+    if (line === "/skill-install" || line.startsWith("/skill-install ")) {
+      await runSkillInstallCommand(line);
+      continue;
+    }
     if (line === "/skills-copy-to-claude" || line.startsWith("/skills-copy-to-claude ")) {
       await runSkillsCopyCommand(line);
       continue;

package/hooks-config.mjs

@@ -147,7 +147,9 @@ export function cleanHooks(raw, where, source = "gu") {
           ...(Number.isFinite(h.timeout) && h.timeout > 0 ? { timeout: h.timeout } : {}),
           ...(isObj(h.env) ? { env: Object.fromEntries(Object.entries(h.env).map(([k, v]) => [k, String(v)])) } : {}),
         }));
-      if (hs.length) kept.push({ matcher: String(g.matcher ?? ""), hooks: hs });
+      // #281: a group marked dialect "claude" (a packed skill's hook, installed for both tools) is
+      // spoken to in Claude's vocabulary, as if it had come from Claude Code's settings.
+      if (hs.length) kept.push({ matcher: String(g.matcher ?? ""), hooks: hs, ...(g.dialect === "claude" ? { dialect: "claude" } : {}) });
     }
     if (kept.length) hooks[event] = kept;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.884",
+  "version": "1.0.885",
   "description": "gu: the coding agent in your terminal. It reads your repo, makes the change and runs the tests, with your own models (Ollama, MLX or any OpenAI-compatible provider). macOS, Linux and Windows.",
   "keywords": [
     "ai",
@@ -146,6 +146,9 @@
     "skills.mjs",
     "skill-source.mjs",
     "skills-copy.mjs",
+    "skill-package.mjs",
+    "resume-memory.mjs",
+    "skill-install.mjs",
     "shell-details.mjs",
     "proc-identity.mjs",
     "win-path.mjs",

package/resume-memory.mjs

@@ -0,0 +1,85 @@
+/**
+ * gu /resume (#285): where the last unfinished session in this project stopped — Claude Code's or
+ * gu's — read from the session-memory skill's database, so gu can carry on Claude's work.
+ *
+ * The memory skill is found through the hooks this folder uses (its memory_hook.py sits next to
+ * memory_cli.py), so whichever copy is installed — ~/.claude/memory, a /skill-install runtime —
+ * is the one asked. Nothing here writes the database.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const SKILL = "claude-session-memory-orchestration";
+
+/** {python, cli} of the memory skill, or null when it is not installed. */
+export function findMemoryCli({ cwd = process.cwd(), home = homedir(), hooksFor } = {}) {
+  for (const source of [undefined, "claude", "gu"]) {
+    let hooks = {};
+    try {
+      hooks = hooksFor ? hooksFor({ cwd, home, source }) : {};
+    } catch {
+      continue;
+    }
+    for (const groups of Object.values(hooks)) {
+      for (const g of groups ?? []) {
+        for (const h of g.hooks ?? []) {
+          const script = [h.command, ...(h.args ?? [])].find((a) => /memory_hook\.py$/.test(String(a)));
+          if (!script) {continue;}
+          const cli = join(dirname(dirname(String(script))), "memory_cli.py");
+          if (existsSync(cli)) {return { python: String(h.command).endsWith(".py") ? pythonFor(cli) : String(h.command), cli };}
+        }
+      }
+    }
+  }
+  for (const dir of [join(home, ".gonext", "skill-runtime", SKILL), join(home, ".claude", "skill-runtime", SKILL), join(home, ".claude", "memory")]) {
+    const cli = join(dir, "memory_cli.py");
+    if (existsSync(cli)) {return { python: pythonFor(cli), cli };}
+  }
+  return null;
+}
+
+function pythonFor(cli) {
+  const dir = dirname(cli);
+  for (const p of [join(dir, ".venv", "bin", "python"), join(dir, ".venv", "Scripts", "python.exe")]) {if (existsSync(p)) {return p;}}
+  return process.platform === "win32" ? "python" : "python3"; // platform-ok: the venv is preferred above
+}
+
+/** {block, resume} from `memory_cli.py resume --json`, or {error}. */
+export function readResume({ cwd = process.cwd(), found, run = spawnSync } = {}) {
+  if (!found) {return { error: "the memory skill is not installed here — /skill-install claude-session-memory-orchestration.zip" };}
+  const r = run(found.python, [found.cli, "resume", "--json"], { cwd, encoding: "utf8", timeout: 20000 });
+  if (r.error || r.status !== 0) {return { error: `memory_cli resume failed: ${(r.error?.message || r.stderr || "").trim().split("\n").pop()}` };}
+  try {
+    const d = JSON.parse(r.stdout);
+    return { block: d.block || "", resume: d.resume ?? null };
+  } catch {
+    return { error: "memory_cli resume printed something that is not JSON" };
+  }
+}
+
+/** The step to offer: the saved next action, else the first plan step not done. */
+export function nextStepOf(resume) {
+  if (!resume) {return "";}
+  const open = (resume.plan ?? []).find((p) => p.status !== "completed");
+  return String(resume.next_action || open?.text || resume.task?.next_action || "").trim();
+}
+
+/** The question asked before carrying on. */
+export function resumeQuestion(resume) {
+  const step = nextStepOf(resume);
+  const what = resume?.task?.id ? `task #${resume.task.id}` : "this work";
+  return step ? `Continue ${what} from "${step.length > 60 ? step.slice(0, 59) + "…" : step}"?` : `Continue ${what}?`;
+}
+
+/** What the agent is sent on "yes": the block itself, and what to do with it. */
+export function resumePrompt(block, resume) {
+  const step = nextStepOf(resume);
+  return [
+    `Continue the unfinished work below${resume?.task?.id ? ` (task #${resume.task.id})` : ""}. It was saved by the memory skill${resume?.tool === "claude" ? " from a Claude Code session" : ""}.`,
+    step ? `Start from: ${step}. Check the files it lists first; do not redo steps marked ✓.` : "Check the files it lists first; do not redo steps marked ✓.",
+    "",
+    block,
+  ].join("\n");
+}

package/skill-install.mjs

@@ -0,0 +1,563 @@
+#!/usr/bin/env node
+/**
+ * INSTALL A PACKED SKILL (#281) — the other half of /skill-pack (skill-package.mjs).
+ *
+ * This one file is BOTH gu's installer (/skill-install imports it) AND the install.mjs that ships
+ * inside every package, so a machine without gu can still run `node install.mjs`. It must stay
+ * self-contained: Node 18+ built-ins only, no imports from the rest of gu.
+ *
+ * A package (a zip, or the same files unzipped):
+ *   <name>/install.mjs     this file
+ *   <name>/skill.json      the manifest (below)
+ *   <name>/skill/…         the skill's folder: SKILL.md and whatever sits next to it
+ *   <name>/runtime/…       optional — the code its MCP servers and hooks run (lived outside the
+ *                          skill folder on the machine it was packed on)
+ *
+ *   skill.json = { format: 1, name, description, python?: { requirements: "requirements.txt" },
+ *                  mcpServers?: { <server>: { command, args, env } },
+ *                  hooks?: { <Claude event>: [ { matcher, hooks: [ { type, command, args, timeout } ] } ] },
+ *                  env?: [names asked for at install], notes?: [ … ] }
+ *
+ * Paths in the manifest and in the packed text files are placeholders, filled in here:
+ *   {{SKILL}}    the skill's folder (one per tool: ~/.gonext/skills/<name>, ~/.claude/skills/<name>)
+ *   {{RUNTIME}}  <base>/skill-runtime/<name>, <base> = ~/.gonext if gu is a target, else ~/.claude
+ *   {{PYTHON}}   the runtime's own venv python (built here from requirements.txt), else python3
+ *   {{HOME}}     the home folder;  {{ENV:NAME}}  NAME from the terminal's environment (never packed)
+ *
+ * Hooks are written in Claude Code's vocabulary. Claude gets them as they are, in
+ * ~/.claude/settings.json; gu gets them under its own event names with dialect "claude", so gu
+ * speaks Claude's input format to the same script (gu_hooks.py). A hook from an older install of
+ * the same script (same path inside the runtime) is replaced, not doubled.
+ *
+ * Nothing is overwritten without a copy: a skill folder, runtime or settings file that changes is
+ * first copied to <base>/skill-backups/<name>-<time>/. A config file that is not valid JSON is
+ * refused, never "repaired".
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { inflateRawSync } from "node:zlib";
+
+export const FORMAT = 1;
+export const MANIFEST = "skill.json";
+export const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const TARGETS = ["gu", "claude"];
+/** Claude Code's hook events → gu's moments (hooks-config.mjs has the same table). */
+export const CLAUDE_TO_GU = { SessionStart: "onStart", UserPromptSubmit: "onAsk", PostToolUse: "onToolDone", Stop: "onTurnEnd" };
+/** Claude Code events gu has no moment for: installed for Claude Code only (#284). */
+export const CLAUDE_ONLY_EVENTS = ["SessionEnd", "PreCompact"];
+
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const slash = (p) => String(p).replace(/\\/g, "/");
+
+// ---- zip (read) --------------------------------------------------------------------------------
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+export function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** A path inside a package: relative, forward slashes, no "..", nothing absolute. */
+export function safeRel(p) {
+  const s = slash(p).replace(/^\.\//, "");
+  if (!s || s.startsWith("/") || /^[A-Za-z]:/.test(s) || s.split("/").some((x) => x === ".." || x === "")) return null;
+  return s;
+}
+
+/** A zip's files → Map<path, { data, mode }>. Folders are left out; a damaged entry throws. */
+export function readZip(buf) {
+  let end = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) throw new Error("not a zip file");
+  const count = buf.readUInt16LE(end + 10);
+  let at = buf.readUInt32LE(end + 16);
+  const files = new Map();
+  for (let n = 0; n < count; n++) {
+    if (buf.readUInt32LE(at) !== 0x02014b50) throw new Error("the zip's file list is damaged");
+    const method = buf.readUInt16LE(at + 10);
+    const crc = buf.readUInt32LE(at + 16);
+    const size = buf.readUInt32LE(at + 20);
+    const nameLen = buf.readUInt16LE(at + 28);
+    const extraLen = buf.readUInt16LE(at + 30);
+    const commentLen = buf.readUInt16LE(at + 32);
+    const attrs = buf.readUInt32LE(at + 38);
+    const local = buf.readUInt32LE(at + 42);
+    const name = buf.toString("utf8", at + 46, at + 46 + nameLen);
+    at += 46 + nameLen + extraLen + commentLen;
+    if (name.endsWith("/")) continue;
+    const rel = safeRel(name);
+    if (!rel) throw new Error(`the zip has an unsafe path: ${name}`);
+    const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
+    const packed = buf.subarray(start, start + size);
+    const data = method === 8 ? inflateRawSync(packed) : method === 0 ? Buffer.from(packed) : null;
+    if (!data) throw new Error(`${name}: compression method ${method} is not supported`);
+    if (crc32(data) !== crc) throw new Error(`${name} is damaged (CRC mismatch)`);
+    files.set(rel, { data, mode: (attrs >>> 16) & 0o777 });
+  }
+  return files;
+}
+
+function readTree(dir, base = dir, out = new Map()) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) readTree(p, base, out);
+    else if (e.isFile()) out.set(slash(p.slice(base.length + 1)), { data: readFileSync(p), mode: statSync(p).mode & 0o777 });
+  }
+  return out;
+}
+
+// ---- the package -------------------------------------------------------------------------------
+
+/** Check a manifest; → list of problems (empty = fine). */
+export function manifestProblems(m) {
+  const out = [];
+  if (!isObj(m)) return ["skill.json is not a JSON object"];
+  if (m.format !== FORMAT) out.push(`skill.json format ${m.format} — this installer reads format ${FORMAT}`);
+  if (!NAME_RE.test(String(m.name ?? ""))) out.push(`"${m.name}" is not a valid skill name`);
+  if (m.mcpServers !== undefined && !isObj(m.mcpServers)) out.push("mcpServers must be an object");
+  for (const [k, v] of Object.entries(isObj(m.mcpServers) ? m.mcpServers : {})) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(k)) out.push(`MCP server name "${k}" is not valid`);
+    if (!isObj(v) || !String(v.command ?? "").trim()) out.push(`MCP server "${k}" has no command`);
+  }
+  if (m.hooks !== undefined && !isObj(m.hooks)) out.push("hooks must be an object");
+  for (const ev of Object.keys(isObj(m.hooks) ? m.hooks : {})) {
+    if (!(ev in CLAUDE_TO_GU) && !CLAUDE_ONLY_EVENTS.includes(ev)) out.push(`hook event "${ev}" is not one this installer knows (${[...Object.keys(CLAUDE_TO_GU), ...CLAUDE_ONLY_EVENTS].join(", ")})`);
+  }
+  if (m.python !== undefined && !(isObj(m.python) && safeRel(m.python.requirements ?? ""))) out.push("python.requirements must name a file in runtime/");
+  return out;
+}
+
+/**
+ * A package from a zip or a folder → { manifest, skill: Map, runtime: Map }. Accepts the folder
+ * itself or a zip whose files sit under one top folder (as /skill-pack writes them).
+ */
+export function loadPackage(src) {
+  const st = statSync(src);
+  let files = st.isDirectory() ? readTree(src) : readZip(readFileSync(src));
+  if (!files.has(MANIFEST)) {
+    const tops = new Set([...files.keys()].map((k) => k.split("/")[0]));
+    const top = tops.size === 1 ? [...tops][0] : null;
+    if (!top || !files.has(`${top}/${MANIFEST}`)) throw new Error(`no ${MANIFEST} in ${src} — is it a gu skill package?`);
+    files = new Map([...files].map(([k, v]) => [k.slice(top.length + 1), v]));
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(files.get(MANIFEST).data.toString("utf8"));
+  } catch (e) {
+    throw new Error(`${MANIFEST} is not valid JSON (${e.message})`);
+  }
+  const problems = manifestProblems(manifest);
+  if (problems.length) throw new Error(problems.join("; "));
+  const part = (prefix) => new Map([...files].filter(([k]) => k.startsWith(prefix)).map(([k, v]) => [k.slice(prefix.length), v]));
+  const skill = part("skill/");
+  if (!skill.has("SKILL.md")) throw new Error("the package has no skill/SKILL.md");
+  const runtime = part("runtime/");
+  if (manifest.python && !runtime.has(manifest.python.requirements)) throw new Error(`runtime/${manifest.python.requirements} is missing`);
+  return { manifest, skill, runtime };
+}
+
+// ---- placeholders ------------------------------------------------------------------------------
+
+/** Fill {{SKILL}} {{RUNTIME}} {{PYTHON}} {{HOME}} {{ENV:X}} in one string. */
+export function fill(s, vars) {
+  return String(s).replace(/\{\{(SKILL|RUNTIME|PYTHON|HOME|ENV:([A-Za-z_][A-Za-z0-9_]*))\}\}/g, (all, k, env) =>
+    env ? (vars.env?.[env] ?? "") : vars[k.toLowerCase()] ?? all
+  );
+}
+const isText = (buf) => !buf.subarray(0, 8192).includes(0);
+/** Text files get placeholders filled with forward-slash paths (safe inside Python/JS strings on Windows too). */
+function fillFile(f, vars) {
+  if (!isText(f.data)) return f.data;
+  const text = f.data.toString("utf8");
+  if (!text.includes("{{")) return f.data;
+  const v = { ...vars, skill: slash(vars.skill), runtime: slash(vars.runtime), python: slash(vars.python), home: slash(vars.home) };
+  return Buffer.from(fill(text, v), "utf8");
+}
+const fillDeep = (v, vars) =>
+  typeof v === "string" ? fill(v, vars) : Array.isArray(v) ? v.map((x) => fillDeep(x, vars)) : isObj(v) ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, fillDeep(x, vars)])) : v;
+
+/** Every {{ENV:X}} the manifest uses. */
+export function envNames(manifest) {
+  const names = new Set(Array.isArray(manifest.env) ? manifest.env.map(String) : []);
+  for (const m of JSON.stringify(manifest).matchAll(/\{\{ENV:([A-Za-z_][A-Za-z0-9_]*)\}\}/g)) names.add(m[1]);
+  return [...names];
+}
+
+// ---- config files ------------------------------------------------------------------------------
+
+function readJsonFile(file) {
+  if (!existsSync(file)) return { data: {} };
+  try {
+    const data = JSON.parse(readFileSync(file, "utf8") || "{}");
+    return isObj(data) ? { data } : { error: "not a JSON object" };
+  } catch (e) {
+    return { error: `not valid JSON (${e.message})` };
+  }
+}
+function writeJsonFile(file, data) {
+  mkdirSync(dirname(file), { recursive: true });
+  let mode = 0o600;
+  try {
+    mode = statSync(file).mode & 0o777;
+  } catch {
+    /* new file: private */
+  }
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", { encoding: "utf8", mode });
+  renameSync(tmp, file);
+}
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** The path a hook runs, inside its package: "hooks/memory_hook.py" for "{{RUNTIME}}/hooks/memory_hook.py". */
+function hookKey(h) {
+  for (const a of [h.command, ...(Array.isArray(h.args) ? h.args : [])]) {
+    const m = String(a).match(/\{\{(?:RUNTIME|SKILL)\}\}[\\/](.+)$/);
+    if (m) return slash(m[1]);
+  }
+  return null;
+}
+/** Does an installed hook run the same script (by its path inside the runtime/skill)? */
+function runsSame(installed, key) {
+  if (!key) return false;
+  return [installed.command, ...(Array.isArray(installed.args) ? installed.args : [])].some((a) => slash(a).endsWith("/" + key));
+}
+
+/**
+ * Add `groups` under `event` in a hooks object: an installed group running the same script is
+ * replaced (an older install, maybe from another folder); an identical one is left alone.
+ * → { hooks, replaced: [paths], added: n }
+ */
+export function mergeHooks(existing, event, groups, extra = {}) {
+  const hooks = isObj(existing) ? structuredClone(existing) : {};
+  const list = Array.isArray(hooks[event]) ? hooks[event] : [];
+  const replaced = [];
+  let added = 0;
+  for (const g of groups) {
+    const want = { matcher: g.matcher ?? "", hooks: g.hooks, ...extra };
+    if (list.some((x) => sameJson(x, want))) continue;
+    const keys = (g.keys ?? []).filter(Boolean);
+    for (let i = list.length - 1; i >= 0; i--) {
+      const hs = Array.isArray(list[i]?.hooks) ? list[i].hooks : [];
+      if (hs.length && hs.every((h) => keys.some((k) => runsSame(h, k)))) {
+        replaced.push(...hs.map((h) => [h.command, ...(h.args ?? [])].join(" ")));
+        list.splice(i, 1);
+      }
+    }
+    list.push(want);
+    added++;
+  }
+  hooks[event] = list;
+  return { hooks, replaced, added };
+}
+
+// ---- the plan ----------------------------------------------------------------------------------
+
+const venvPython = (dir, platform) => (platform === "win32" ? join(dir, ".venv", "Scripts", "python.exe") : join(dir, ".venv", "bin", "python"));
+
+function sameTree(files, dir, vars) {
+  if (!existsSync(dir)) return false;
+  let have;
+  try {
+    have = readTree(dir);
+  } catch {
+    return false;
+  }
+  for (const [k, f] of files) if (!have.has(k) || !have.get(k).data.equals(fillFile(f, vars))) return false;
+  return true;
+}
+
+/**
+ * What installing `pkg` would do → a plan for applyInstall and for showing the user. `targets`
+ * left out = every tool that is on this machine (its folder exists).
+ */
+export function planInstall(pkg, { home = homedir(), targets, platform = process.platform, env = process.env } = {}) {
+  const { manifest: m } = pkg;
+  const name = m.name;
+  const found = TARGETS.filter((t) => existsSync(join(home, t === "gu" ? ".gonext" : ".claude")));
+  const use = targets?.length ? targets : found;
+  if (!use.length) throw new Error("neither gu (~/.gonext) nor Claude Code (~/.claude) is set up here — pass --gu or --claude");
+  const base = join(home, use.includes("gu") ? ".gonext" : ".claude");
+  const runtime = join(base, "skill-runtime", name);
+  // platform-ok: only for a package whose command is {{PYTHON}} with no venv — "python" on Windows (not the Store stub's name).
+  const python = m.python ? venvPython(runtime, platform) : platform === "win32" ? "python" : "python3";
+  const envValues = {};
+  const missingEnv = [];
+  for (const k of envNames(m)) {
+    if (env[k]) envValues[k] = env[k];
+    else missingEnv.push(k);
+  }
+  const warnings = [];
+  const items = [];
+  const runtimeVars = { skill: join(home, ".gonext", "skills", name), runtime, python, home, env: envValues };
+  const runtimeStatus = !pkg.runtime.size ? "same" : sameTree(pkg.runtime, runtime, runtimeVars) ? "same" : existsSync(runtime) ? "differs" : "new";
+  if (pkg.runtime.size) items.push({ kind: "runtime", to: runtime, status: runtimeStatus, files: pkg.runtime.size });
+  // The venv is (re)built when it is missing or the runtime (so maybe requirements.txt) changed.
+  if (m.python) items.push({ kind: "python", to: runtime, requirements: m.python.requirements, status: runtimeStatus === "same" && existsSync(python) ? "same" : "new" });
+  for (const t of use) {
+    const dot = t === "gu" ? ".gonext" : ".claude";
+    const skillDir = join(home, dot, "skills", name);
+    const vars = { skill: skillDir, runtime, python, home, env: envValues };
+    items.push({ kind: "skill", target: t, to: skillDir, vars, status: sameTree(pkg.skill, skillDir, vars) ? "same" : existsSync(skillDir) ? "differs" : "new" });
+
+    const servers = isObj(m.mcpServers) ? m.mcpServers : {};
+    if (Object.keys(servers).length) {
+      const file = t === "gu" ? join(home, ".gonext", "mcp.json") : join(home, ".claude.json");
+      const cur = readJsonFile(file);
+      if (cur.error) warnings.push(`${file} is ${cur.error} — its MCP servers are left alone`);
+      for (const [sname, entry] of Object.entries(servers)) {
+        const want = fillDeep({ command: entry.command, args: entry.args ?? [], ...(isObj(entry.env) && Object.keys(entry.env).length ? { env: entry.env } : {}) }, vars);
+        if (t === "claude") want.type = "stdio";
+        const have = cur.data?.mcpServers?.[sname];
+        items.push({ kind: "server", target: t, name: sname, file, entry: want, blocked: !!cur.error, status: !have ? "new" : sameJson(have, want) ? "same" : "differs" });
+      }
+    }
+
+    const hookDefs = isObj(m.hooks) ? m.hooks : {};
+    if (Object.keys(hookDefs).length) {
+      const file = join(home, dot, "settings.json");
+      const cur = readJsonFile(file);
+      if (cur.error) warnings.push(`${file} is ${cur.error} — no hooks are added to it`);
+      let hooks = cur.data?.hooks ?? {};
+      const replaced = [];
+      let added = 0;
+      const events = [];
+      for (const [ev, groups] of Object.entries(hookDefs)) {
+        if (t === "gu" && !(ev in CLAUDE_TO_GU)) continue; // a Claude-only event: gu never fires it
+        events.push(ev);
+        const filled = (Array.isArray(groups) ? groups : []).map((g) => ({
+          matcher: g.matcher ?? "",
+          hooks: fillDeep(g.hooks ?? [], vars),
+          keys: (g.hooks ?? []).map(hookKey),
+        }));
+        const r = mergeHooks(hooks, t === "gu" ? CLAUDE_TO_GU[ev] : ev, filled, t === "gu" ? { dialect: "claude" } : {});
+        hooks = r.hooks;
+        replaced.push(...r.replaced);
+        added += r.added;
+      }
+      items.push({ kind: "hooks", target: t, file, hooks, events, replaced, blocked: !!cur.error, status: added ? (replaced.length ? "differs" : "new") : "same" });
+    }
+  }
+  return { name, manifest: m, pkg, home, base, runtime, python, targets: use, items, missingEnv, warnings, notes: Array.isArray(m.notes) ? m.notes.map(String) : [] };
+}
+
+// ---- doing it ----------------------------------------------------------------------------------
+
+function writeFiles(dir, files, vars) {
+  for (const [rel, f] of files) {
+    const p = join(dir, ...rel.split("/"));
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, fillFile(f, vars));
+    if (f.mode & 0o111) chmodSync(p, f.mode | 0o600);
+  }
+}
+function copyTree(from, to, skip = new Set()) {
+  mkdirSync(to, { recursive: true });
+  for (const e of readdirSync(from, { withFileTypes: true })) {
+    if (skip.has(e.name)) continue;
+    const a = join(from, e.name), b = join(to, e.name);
+    if (e.isDirectory()) copyTree(a, b);
+    else if (e.isFile()) copyFileSync(a, b);
+  }
+}
+
+/** A Python 3.9+ on this machine → [command, ...args] or null. Windows' Store stub fails the check. */
+export function findPython({ platform = process.platform, run = spawnSync } = {}) {
+  // platform-ok: this IS the resolver — install.mjs ships alone and cannot import platform-tools.mjs. Each candidate is run and version-checked, so the Store stub fails.
+  const tries = platform === "win32" ? [["py", "-3"], ["python"], ["python3"]] : [["python3"], ["python"]];
+  for (const [cmd, ...args] of tries) {
+    const r = run(cmd, [...args, "-c", "import sys; print('%d.%d' % sys.version_info[:2])"], { encoding: "utf8" });
+    const v = String(r.stdout ?? "").trim().match(/^(\d+)\.(\d+)$/);
+    if (r.status === 0 && v && (+v[1] > 3 || (+v[1] === 3 && +v[2] >= 9))) return [cmd, ...args];
+  }
+  return null;
+}
+
+/**
+ * Carry out a plan. `say(line)` reports progress. → { done: [lines], errors: [lines], backups }.
+ * Order: runtime, its venv, then each tool's skill, MCP servers and hooks. A failed venv stops
+ * before anything points at it.
+ */
+export function applyInstall(plan, { say = () => {}, run = spawnSync, now = new Date() } = {}) {
+  const done = [];
+  const errors = [];
+  const stamp = now.toISOString().replace(/[:.]/g, "-");
+  const backupDir = join(plan.base, "skill-backups", `${plan.name}-${stamp}`);
+  let backedUp = false;
+  const backup = (p, label) => {
+    if (!existsSync(p)) return;
+    const dest = join(backupDir, label);
+    mkdirSync(dirname(dest), { recursive: true });
+    if (statSync(p).isDirectory()) copyTree(p, dest, new Set([".venv", "__pycache__"]));
+    else copyFileSync(p, dest);
+    backedUp = true;
+  };
+
+  for (const it of plan.items) {
+    try {
+      if (it.kind === "runtime" && it.status !== "same") {
+        backup(it.to, "runtime");
+        writeFiles(it.to, plan.pkg.runtime, { skill: join(plan.home, ".gonext", "skills", plan.name), runtime: plan.runtime, python: plan.python, home: plan.home, env: {} });
+        done.push(`runtime → ${it.to}`);
+      } else if (it.kind === "python" && it.status !== "same") {
+        const py = findPython({ run });
+        if (!py) throw new Error("Python 3.9 or newer is needed for this skill and none was found (install it, then run this again)");
+        if (!existsSync(plan.python)) {
+          say(`  making a Python venv in ${join(it.to, ".venv")} …`);
+          const v = run(py[0], [...py.slice(1), "-m", "venv", join(it.to, ".venv")], { encoding: "utf8" });
+          if (v.status !== 0) {
+            const why = String(v.stderr || v.stdout || "").trim().split("\n").pop();
+            throw new Error(`couldn't make the venv: ${why}${process.platform === "linux" ? " (on Ubuntu: sudo apt install python3-venv)" : ""}`);
+          }
+        }
+        say(`  installing ${it.requirements} …`);
+        const p = run(plan.python, ["-m", "pip", "install", "--quiet", "--disable-pip-version-check", "-r", join(it.to, it.requirements)], { encoding: "utf8" });
+        if (p.status !== 0) throw new Error(`pip install failed: ${String(p.stderr || p.stdout || "").trim().split("\n").slice(-2).join(" ")}`);
+        done.push(`Python packages from ${it.requirements}`);
+      } else if (it.kind === "skill" && it.status !== "same") {
+        backup(it.to, `${it.target}-skill`);
+        writeFiles(it.to, plan.pkg.skill, it.vars);
+        done.push(`${it.target}: skill → ${it.to}`);
+      } else if (it.kind === "server" && it.status !== "same" && !it.blocked) {
+        const cur = readJsonFile(it.file);
+        if (cur.error) throw new Error(`${it.file} is ${cur.error}`);
+        if (it.status === "differs") backup(it.file, `${it.target}-${it.file.split(/[\\/]/).pop()}`);
+        const data = cur.data;
+        data.mcpServers = isObj(data.mcpServers) ? data.mcpServers : {};
+        data.mcpServers[it.name] = it.entry;
+        writeJsonFile(it.file, data);
+        done.push(`${it.target}: MCP server ${it.name} → ${it.file}`);
+      } else if (it.kind === "hooks" && it.status !== "same" && !it.blocked) {
+        const cur = readJsonFile(it.file);
+        if (cur.error) throw new Error(`${it.file} is ${cur.error}`);
+        backup(it.file, `${it.target}-settings.json`);
+        writeJsonFile(it.file, { ...cur.data, hooks: it.hooks });
+        done.push(`${it.target}: hooks (${it.events.join(", ")}) → ${it.file}`);
+      }
+    } catch (e) {
+      errors.push(`${it.kind}${it.target ? ` (${it.target})` : ""}: ${e.message}`);
+      if (it.kind === "runtime" || it.kind === "python") break; // the rest would point at a broken runtime
+    }
+  }
+  return { done, errors, backups: backedUp ? backupDir : null };
+}
+
+/** What to do after installing, for the tools that got it. */
+export const nextStep = (plan) =>
+  plan.targets.length === 2 ? "Start a new gu or Claude Code session to use it." : plan.targets[0] === "gu" ? "Start a new gu session (/reset) to use it." : "Start a new Claude Code session to use it.";
+
+/** Would applyInstall change anything? */
+export const planHasWork = (plan) => plan.items.some((i) => i.status && i.status !== "same" && !i.blocked);
+
+// ---- describing a plan (shared by the CLI and gu) ----------------------------------------------
+
+/** The plan as lines of text. `tilde` shortens paths. */
+export function describePlan(plan, tilde = (p) => p) {
+  const word = { new: "new", same: "already there", differs: "replaces what is there (backed up)" };
+  const out = [`${plan.name} — for ${plan.targets.map((t) => (t === "gu" ? "gu" : "Claude Code")).join(" and ")}`];
+  for (const it of plan.items) {
+    if (it.kind === "runtime") out.push(`  runtime (${it.files} files) → ${tilde(it.to)}  ${word[it.status]}`);
+    if (it.kind === "python") out.push(`  Python venv in the runtime, packages from ${it.requirements}  ${it.status === "same" ? word.same : "built here"}`);
+    if (it.kind === "skill") out.push(`  ${it.target}: skill → ${tilde(it.to)}  ${word[it.status]}`);
+    if (it.kind === "server") out.push(`  ${it.target}: MCP server ${it.name} → ${tilde(it.file)}  ${it.blocked ? "SKIPPED (file is broken)" : word[it.status]}`);
+    if (it.kind === "hooks") {
+      out.push(`  ${it.target}: hooks ${it.events.join(", ")} → ${tilde(it.file)}  ${it.blocked ? "SKIPPED (file is broken)" : it.status === "same" ? word.same : "added"}`);
+      for (const r of it.replaced) out.push(`    replaces an older copy: ${tilde(r)}`);
+    }
+  }
+  for (const k of plan.missingEnv) out.push(`  ! ${k} is not set here — set it and install again`);
+  for (const w of plan.warnings) out.push(`  ! ${w}`);
+  for (const n of plan.notes) out.push(`  note: ${n}`);
+  return out;
+}
+
+// ---- run as a script: node install.mjs ---------------------------------------------------------
+
+async function main(argv) {
+  const has = (f) => argv.includes(f);
+  const at = argv.indexOf("--home");
+  const home = at >= 0 ? argv[at + 1] : homedir();
+  const src = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--home") ?? dirname(fileURLToPath(import.meta.url));
+  if (has("--help") || has("-h")) {
+    console.log("node install.mjs [package] [--gu] [--claude] [--home <dir>] [--dry-run] [--yes]\n  Installs a gu skill package. With neither --gu nor --claude, installs for every tool that is set up here.");
+    return 0;
+  }
+  if (Number(process.versions.node.split(".")[0]) < 18) {
+    console.error(`Node.js 18 or newer is needed (this is ${process.version}).`);
+    return 1;
+  }
+  const targets = TARGETS.filter((t) => has(`--${t}`));
+  let plan;
+  try {
+    plan = planInstall(loadPackage(resolve(src)), { home, targets });
+  } catch (e) {
+    console.error(`Not installed: ${e.message}`);
+    return 1;
+  }
+  const tilde = (p) => String(p).split(home).join("~");
+  console.log(describePlan(plan, tilde).join("\n"));
+  const todo = planHasWork(plan);
+  if (!todo) {
+    console.log("\nNothing to do — it is already installed.");
+    return 0;
+  }
+  if (has("--dry-run")) {
+    console.log("\n--dry-run: nothing was written.");
+    return 0;
+  }
+  if (!has("--yes")) {
+    if (!process.stdin.isTTY) {
+      console.error("\nAdd --yes to install without asking.");
+      return 1;
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const a = (await rl.question("\nInstall? [y/N] ")).trim().toLowerCase();
+    rl.close();
+    if (a !== "y" && a !== "yes") {
+      console.log("Cancelled — nothing written.");
+      return 0;
+    }
+  }
+  const r = applyInstall(plan, { say: (l) => console.log(l) });
+  for (const d of r.done) console.log(`✓ ${tilde(d)}`);
+  for (const e of r.errors) console.error(`✗ ${e}`);
+  if (r.backups) console.log(`Old copies: ${tilde(r.backups)}`);
+  if (!r.errors.length) console.log(`Done. ${nextStep(plan)}`);
+  return r.errors.length ? 1 : 0;
+}
+
+/** Run directly (node install.mjs), not imported? Compared as REAL paths: a folder reached
+ * through a symlink (macOS /var → /private/var) must still count, or the installer silently
+ * does nothing. */
+export function isMainModule(argv1, url = import.meta.url) {
+  if (!argv1) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return resolve(p);
+    }
+  };
+  return real(resolve(argv1)) === real(fileURLToPath(url));
+}
+
+if (isMainModule(process.argv[1])) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/skill-package.mjs

@@ -0,0 +1,455 @@
+/**
+ * PACK A SKILL FOR ANOTHER MACHINE (#281) — /skill-pack <name>.
+ *
+ * A skill is often more than its SKILL.md: an MCP server it calls, hooks that run on every turn,
+ * and the code both of those run, which may live outside the skill folder (the session-memory
+ * skill keeps its code in ~/.claude/memory and its venv inside that). This file finds all of it on
+ * this machine and writes one zip that skill-install.mjs (shipped inside as install.mjs) puts back
+ * on any machine, for gu and/or Claude Code.
+ *
+ * What it finds, for the skill folder S (gu's or Claude's, yours or this project's):
+ *   MCP servers  in ~/.gonext/mcp.json and ~/.claude.json whose command/args point inside S or the
+ *                runtime, or that SKILL.md names
+ *   the runtime  R = the folder the skill's outside files share: absolute paths SKILL.md names
+ *                plus the servers' files (or --runtime <dir>). Refused when that is too broad
+ *                (home, ~/.claude, ~/.gonext) or too big
+ *   hooks        in ~/.claude/settings.json and ~/.gonext/settings.json whose files are in S or R
+ *   Python       a command that is R's own venv python becomes {{PYTHON}}; R/requirements.txt is
+ *                then required — the venv itself is never packed, the new machine builds its own
+ *
+ * What it never packs: venvs, node_modules, .git, caches, .env files, databases (.db/.sqlite —
+ * a project's memory stays with the project), .claude-memory folders. MCP server and hook env
+ * values that look secret (by name or shape) become {{ENV:NAME}}, read on the new machine from its
+ * terminal. Every packed text file is scanned for secret shapes; one hit refuses the pack.
+ *
+ * Paths: S → {{SKILL}}, R → {{RUNTIME}}, R's venv python → {{PYTHON}}, then home → {{HOME}}, in
+ * every text file and every server/hook entry. A path still outside all of those is a warning.
+ */
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { deflateRawSync } from "node:zlib";
+import { scanSkillsDir } from "./skills.mjs";
+import { CLAUDE_ONLY_EVENTS, CLAUDE_TO_GU, crc32, FORMAT, MANIFEST, manifestProblems } from "./skill-install.mjs";
+
+export const LIMITS = { files: 2000, bytes: 25 * 1024 * 1024 };
+const SKIP_DIRS = new Set([".venv", "venv", "env", "node_modules", ".git", "__pycache__", ".claude-memory", ".pytest_cache", ".mypy_cache", ".ruff_cache"]);
+const SKIP_FILE = (n) => n === ".DS_Store" || /\.(pyc|pyo|db|sqlite3?|db-wal|db-shm|db-journal|log)$/i.test(n) || n === ".env" || n.startsWith(".env.");
+// platform-ok: names recognised in a packed command, never run here.
+const INTERPRETERS = new Set(["node", "python", "python3", "npx", "uv", "uvx", "bun", "deno", "bash", "sh", "pwsh", "powershell"]);
+const GU_TO_CLAUDE = Object.fromEntries(Object.entries(CLAUDE_TO_GU).map(([c, g]) => [g, c]));
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** Secret shapes (a subset of api/scripts/scan-bundle.mjs plus the common API-key forms). */
+export const SECRET_SHAPES = [
+  { kind: "a private key (PEM)", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+  { kind: "an AWS access key id", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, unless: (m) => /0{5,}|EXAMPLE/.test(m) },
+  { kind: "a signed gu token", re: /\bgu1\.[A-Za-z0-9_-]{40,}\.[A-Za-z0-9_-]{40,}/g },
+  { kind: "an API key (sk-…)", re: /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{24,}/g },
+  { kind: "a GitHub token", re: /\bgh[pousr]_[A-Za-z0-9]{30,}/g },
+  { kind: "a Slack token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}/g },
+  { kind: "a Google API key", re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  {
+    kind: "a database address with a password",
+    re: /\b(?:mongodb(?:\+srv)?|postgres(?:ql)?|mysql|redis):\/\/[^\s"'`/:@${}]+:[^\s"'`@${}]+@[^\s"'`/]+/g,
+    unless: (m) => /@(127\.0\.0\.1|localhost|host|example\.com|\[::1\])(:|\/|$)/.test(m),
+  },
+];
+/** Findings in one text → [{ line, kind }], never the value. */
+export function scanSecrets(text) {
+  const t = String(text ?? "");
+  const out = [];
+  for (const s of SECRET_SHAPES) {
+    for (const m of t.matchAll(s.re)) {
+      if (s.unless?.(m[0])) continue;
+      out.push({ line: t.slice(0, m.index).split("\n").length, kind: s.kind });
+    }
+  }
+  return out;
+}
+const SECRET_NAME = /KEY|TOKEN|SECRET|PASS|AUTH|CRED|PRIVATE|COOKIE|SESSION/i;
+
+// ---- reading this machine ----------------------------------------------------------------------
+
+function readJson(file) {
+  try {
+    const d = JSON.parse(readFileSync(file, "utf8"));
+    return isObj(d) ? d : {};
+  } catch {
+    return {};
+  }
+}
+const inside = (p, dir) => {
+  const a = resolve(p), b = resolve(dir);
+  return a === b || a.startsWith(b.endsWith(sep) ? b : b + sep);
+};
+const isText = (buf) => !buf.subarray(0, 8192).includes(0);
+const expand = (p, home) => (p.startsWith("~/") || p === "~" ? join(home, p.slice(2)) : p);
+
+/** Every file under dir that is packed → { files: Map<rel, {data, mode}>, skipped: [rel] }. */
+export function packTree(dir) {
+  const files = new Map();
+  const skipped = [];
+  let bytes = 0;
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      const rel = p.slice(dir.length + 1).split(sep).join("/");
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) skipped.push(rel + "/");
+        else walk(p);
+      } else if (e.isFile()) {
+        if (SKIP_FILE(e.name)) {
+          if (e.name !== ".DS_Store" && !e.name.endsWith(".pyc")) skipped.push(rel);
+          continue;
+        }
+        const st = statSync(p);
+        bytes += st.size;
+        if (files.size >= LIMITS.files || bytes > LIMITS.bytes) {
+          throw new Error(`${dir} is too big to pack (over ${LIMITS.files} files or ${LIMITS.bytes / 1024 / 1024} MB)`);
+        }
+        files.set(rel, { data: readFileSync(p), mode: st.mode & 0o777 });
+      }
+    }
+  };
+  walk(dir);
+  return { files, skipped };
+}
+
+/** The skill named `name` → { name, dir, source, scope } | null. This project's first, then yours; gu's, then Claude's. */
+export function findSkill(name, { cwd = process.cwd(), home = homedir() } = {}) {
+  const want = String(name).replace(/^\//, "");
+  const dirs = [];
+  for (const source of ["gu", "claude"]) {
+    const dot = source === "gu" ? ".gonext" : ".claude";
+    if (cwd && resolve(cwd) !== resolve(home)) dirs.push({ dir: join(cwd, dot, "skills"), source, scope: "project" });
+    dirs.push({ dir: join(home, dot, "skills"), source, scope: "user" });
+  }
+  for (const d of dirs) {
+    const hit = scanSkillsDir(d.dir, d.scope).skills.find((s) => s.name === want || s.dir.split(/[\\/]/).pop() === want);
+    if (hit) return { name: hit.name, description: hit.description, dir: hit.dir, source: d.source, scope: d.scope };
+  }
+  return null;
+}
+
+/** Absolute paths that exist, named in a text (/abs/…, ~/…, C:\…). */
+export function pathsIn(text, home) {
+  const out = new Set();
+  const re = /(?:~\/|\/(?:Users|home|opt|usr|var|srv|root)\/|[A-Za-z]:\\)[^\s"'`)<>\]|,;]*/g;
+  for (const m of String(text).matchAll(re)) {
+    let p = expand(m[0].replace(/[.:]+$/, ""), home);
+    // Walk up to the longest prefix that exists (a doc may name a file that is made later).
+    while (p && !existsSync(p) && dirname(p) !== p) p = dirname(p);
+    if (p && existsSync(p) && isAbsolute(p)) out.add(resolve(p));
+  }
+  return [...out];
+}
+
+function commonDir(paths) {
+  if (!paths.length) return null;
+  let parts = resolve(paths[0]).split(sep);
+  for (const p of paths.slice(1)) {
+    const q = resolve(p).split(sep);
+    let i = 0;
+    while (i < parts.length && i < q.length && parts[i] === q[i]) i++;
+    parts = parts.slice(0, i);
+  }
+  return parts.join(sep) || sep;
+}
+
+/** Is this folder too broad to be one skill's runtime? */
+function tooBroad(dir, home) {
+  const d = resolve(dir);
+  return [home, join(home, ".claude"), join(home, ".gonext"), join(home, ".config"), dirname(home), sep].some((x) => resolve(x) === d) || inside(home, d);
+}
+
+const refsOf = (entry, home) =>
+  [entry.command, ...(Array.isArray(entry.args) ? entry.args : [])]
+    .map((a) => String(a ?? ""))
+    .filter((a) => isAbsolute(a) || a.startsWith("~/"))
+    .map((a) => resolve(expand(a, home)));
+
+// ---- the plan ----------------------------------------------------------------------------------
+
+/**
+ * Everything /skill-pack would write → { manifest, skill, runtime, found, warnings, secrets, skipped }.
+ * Throws when the skill is missing or the runtime cannot be told apart from your home folder.
+ */
+export function planSkillPack(name, { cwd = process.cwd(), home = homedir(), runtime: runtimeOpt, platform = process.platform } = {}) {
+  const sk = findSkill(name, { cwd, home });
+  if (!sk) throw new Error(`no skill named "${name}" in ./.gonext/skills, ~/.gonext/skills, ./.claude/skills or ~/.claude/skills`);
+  const warnings = [];
+  const skillTree = packTree(sk.dir);
+  const md = skillTree.files.get("SKILL.md").data.toString("utf8");
+
+  // MCP servers everywhere this machine keeps them.
+  const servers = [];
+  const guMcp = readJson(join(home, ".gonext", "mcp.json"));
+  const claude = readJson(join(home, ".claude.json"));
+  const proj = isObj(claude.projects) ? claude.projects[resolve(cwd)] : null;
+  for (const [where, obj] of [["~/.gonext/mcp.json", guMcp.mcpServers], ["~/.claude.json", claude.mcpServers], ["~/.claude.json (this folder)", proj?.mcpServers], ["./.mcp.json", readJson(join(cwd, ".mcp.json")).mcpServers]]) {
+    for (const [n, e] of Object.entries(isObj(obj) ? obj : {})) if (isObj(e) && e.command) servers.push({ name: n, entry: e, where });
+  }
+  const named = (n) => new RegExp(`(^|[^A-Za-z0-9_-])${n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^A-Za-z0-9_-]|$)`).test(md);
+
+  // The runtime: what the skill's outside files have in common.
+  const mdPaths = pathsIn(md, home).filter((p) => !inside(p, sk.dir));
+  const firstServers = servers.filter((s) => refsOf(s.entry, home).some((p) => inside(p, sk.dir)) || named(s.name));
+  let runtime = runtimeOpt ? resolve(expand(runtimeOpt, home)) : null;
+  if (!runtime) {
+    const outside = [...mdPaths, ...firstServers.flatMap((s) => refsOf(s.entry, home).filter((p) => existsSync(p) && !inside(p, sk.dir)))];
+    const dirs = outside.map((p) => (statSync(p).isDirectory() ? p : dirname(p)));
+    // A venv's python names its runtime by where the venv sits, not by bin/.
+    const roots = dirs.map((d) => d.replace(new RegExp(`[\\\\/](?:\\.venv|venv)[\\\\/](?:bin|Scripts)$`), ""));
+    runtime = commonDir(roots);
+  }
+  if (runtime && !existsSync(runtime)) throw new Error(`--runtime ${runtime} does not exist`);
+  if (runtime && tooBroad(runtime, home)) {
+    throw new Error(`the skill's outside files only have ${runtime} in common — too broad to pack. Point at the right folder: /skill-pack ${sk.name} --runtime <dir>`);
+  }
+  if (runtime && inside(runtime, sk.dir)) runtime = null; // all inside the skill folder: nothing extra
+
+  const linked = (entry) => refsOf(entry, home).some((p) => inside(p, sk.dir) || (runtime && inside(p, runtime)));
+  const useServers = servers.filter((s) => linked(s.entry) || named(s.name));
+  const dup = new Map();
+  for (const s of useServers) {
+    if (dup.has(s.name) && JSON.stringify(dup.get(s.name).entry) !== JSON.stringify(s.entry)) warnings.push(`MCP server ${s.name} is set up differently in ${dup.get(s.name).where} and ${s.where} — packed the one in ${dup.get(s.name).where}`);
+    if (!dup.has(s.name)) dup.set(s.name, s);
+  }
+  // A server SKILL.md names that is set up nowhere here: say so, never invent one.
+  for (const m of md.matchAll(/`([a-z0-9][a-z0-9_-]{2,63})`\s+MCP server|MCP server\s+`([a-z0-9][a-z0-9_-]{2,63})`/gi)) {
+    const n = m[1] || m[2];
+    if (!dup.has(n)) warnings.push(`SKILL.md names the MCP server "${n}", which is not set up on this machine — it is not in the package`);
+  }
+
+  // Hooks: Claude's settings (Claude vocabulary) and gu's (gu vocabulary, or dialect "claude").
+  const hooks = {};
+  const hookFrom = [];
+  const addHook = (claudeEvent, group, where) => {
+    const hs = (Array.isArray(group.hooks) ? group.hooks : []).filter((h) => isObj(h) && (h.type ?? "command") === "command" && h.command);
+    if (!hs.length || !hs.every((h) => linked(h))) return;
+    const g = { matcher: String(group.matcher ?? ""), hooks: hs.map((h) => ({ type: "command", command: h.command, ...(h.args ? { args: h.args } : {}), ...(h.timeout ? { timeout: h.timeout } : {}), ...(isObj(h.env) ? { env: h.env } : {}) })) };
+    const list = (hooks[claudeEvent] ??= []);
+    if (!list.some((x) => JSON.stringify(x) === JSON.stringify(g))) {
+      list.push(g);
+      hookFrom.push(`${claudeEvent} (${where})`);
+    }
+  };
+  const claudeSettings = readJson(join(home, ".claude", "settings.json"));
+  for (const [ev, groups] of Object.entries(isObj(claudeSettings.hooks) ? claudeSettings.hooks : {})) {
+    if (!(ev in CLAUDE_TO_GU) && !CLAUDE_ONLY_EVENTS.includes(ev)) {
+      if ((Array.isArray(groups) ? groups : []).some((g) => (g.hooks ?? []).some((h) => linked(h)))) warnings.push(`a ${ev} hook belongs to this skill, but no installer handles ${ev} — not packed`);
+      continue;
+    }
+    for (const g of Array.isArray(groups) ? groups : []) addHook(ev, g, "Claude Code");
+  }
+  const guSettings = readJson(join(home, ".gonext", "settings.json"));
+  for (const [ev, groups] of Object.entries(isObj(guSettings.hooks) ? guSettings.hooks : {})) {
+    for (const g of Array.isArray(groups) ? groups : []) {
+      if (!GU_TO_CLAUDE[ev]) continue;
+      if (g.dialect !== "claude") {
+        if ((g.hooks ?? []).some((h) => linked(h))) warnings.push(`gu's ${ev} hook for this skill speaks gu's own input format — not packed (only Claude-format hooks run in both tools)`);
+        continue;
+      }
+      addHook(GU_TO_CLAUDE[ev], g, "gu");
+    }
+  }
+
+  // Python: a command that is the runtime's own venv python.
+  let python = null;
+  let venvPy = null;
+  const isVenvPy = (c) => runtime && inside(c, runtime) && /[\\/](?:\.venv|venv)[\\/](?:bin[\\/]python[0-9.]*|Scripts[\\/]python(?:\.exe)?)$/.test(c);
+  for (const e of [...[...dup.values()].map((s) => s.entry), ...Object.values(hooks).flat().flatMap((g) => g.hooks)]) {
+    const c = String(e.command);
+    if (isAbsolute(c) && isVenvPy(c)) venvPy = c;
+  }
+  const runtimeTree = runtime ? packTree(runtime) : { files: new Map(), skipped: [] };
+  if (venvPy) {
+    if (!runtimeTree.files.has("requirements.txt")) throw new Error(`${venvPy} is a venv, but ${runtime} has no requirements.txt to rebuild it from — add one (pip freeze > requirements.txt) and pack again`);
+    python = { requirements: "requirements.txt" };
+  }
+
+  // Path → placeholder, longest first.
+  const subs = [];
+  const addSub = (from, to) => {
+    if (!from) return;
+    subs.push([from, to]);
+    if (from.startsWith(home + sep)) subs.push(["~" + from.slice(home.length).split(sep).join("/"), to]);
+  };
+  if (venvPy) addSub(venvPy, "{{PYTHON}}");
+  addSub(sk.dir, "{{SKILL}}");
+  if (runtime) addSub(runtime, "{{RUNTIME}}");
+  subs.push([home, "{{HOME}}"]);
+  subs.sort((a, b) => b[0].length - a[0].length);
+  const rewrite = (s) => {
+    let t = String(s);
+    for (const [from, to] of subs) t = t.split(from).join(to);
+    return t;
+  };
+  const env = new Set();
+  const cleanEntry = (e, label) => {
+    let command = String(e.command);
+    if (isAbsolute(command) && !(runtime && inside(command, runtime)) && !inside(command, sk.dir)) {
+      const base = command.split(/[\\/]/).pop().replace(/\.exe$/i, "");
+      if (INTERPRETERS.has(base.replace(/[0-9.]+$/, "")) || INTERPRETERS.has(base)) command = base;
+      else warnings.push(`${label} runs ${command}, which the other machine may not have`);
+    }
+    const out = { command: rewrite(command), args: (Array.isArray(e.args) ? e.args : []).map((a) => rewrite(a)) };
+    if (isObj(e.env)) {
+      out.env = {};
+      for (const [k, v] of Object.entries(e.env)) {
+        if (SECRET_NAME.test(k) || scanSecrets(String(v)).length) {
+          out.env[k] = `{{ENV:${k}}}`;
+          env.add(k);
+        } else out.env[k] = rewrite(v);
+      }
+    }
+    for (const a of [out.command, ...out.args]) {
+      if ((isAbsolute(a) || a.startsWith("~/")) && !a.startsWith("{{")) warnings.push(`${label} names ${a}, which is outside the skill and its runtime — it may not exist on the other machine`);
+    }
+    return out;
+  };
+  const mcpServers = Object.fromEntries([...dup.values()].map((s) => [s.name, cleanEntry(s.entry, `MCP server ${s.name}`)]));
+  const outHooks = Object.fromEntries(
+    Object.entries(hooks).map(([ev, groups]) => [ev, groups.map((g) => ({ matcher: g.matcher, hooks: g.hooks.map((h) => ({ type: "command", ...cleanEntry(h, `the ${ev} hook`), ...(h.timeout ? { timeout: h.timeout } : {}) })) }))])
+  );
+
+  // Rewrite and scan every text file.
+  const secrets = [];
+  const finish = (tree, prefix) => {
+    const out = new Map();
+    for (const [rel, f] of tree.files) {
+      if (!isText(f.data)) {
+        out.set(rel, f);
+        continue;
+      }
+      const text = rewrite(f.data.toString("utf8"));
+      for (const s of scanSecrets(text)) secrets.push({ file: `${prefix}/${rel}`, ...s });
+      out.set(rel, { data: Buffer.from(text, "utf8"), mode: f.mode });
+    }
+    return out;
+  };
+  const skill = finish(skillTree, "skill");
+  const runtimeFiles = finish(runtimeTree, "runtime");
+
+  const manifest = {
+    format: FORMAT,
+    name: sk.name,
+    description: sk.description,
+    packedAt: new Date().toISOString().slice(0, 10),
+    from: sk.source === "gu" ? "gu" : "Claude Code",
+    ...(python ? { python } : {}),
+    ...(Object.keys(mcpServers).length ? { mcpServers } : {}),
+    ...(Object.keys(outHooks).length ? { hooks: outHooks } : {}),
+    ...(env.size ? { env: [...env] } : {}),
+  };
+  const problems = manifestProblems(manifest);
+  if (problems.length) throw new Error(problems.join("; "));
+  return {
+    manifest,
+    skill,
+    runtime: runtimeFiles,
+    found: { skillDir: sk.dir, source: sk.source, scope: sk.scope, runtimeDir: runtime, servers: [...dup.values()].map((s) => `${s.name} (${s.where})`), hooks: hookFrom, python: !!python },
+    warnings: [...new Set(warnings)],
+    secrets,
+    skipped: [...skillTree.skipped.map((s) => `skill/${s}`), ...runtimeTree.skipped.map((s) => `runtime/${s}`)],
+  };
+}
+
+// ---- the zip -----------------------------------------------------------------------------------
+
+const DOS_TIME = 0; // 00:00:00
+const DOS_DATE = ((2026 - 1980) << 9) | (1 << 5) | 1; // fixed: the same skill packs to the same bytes
+
+/** Map<path, {data, mode}> → zip bytes (deflated; unix modes kept). */
+export function writeZip(files) {
+  const locals = [];
+  const central = [];
+  let offset = 0;
+  for (const [name, f] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    const nameBuf = Buffer.from(name, "utf8");
+    const packed = deflateRawSync(f.data, { level: 9 });
+    const crc = crc32(f.data);
+    const h = Buffer.alloc(30);
+    h.writeUInt32LE(0x04034b50, 0);
+    h.writeUInt16LE(20, 4);
+    h.writeUInt16LE(0x0800, 6); // utf-8 names
+    h.writeUInt16LE(8, 8);
+    h.writeUInt16LE(DOS_TIME, 10);
+    h.writeUInt16LE(DOS_DATE, 12);
+    h.writeUInt32LE(crc, 14);
+    h.writeUInt32LE(packed.length, 18);
+    h.writeUInt32LE(f.data.length, 22);
+    h.writeUInt16LE(nameBuf.length, 26);
+    locals.push(h, nameBuf, packed);
+    const c = Buffer.alloc(46);
+    c.writeUInt32LE(0x02014b50, 0);
+    c.writeUInt16LE((3 << 8) | 20, 4); // made on unix: external attrs carry the mode
+    c.writeUInt16LE(20, 6);
+    c.writeUInt16LE(0x0800, 8);
+    c.writeUInt16LE(8, 10);
+    c.writeUInt16LE(DOS_TIME, 12);
+    c.writeUInt16LE(DOS_DATE, 14);
+    c.writeUInt32LE(crc, 16);
+    c.writeUInt32LE(packed.length, 20);
+    c.writeUInt32LE(f.data.length, 24);
+    c.writeUInt16LE(nameBuf.length, 28);
+    c.writeUInt32LE((((f.mode || 0o644) | 0o100000) << 16) >>> 0, 38);
+    c.writeUInt32LE(offset, 42);
+    central.push(c, nameBuf);
+    offset += 30 + nameBuf.length + packed.length;
+  }
+  const cd = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(files.size, 8);
+  end.writeUInt16LE(files.size, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+/** A zip entry's name: "/" always, whatever this machine uses (the zip format says so). */
+const zipPath = (...parts) => parts.join("/");
+
+/** The README that rides in the zip. */
+export function readmeFor(manifest) {
+  const n = manifest.name;
+  return [
+    `${n} — a skill packed by gu`,
+    "",
+    manifest.description,
+    "",
+    "Install (Node.js 18+; Python 3.9+ too if the skill uses Python):",
+    `  in gu:            /skill-install ${n}.zip`,
+    `  without gu:       unzip ${n}.zip && node ${zipPath(n, "install.mjs")}`,
+    "",
+    "It installs for gu (~/.gonext) and Claude Code (~/.claude), whichever is set up on the machine;",
+    "--gu or --claude picks one, --dry-run shows the plan without writing anything.",
+    ...(manifest.env?.length ? ["", `Set these in the terminal first (they were not packed): ${manifest.env.join(", ")}`] : []),
+    "",
+  ].join("\n");
+}
+
+/** The whole package as zip entries under one top folder. */
+export function packageFiles(plan) {
+  const n = plan.manifest.name;
+  const files = new Map();
+  const installer = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "skill-install.mjs"));
+  files.set(zipPath(n, "install.mjs"), { data: installer, mode: 0o755 });
+  files.set(zipPath(n, MANIFEST), { data: Buffer.from(JSON.stringify(plan.manifest, null, 2) + "\n"), mode: 0o644 });
+  files.set(zipPath(n, "README.txt"), { data: Buffer.from(readmeFor(plan.manifest)), mode: 0o644 });
+  for (const [rel, f] of plan.skill) files.set(zipPath(n, "skill", rel), f);
+  for (const [rel, f] of plan.runtime) files.set(zipPath(n, "runtime", rel), f);
+  return files;
+}
+
+/** Write the zip → { file, bytes, count }. Refuses while the plan has secret findings. */
+export function writeSkillPack(plan, outFile) {
+  if (plan.secrets.length) throw new Error(`secret-looking text in ${plan.secrets.map((s) => `${s.file}:${s.line}`).join(", ")} — remove it and pack again`);
+  const files = packageFiles(plan);
+  const zip = writeZip(files);
+  writeFileSync(outFile, zip);
+  return { file: outFile, bytes: zip.length, count: files.size };
+}