@foldspace_npm/harness 0.1.30 → 0.1.32

package/src/init.mjs

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
@@ -299,13 +300,11 @@ function createTemplateValues(config, harnessVersion) {
     throw new Error("Display name must be a non-empty single line and cannot contain '{{'.");
   }
 
-  const packageName = toPackageName(displayName);
-  if (!packageName) {
-    throw new Error("Display name must contain at least one letter or number.");
-  }
-
   const productId = validateProductId(config.productId);
   const agentApiName = validateIdentifier(config.agentApiName, "Agent Key");
+  // A name in another alphabet, such as a folder the human named, has no
+  // letters a package name can use; the Agent Key always has.
+  const packageName = toPackageName(displayName) || toPackageName(agentApiName);
   const region = parseRegion(config.region || DEFAULT_REGION);
   const target = normalizeTarget(config.domain);
   const hosts =
@@ -362,14 +361,17 @@ function copyTemplate(templateRoot, targetRoot, values) {
       const sourcePath = path.join(templateRoot, relativePath);
       // npm excludes .gitignore files from package tarballs, so the bundled
       // template uses a publish-safe name and restores it during generation.
-      // The permission allowlist lives in .claude/, kept flat here for the
-      // same reason.
+      // The permission allowlist and the skills live in .claude/, kept flat
+      // here for the same reason - and so a session working on the harness
+      // itself does not pick the skills up as its own.
       const outputPath =
         relativePath === "gitignore"
           ? ".gitignore"
           : relativePath === "claude-settings.json"
             ? path.join(".claude", "settings.json")
-            : relativePath;
+            : relativePath === "skills" || relativePath.startsWith(`skills${path.sep}`)
+              ? path.join(".claude", relativePath)
+              : relativePath;
       const targetPath = path.join(targetRoot, outputPath);
       assertInside(targetRoot, targetPath);
 
@@ -401,10 +403,147 @@ function validateGeneratedProject(projectDir) {
   }
 }
 
+// What a folder the human made for their agent may already hold: files the
+// system, an editor or Claude Code put there. The template writes none of them
+// except .claude/settings.json, and init leaves each one as it is.
+const ignorableFiles = new Set([".ds_store", ".localized", "icon\r", "thumbs.db", "desktop.ini", ".mcp.json"]);
+const ignorableDirectories = new Set([".claude", ".git", ".vscode", ".cursor", ".idea"]);
+
+function isIgnorableEntry(entry) {
+  const name = entry.name.toLowerCase();
+  if (entry.isDirectory()) {
+    return ignorableDirectories.has(name);
+  }
+  // A .git file, not a folder, belongs to another repository's worktree or
+  // submodule, so it is not ignorable.
+  return entry.isFile() && (ignorableFiles.has(name) || name.startsWith("._"));
+}
+
+// What stops init from filling an existing folder; an empty list means nothing.
+function existingTargetBlockers(targetDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(targetDir, { withFileTypes: true });
+  } catch (error) {
+    throw new Error(`Refusing to set up a project in ${targetDir}: it cannot be read (${error.code || error.message}).`);
+  }
+  const blockers = entries
+    .filter((entry) => !isIgnorableEntry(entry))
+    .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
+    .sort((a, b) => a.localeCompare(b));
+  // The one template file that lands inside an ignorable folder. lstat, so a
+  // link there counts even when what it points to is missing.
+  if (fs.lstatSync(path.join(targetDir, ".claude", "settings.json"), { throwIfNoEntry: false })) {
+    blockers.push(path.join(".claude", "settings.json"));
+  }
+  return blockers;
+}
+
+function realPath(target) {
+  try {
+    return fs.realpathSync(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+// Folders init never fills, even empty: the home folder and its own Desktop,
+// Documents and Downloads, the disk's root, the folders Claude Code
+// Desktop makes for a session started with no folder, which the human cannot
+// find again, and Codex's folder for chats with no project
+// (~/Documents/Codex) and each chat's own folder in it.
+function personalFolderReason(targetDir) {
+  const target = realPath(targetDir);
+  const home = realPath(os.homedir());
+  if (path.dirname(target) === target) {
+    return "it is the disk's root";
+  }
+  if (target === home) {
+    return "it is the home folder";
+  }
+  if (path.dirname(target) === home && ["desktop", "documents", "downloads"].includes(path.basename(target).toLowerCase())) {
+    return `it is the home folder's ${path.basename(target)}`;
+  }
+  if (target.split(path.sep).includes("scratch-workspaces")) {
+    return "it is a temporary session folder";
+  }
+  const codexChats = path.join(home, "documents", "codex");
+  const lower = target.toLowerCase();
+  if (lower === codexChats.toLowerCase() || path.dirname(lower) === codexChats.toLowerCase()) {
+    return "it is Codex's folder for chats with no project; make the agent's folder next to the chat's, in ~/Documents/Codex";
+  }
+  return null;
+}
+
+function assertFillableTarget(targetDir) {
+  if (!fs.statSync(targetDir).isDirectory()) {
+    throw new Error(`Refusing to overwrite existing path: ${targetDir}`);
+  }
+  if (fs.existsSync(path.join(targetDir, "foldspace.dev.json"))) {
+    throw new Error(`${targetDir} is already a Foldspace project. Open it instead of running init.`);
+  }
+  const reason = personalFolderReason(targetDir);
+  if (reason) {
+    throw new Error(`Refusing to set up a project in ${targetDir}: ${reason}. Pass a new folder instead.`);
+  }
+  const blockers = existingTargetBlockers(targetDir);
+  if (blockers.length > 0) {
+    const shown = blockers.slice(0, 5).join(", ") + (blockers.length > 5 ? `, and ${blockers.length - 5} more` : "");
+    throw new Error(
+      `Refusing to set up a project in ${targetDir}: it already holds ${shown}. ` +
+        "init sets up a new folder, or one that holds nothing but files the system or an editor put there.",
+    );
+  }
+}
+
+// Fill an existing folder without replacing it, so a session working in it
+// stays in the same folder. A file that is already there is never
+// overwritten, and on any error everything this call created is removed.
+// foldspace.dev.json goes in last: init and the playbook take it to mean a
+// finished project, so a fill that is cut short never looks like one.
+function copyIntoExisting(sourceRoot, targetRoot) {
+  const created = [];
+  const lastAtRoot = (entries, relativeDir) =>
+    relativeDir === ""
+      ? [...entries.filter((entry) => entry.name !== "foldspace.dev.json"), ...entries.filter((entry) => entry.name === "foldspace.dev.json")]
+      : entries;
+  const walk = (relativeDir) => {
+    for (const entry of lastAtRoot(fs.readdirSync(path.join(sourceRoot, relativeDir), { withFileTypes: true }), relativeDir)) {
+      const relativePath = path.join(relativeDir, entry.name);
+      const sourcePath = path.join(sourceRoot, relativePath);
+      const targetPath = path.join(targetRoot, relativePath);
+      if (entry.isDirectory()) {
+        try {
+          fs.mkdirSync(targetPath);
+          created.push(targetPath);
+        } catch (error) {
+          // .claude/ is the one template folder the human's folder may hold.
+          if (error?.code !== "EEXIST" || relativePath !== ".claude") {
+            throw error;
+          }
+        }
+        walk(relativePath);
+        continue;
+      }
+      fs.copyFileSync(sourcePath, targetPath, fs.constants.COPYFILE_EXCL);
+      created.push(targetPath);
+    }
+  };
+  try {
+    walk("");
+  } catch (error) {
+    for (const createdPath of created.reverse()) {
+      fs.rmSync(createdPath, { recursive: true, force: true });
+    }
+    throw error;
+  }
+}
+
 export function scaffoldProject(config, options = {}) {
   const targetDir = config.targetDir;
-  if (fs.existsSync(targetDir)) {
-    throw new Error(`Refusing to overwrite existing path: ${targetDir}`);
+  const inPlace = fs.existsSync(targetDir);
+  if (inPlace) {
+    assertFillableTarget(targetDir);
   }
 
   const templateRoot = options.templateRoot || defaultTemplateRoot;
@@ -414,17 +553,29 @@ export function scaffoldProject(config, options = {}) {
 
   const harnessVersion = options.harnessVersion || readHarnessVersion(options.packageRoot || packageRoot);
   const values = createTemplateValues(config, harnessVersion);
+  // A new folder is rendered next to where it goes, so it can be renamed into
+  // place in one step. Filling a folder copies file by file, so it renders in
+  // the system's temporary folder and leaves nothing beside the human's folder.
   const parentDir = path.dirname(targetDir);
   fs.mkdirSync(parentDir, { recursive: true });
-  const temporaryDir = fs.mkdtempSync(path.join(parentDir, `.${path.basename(targetDir)}.foldspace-init-`));
+  const temporaryDir = fs.mkdtempSync(
+    path.join(inPlace ? os.tmpdir() : parentDir, `.${path.basename(targetDir)}.foldspace-init-`),
+  );
 
   try {
     copyTemplate(templateRoot, temporaryDir, values);
     validateGeneratedProject(temporaryDir);
-    if (fs.existsSync(targetDir)) {
-      throw new Error(`Target path appeared while initializing: ${targetDir}`);
+    if (inPlace) {
+      // Checked again: something may have landed there while rendering.
+      assertFillableTarget(targetDir);
+      copyIntoExisting(temporaryDir, targetDir);
+      fs.rmSync(temporaryDir, { recursive: true, force: true });
+    } else {
+      if (fs.existsSync(targetDir)) {
+        throw new Error(`Target path appeared while initializing: ${targetDir}`);
+      }
+      fs.renameSync(temporaryDir, targetDir);
     }
-    fs.renameSync(temporaryDir, targetDir);
   } catch (error) {
     fs.rmSync(temporaryDir, { recursive: true, force: true });
     throw error;
@@ -434,6 +585,7 @@ export function scaffoldProject(config, options = {}) {
     targetDir,
     packageName: values.PACKAGE_NAME,
     harnessVersion,
+    inPlace,
   };
 }
 
@@ -496,11 +648,13 @@ export async function runInit(argv, options = {}) {
   const log = options.log || console.log;
   const installed = await maybeInstallDependencies(result.targetDir, options);
 
-  log(`Created Foldspace project at ${result.targetDir}`);
+  log(`${result.inPlace ? "Set up Foldspace project in" : "Created Foldspace project at"} ${result.targetDir}`);
   log(`Using @foldspace_npm/harness ${result.harnessVersion}`);
   log("");
   log("Next steps:");
-  log(`  cd ${result.targetDir}`);
+  if (path.resolve(process.cwd()) !== result.targetDir) {
+    log(`  cd ${result.targetDir}`);
+  }
   if (!installed) {
     log("  npm install --ignore-scripts");
   }

package/src/panel-driver.mjs

@@ -0,0 +1,283 @@
+// Driving the agent's panel the way a person does: open it, type into the
+// composer, press Enter, read the screen. Shared by `foldspace ask` and
+// `foldspace record`.
+//
+// Nothing here reaches into the SDK's internals, patches fetch or injects into
+// the panel. The panel is the SDK's iframe#eucera-agent-iframe; its document is
+// readable from the page, so the reply is read from what is on screen.
+
+import { createSettleTracker, replyAfter, squash } from "./ask-core.mjs";
+import { sleep } from "./cdp-client.mjs";
+
+export const PANEL_ID = "eucera-agent-iframe";
+
+// Shared by every page snippet: the panel document, or null while it loads.
+export const PANEL_DOC = `
+  const frame = document.getElementById(${JSON.stringify(PANEL_ID)});
+  let doc = null;
+  try { doc = frame && frame.contentDocument; } catch {}
+`;
+
+// The agent handle: the one attach's bootstrap made, else the page's own SDK
+// handle for this project's agent. Defines `sdk` and `agent` for the snippet
+// that follows.
+const AGENT_HANDLE = (agentApiName) => `
+  const wanted = ${JSON.stringify(agentApiName || "")};
+  const namespace = typeof window.__FOLD_SPACE__ === "string" && window.__FOLD_SPACE__
+    ? window.__FOLD_SPACE__ : "foldspace";
+  const sdk = window[namespace];
+  let agent = window.__FOLDSPACE_AGENT__ || null;
+  if (!agent && typeof sdk?.agentIds === "function") {
+    const ids = sdk.agentIds().filter((id) => typeof id === "string" && id.indexOf("-") > 0);
+    const id = ids.find((item) => item.slice(item.indexOf("-") + 1) === wanted) || ids[0];
+    if (id) {
+      const cut = id.indexOf("-");
+      agent = sdk.agent({ apiName: id.slice(cut + 1), mode: id.slice(0, cut).toUpperCase() });
+    }
+  }
+`;
+
+export async function panelState(page) {
+  return page.evaluate(`${PANEL_DOC}
+    if (!doc) return { frame: !!frame, composer: false };
+    const box = doc.querySelector("textarea");
+    const rect = frame.getBoundingClientRect();
+    return { frame: true, composer: !!box, visible: rect.width > 50 && rect.height > 50 };`);
+}
+
+// open() is the SDK's public "show the panel" call, the same thing the
+// launcher button does. The handle comes from the bootstrap when attach made
+// one, else from the page's own SDK.
+export async function openPanel(page, agentApiName) {
+  return page.evaluate(`${AGENT_HANDLE(agentApiName)}
+    if (typeof agent?.open !== "function") return { sdk: !!sdk, opened: false };
+    try { agent.open(); return { sdk: true, opened: true }; }
+    catch (error) { return { sdk: true, opened: false, error: String(error?.message || error) }; }`);
+}
+
+/**
+ * Open the panel until its composer shows. The composer does not exist until
+ * the panel has opened, and one open() is not always enough, so it is retried
+ * inside the poll. Gives up early when there is no panel and no SDK at all.
+ */
+export async function openComposer(page, agentApiName, { waitS = 30 } = {}) {
+  let state = await panelState(page);
+  let opened = { sdk: false, opened: false };
+  for (let tick = 0; tick < waitS && !(state.composer && state.visible); tick++) {
+    opened = await openPanel(page, agentApiName).catch(() => opened);
+    await sleep(1000);
+    state = await panelState(page).catch(() => state);
+    if (tick === 5 && !state.frame && !opened.sdk) break;
+  }
+  return { state, opened };
+}
+
+export async function readPanel(page, cardsBefore) {
+  return page.evaluate(`${PANEL_DOC}
+    if (!doc || !doc.body) return { panel: "", cards: [], cardFrames: 0, newCardFrames: 0 };
+    const squash = (text) => (text || "").replace(/\\s+/g, " ").trim();
+    const frames = Array.from(doc.querySelectorAll("iframe"));
+    const cards = [];
+    let painted = 0;
+    // Cards from earlier turns are still in the panel; only the new ones count.
+    for (const card of frames.slice(${Number(cardsBefore) || 0})) {
+      const rect = card.getBoundingClientRect();
+      if (rect.width > 20 && rect.height > 20) painted += 1;
+      try {
+        const body = card.contentDocument && card.contentDocument.body;
+        if (body) cards.push(squash(body.innerText || body.textContent));
+      } catch {}
+    }
+    return {
+      panel: squash(doc.body.innerText || doc.body.textContent),
+      cards: cards.filter(Boolean),
+      cardFrames: frames.length,
+      newCardFrames: painted,
+    };`);
+}
+
+/** Where the panel sits in the page, in CSS pixels, with the viewport size; null without one. */
+export async function panelRect(page) {
+  return page.evaluate(`${PANEL_DOC}
+    if (!frame) return null;
+    const rect = frame.getBoundingClientRect();
+    return {
+      x: rect.left, y: rect.top, width: rect.width, height: rect.height,
+      viewportWidth: window.innerWidth, viewportHeight: window.innerHeight,
+    };`);
+}
+
+async function focusComposer(page) {
+  return page.evaluate(`${PANEL_DOC}
+    const box = doc && doc.querySelector("textarea");
+    if (!box) return false;
+    window.focus(); frame.contentWindow.focus(); box.focus();
+    return doc.activeElement === box;`);
+}
+
+export async function composerValue(page) {
+  return page
+    .evaluate(`${PANEL_DOC}
+      const box = doc && doc.querySelector("textarea");
+      return box ? box.value : "";`)
+    .catch(() => "");
+}
+
+/** Enter as real key events through the browser's input pipeline. */
+export async function pressEnter(page) {
+  const enter = {
+    key: "Enter",
+    code: "Enter",
+    windowsVirtualKeyCode: 13,
+    nativeVirtualKeyCode: 13,
+  };
+  await page.send("Input.dispatchKeyEvent", { type: "rawKeyDown", ...enter });
+  await page.send("Input.dispatchKeyEvent", { type: "char", ...enter, text: "\r" });
+  await page.send("Input.dispatchKeyEvent", { type: "keyUp", ...enter });
+}
+
+// Real key events through the browser's input pipeline, like a person at the
+// keyboard. Frameworks that ignore synthetic DOM events still hear these.
+export async function typeLikeAPerson(page, text) {
+  const focused = await focusComposer(page);
+  if (!focused) return false;
+  await page.send("Input.insertText", { text });
+  const typed = await composerValue(page);
+  if (squash(typed) !== text) return false;
+  await pressEnter(page);
+  return true;
+}
+
+// The same gesture delivered as DOM events on the composer; still only typing,
+// still nothing injected. `submit` false fills the box and presses nothing.
+async function setComposerWithDomEvents(page, text, { submit = true } = {}) {
+  return page.evaluate(`${PANEL_DOC}
+    const box = doc && doc.querySelector("textarea");
+    if (!box) return false;
+    const view = frame.contentWindow;
+    const setValue = Object.getOwnPropertyDescriptor(view.HTMLTextAreaElement.prototype, "value").set;
+    box.focus();
+    setValue.call(box, ${JSON.stringify(text)});
+    box.dispatchEvent(new view.Event("input", { bubbles: true }));
+    if (${submit ? "true" : "false"}) {
+      for (const type of ["keydown", "keypress", "keyup"]) {
+        box.dispatchEvent(new view.KeyboardEvent(type, {
+          key: "Enter", code: "Enter", keyCode: 13, which: 13, bubbles: true, cancelable: true,
+        }));
+      }
+    }
+    return true;`);
+}
+
+// A background or unfocused tab can swallow CDP input. Same gesture, delivered
+// as DOM events on the composer.
+export async function typeWithDomEvents(page, text) {
+  return setComposerWithDomEvents(page, text, { submit: true });
+}
+
+/**
+ * Type the question and send it, the way `ask` always has: the keyboard
+ * first; if the question is still sitting in the composer afterwards, Enter
+ * never landed, so the same thing again as DOM events.
+ */
+export async function sendQuestion(page, question) {
+  let typedBy = "keyboard";
+  let sent = await typeLikeAPerson(page, question).catch(() => false);
+  await sleep(700);
+  // Still sitting in the composer means Enter never landed.
+  if (!sent || squash(await composerValue(page)) === question) {
+    typedBy = "dom-events";
+    sent = await typeWithDomEvents(page, question).catch(() => false);
+  }
+  return { sent, typedBy };
+}
+
+/**
+ * Type the question one character at a time, so a recording shows it being
+ * typed, then press Enter. Each character goes through the keyboard pipeline;
+ * if the window swallows CDP input, each one is set as a DOM input event
+ * instead - it still appears key by key. `delayMs` is the pause between keys.
+ * Returns { sent, typedBy, enteredAt }: enteredAt is when the Enter that sent
+ * it was pressed (ms), for a recording's timeline.
+ */
+export async function typeKeyByKey(page, question, { delayMs = 45 } = {}) {
+  const characters = [...question];
+  let typedBy = "keyboard";
+  if (!(await focusComposer(page).catch(() => false))) return { sent: false, typedBy };
+  let typed = "";
+  for (const character of characters) {
+    typed += character;
+    if (typedBy === "keyboard") {
+      await page.send("Input.insertText", { text: character }).catch(() => {});
+      // Checked on the first key only: the composer either hears CDP or not.
+      if (typed.length === 1 && (await composerValue(page)) !== typed) typedBy = "dom-events";
+    }
+    if (typedBy === "dom-events") {
+      await setComposerWithDomEvents(page, typed, { submit: false }).catch(() => false);
+    }
+    await sleep(delayMs);
+  }
+  if (squash(await composerValue(page)) !== squash(question)) return { sent: false, typedBy, enteredAt: null };
+  await sleep(250);
+  let enteredAt = Date.now();
+  await pressEnter(page).catch(() => {});
+  await sleep(500);
+  if (squash(await composerValue(page)) === squash(question)) {
+    // Enter never landed: the same key as DOM events.
+    enteredAt = Date.now();
+    await typeWithDomEvents(page, question).catch(() => false);
+    await sleep(400);
+    typedBy = "dom-events";
+  }
+  return { sent: squash(await composerValue(page)) !== squash(question), typedBy, enteredAt };
+}
+
+/**
+ * A fresh conversation, the way a person starts one: the New Chat button in
+ * the panel's header (its class is in both header layouts of the panel).
+ * Returns false when this panel shows no such button.
+ */
+export async function clickNewChat(page) {
+  return page.evaluate(`${PANEL_DOC}
+    const button = doc && doc.querySelector(".eucera-copilot-header-new-chat-icon");
+    if (!button) return false;
+    button.click();
+    return true;`);
+}
+
+/**
+ * The SDK's own way to put a question to the agent in a new conversation:
+ * agent.message(text, { newChat: true, autoSend: true }). The question is
+ * sent at once - nothing is typed - so it is only the fallback for a panel
+ * with no New Chat button.
+ */
+export async function messageInNewChat(page, agentApiName, question) {
+  return page.evaluate(`${AGENT_HANDLE(agentApiName)}
+    if (typeof agent?.message !== "function") return false;
+    agent.message(${JSON.stringify(question)}, { newChat: true, autoSend: true });
+    return true;`);
+}
+
+/**
+ * Poll the panel until the reply to `question` settles or `timeoutS` passes.
+ * `onPoll` sees each observation (with its time), for a caller that wants to
+ * know when the reply first appeared and when it last changed.
+ */
+export async function waitForReply(
+  page,
+  question,
+  { cardsBefore = 0, timeoutS = 90, pollMs = 1500, tracker = createSettleTracker(), onPoll } = {},
+) {
+  const deadline = Date.now() + timeoutS * 1000;
+  let seen = { panel: "", cards: [], newCardFrames: 0 };
+  let reply = "";
+  let settled = false;
+  while (Date.now() < deadline && !settled) {
+    await sleep(pollMs);
+    seen = await readPanel(page, cardsBefore).catch(() => seen);
+    reply = replyAfter(seen.panel, question);
+    settled = tracker.observe({ reply, cards: seen.cards }).settled;
+    if (onPoll) onPoll({ at: Date.now(), reply, seen, settled });
+  }
+  return { settled, reply, seen };
+}

package/src/session-events.mjs

@@ -13,6 +13,7 @@ export const SESSION_EVENTS = Object.freeze([
   "observe",
   "ask",
   "run",
+  "record",
 ]);
 
 export function eventsPath(projectDir) {

package/src/upgrade.mjs

@@ -18,6 +18,8 @@ const instructionTemplatePath = path.join(
   "agent-starter",
   "CLAUDE.md",
 );
+// Flat in the template (as claude-settings.json is); .claude/skills/ in a project.
+const skillsTemplateRoot = path.join(packageRoot, "templates", "agent-starter", "skills");
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
 
 export function resolveProjectDir(env = process.env, cwd = process.cwd()) {
@@ -208,6 +210,84 @@ export function refreshInstructionStub(projectDir, options = {}) {
   return { written: true, backedUp, importPresent: true };
 }
 
+/** Every file of the harness's skills: [{ rel, source }], rel under .claude/skills/. */
+function shippedSkillFiles(skillsRoot) {
+  const files = [];
+  if (!fs.existsSync(skillsRoot)) return files;
+  const walk = (relative) => {
+    for (const entry of fs.readdirSync(path.join(skillsRoot, relative), { withFileTypes: true })) {
+      const rel = path.join(relative, entry.name);
+      if (entry.isDirectory()) walk(rel);
+      else if (entry.isFile()) files.push({ rel, source: path.join(skillsRoot, rel) });
+    }
+  };
+  walk("");
+  return files;
+}
+
+/**
+ * The skills this harness ships, written into the project's .claude/skills/
+ * from the installed package: `init` writes them with the rest of the
+ * template, and an upgrade brings them up to date the same way. Only the
+ * harness's own skill folders are written; any other skill there is left
+ * alone. They carry no template tokens, so they are copied as they are. A
+ * copy that differs is kept beside it as <file>.bak first - it may hold the
+ * human's own edits. Returns { written, backedUp }, paths relative to the
+ * project.
+ */
+export function refreshProjectSkills(projectDir, { skillsRoot = skillsTemplateRoot } = {}) {
+  const written = [];
+  const backedUp = [];
+  for (const { rel, source } of shippedSkillFiles(skillsRoot)) {
+    const target = path.join(projectDir, ".claude", "skills", rel);
+    const content = fs.readFileSync(source);
+    let current = null;
+    try {
+      current = fs.readFileSync(target);
+    } catch {
+      current = null;
+    }
+    if (current && current.equals(content)) continue;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (current) {
+      fs.writeFileSync(`${target}.bak`, current);
+      backedUp.push(path.join(".claude", "skills", `${rel}.bak`));
+    }
+    fs.writeFileSync(target, content);
+    written.push(path.join(".claude", "skills", rel));
+  }
+  return { written, backedUp };
+}
+
+/**
+ * Write any of the harness's skill files the project does not have yet, and
+ * touch nothing else. Every command runs it: `upgrade --yes` runs the harness
+ * version that was installed before, which may come from before the skills
+ * shipped, so the first upgrade to this one cannot write them - the next
+ * command does. Only in a Foldspace project (foldspace.dev.json). Returns the
+ * paths written; never throws.
+ */
+export function ensureProjectSkills(projectDir, { skillsRoot = skillsTemplateRoot } = {}) {
+  const written = [];
+  try {
+    if (!fs.existsSync(path.join(projectDir, "foldspace.dev.json"))) return written;
+    for (const { rel, source } of shippedSkillFiles(skillsRoot)) {
+      const target = path.join(projectDir, ".claude", "skills", rel);
+      if (fs.existsSync(target)) continue;
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(source, target);
+      written.push(path.join(".claude", "skills", rel));
+    }
+  } catch {
+    // a read-only or odd project folder: the manual names the shipped copy too
+  }
+  return written;
+}
+
+function skillsReport(result) {
+  return result.backedUp.length ? { skills: result.written, skillsBackedUp: result.backedUp } : { skills: result.written };
+}
+
 function cachePath(projectDir) {
   return path.join(projectDir, ".foldspace-dev", "harness-update.json");
 }
@@ -483,6 +563,7 @@ export async function runUpgrade(argv, options = {}) {
       instructionsImport: true,
       refreshed: refreshed.written,
       backedUp: refreshed.backedUp,
+      ...skillsReport(refreshProjectSkills(projectDir, options)),
       next: refreshed.written
         ? "Imported platform instructions from the installed harness."
         : report.next,
@@ -525,7 +606,9 @@ export async function runUpgrade(argv, options = {}) {
   }
 
   if (!shouldInstall && !shouldRefresh) {
-    return report;
+    // Already on the latest: --yes still brings the skills up to date, for a
+    // project whose last upgrade ran a harness from before they shipped.
+    return parsed.yes ? { ...report, ...skillsReport(refreshProjectSkills(projectDir, options)) } : report;
   }
 
   if (shouldInstall) {
@@ -541,6 +624,8 @@ export async function runUpgrade(argv, options = {}) {
   if (shouldRefresh) {
     refreshed = refreshInstructionStub(projectDir, options);
   }
+  // After the install, this package's folder holds the new version's files.
+  const skills = skillsReport(refreshProjectSkills(projectDir, options));
 
   const nextReport = {
     ...report,
@@ -551,6 +636,7 @@ export async function runUpgrade(argv, options = {}) {
     instructionsImport: shouldRefresh ? true : report.instructionsImport,
     refreshed: refreshed.written,
     backedUp: refreshed.backedUp,
+    ...skills,
   };
   nextReport.next = nextAction(nextReport);
   return nextReport;