faberun 0.3.0 → 0.6.0

package/src/cli/setup.mjs

@@ -5,9 +5,14 @@
  * It checks the two host prerequisites, discovers the catalogue runtimes
  * through the same `discoverRuntimes` the engine uses, asks which harnesses to
  * enable and which runtime is the default worker and judge, and writes the user
- * config at `$FABERUN_HOME/config.json`. The judge must resolve to a vendor
- * other than the worker's; the prompt refuses a same-vendor answer once and the
- * command fails on the second.
+ * config at `$FABERUN_HOME/config.json`. When a config already exists, its
+ * recorded harnesses, worker and judge seed the defaults instead of the
+ * fresh-machine ones, narrowed to whatever discovery still reports available;
+ * an explicit `--harnesses`, `--worker` or `--judge` still wins. The judge must
+ * resolve to a vendor other than the worker's; the prompt refuses a same-vendor
+ * answer once and the command fails on the second. Once the config is written it offers to register
+ * the faberun skill into every installed harness's skills directory, reusing
+ * `registerSkills` from `./skills.mjs` so discovery has one home.
  *
  * Discovery and the question function are injected so tests never touch a real
  * binary or a terminal. `--json` never asks: it reports the same facts as one
@@ -25,10 +30,12 @@ import { boundedGitSync } from "../repo/worktree.mjs";
 import { colorLevel, renderBanner, statusToken } from "./brand.mjs";
 import { packageVersion } from "../host/package.mjs";
 import { configPath, faberunHome } from "../host/home.mjs";
-import { writeUserConfig } from "../host/config.mjs";
+import { readUserConfig, writeUserConfig } from "../host/config.mjs";
+import { discoverSkillTargets, registerSkills } from "./skills.mjs";
 
 /** @typedef {import("../engine/runtime-discovery.mjs").RuntimeAvailability} RuntimeAvailability */
 /** @typedef {import("../host/config.mjs").UserConfig} UserConfig */
+/** @typedef {import("./skills.mjs").SkillRegistration} SkillRegistration */
 /** @typedef {(text: string) => void} Writer */
 /** @typedef {(question: string) => Promise<string>} Asker */
 /** @typedef {{id: string, harness: string, model: string, available: boolean, status: string, missing: string[]}} RuntimeView */
@@ -39,9 +46,11 @@ import { writeUserConfig } from "../host/config.mjs";
  * @property {string} [harnesses]
  * @property {string} [worker]
  * @property {string} [judge]
+ * @property {boolean} [skill] whether to register the faberun skill (default true)
  * @property {boolean} [json]
  * @property {NodeJS.ProcessEnv} [env]
  * @property {() => Promise<Record<string, RuntimeAvailability>>} [discover]
+ * @property {(name: string) => boolean} [isInstalled]
  * @property {Asker} [ask]
  * @property {Writer} [stdout]
  * @property {Writer} [stderr]
@@ -94,7 +103,7 @@ export async function setupCommand(options = {}) {
   }
 
   if (requirements.some((requirement) => !requirement.ok)) {
-    if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null }, null, 2)}\n`);
+    if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null, skills: [] }, null, 2)}\n`);
     return 1;
   }
 
@@ -107,7 +116,7 @@ export async function setupCommand(options = {}) {
 
   if (availableHarnesses.length === 0) {
     if (json) {
-      stdout(`${JSON.stringify({ requirements, runtimes, config: null }, null, 2)}\n`);
+      stdout(`${JSON.stringify({ requirements, runtimes, config: null, skills: [] }, null, 2)}\n`);
     } else {
       stdout(`${statusToken("fail", level)} harnesses · none available · install one of: ${INSTALL_HARNESSES.join(", ")}\n`);
     }
@@ -115,7 +124,9 @@ export async function setupCommand(options = {}) {
   }
 
   const candidates = availableCandidates(DISCOVERY_RUNTIME_DEFINITIONS, availability);
-  const defaultWorker = cheapest(candidates)?.id ?? "";
+  const kept = mergeExistingConfig(readUserConfig(env), availability);
+  const defaultHarnesses = kept.harnesses.length > 0 ? kept.harnesses : availableHarnesses;
+  const defaultWorker = kept.worker || (cheapest(candidates)?.id ?? "");
   const interactive = isTTY && !json && !yes
     && options.harnesses === undefined && options.worker === undefined && options.judge === undefined;
 
@@ -124,16 +135,19 @@ export async function setupCommand(options = {}) {
   let selectedWorker;
   let selectedJudge;
   const asker = makeAsker(options.ask);
+  /** @type {SkillRegistration[]} */
+  let skills = [];
   try {
     if (interactive) {
-      const harnessAnswer = (await asker.ask(`Enable which harnesses? [${availableHarnesses.join(", ")}] `)).trim();
-      selectedHarnesses = splitHarnesses(harnessAnswer).length ? splitHarnesses(harnessAnswer) : availableHarnesses;
+      const harnessAnswer = (await asker.ask(`Enable which harnesses? [${defaultHarnesses.join(", ")}] `)).trim();
+      selectedHarnesses = splitHarnesses(harnessAnswer).length ? splitHarnesses(harnessAnswer) : defaultHarnesses;
 
       const workerAnswer = (await asker.ask(`Default worker runtime? [${defaultWorker}] `)).trim();
       selectedWorker = workerAnswer || defaultWorker;
 
-      let judgeAnswer = (await asker.ask(`Default judge runtime? [${defaultJudge(selectedWorker, candidates)}] `)).trim();
-      let judge = judgeAnswer || defaultJudge(selectedWorker, candidates);
+      const judgeDefault = keptJudgeDefault(kept, selectedWorker, candidates);
+      let judgeAnswer = (await asker.ask(`Default judge runtime? [${judgeDefault}] `)).trim();
+      let judge = judgeAnswer || judgeDefault;
       if (!crossVendor(judge, selectedWorker)) {
         stderr("the judge must come from a different vendor than the worker\n");
         judgeAnswer = (await asker.ask(`Default judge runtime? [${defaultJudge(selectedWorker, candidates)}] `)).trim();
@@ -142,35 +156,56 @@ export async function setupCommand(options = {}) {
       }
       selectedJudge = judge;
     } else {
-      selectedHarnesses = splitHarnesses(options.harnesses ?? "").length ? splitHarnesses(options.harnesses ?? "") : availableHarnesses;
+      selectedHarnesses = splitHarnesses(options.harnesses ?? "").length ? splitHarnesses(options.harnesses ?? "") : defaultHarnesses;
       selectedWorker = options.worker ?? defaultWorker;
-      selectedJudge = options.judge ?? defaultJudge(selectedWorker, candidates);
+      selectedJudge = options.judge ?? keptJudgeDefault(kept, selectedWorker, candidates);
       if (!crossVendor(selectedJudge, selectedWorker)) {
-        if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null }, null, 2)}\n`);
+        if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null, skills }, null, 2)}\n`);
         else stdout(`${statusToken("fail", level)} judge · the judge must come from a different vendor than the worker\n`);
         return 1;
       }
     }
-  } finally {
-    asker.close();
-  }
 
-  const config = {
-    schemaVersion: /** @type {1} */ (1),
-    harnesses: selectedHarnesses,
-    worker: selectedWorker,
-    judge: selectedJudge,
-    updatedAt: new Date().toISOString(),
-  };
-  writeUserConfig(env, config);
+    const config = {
+      schemaVersion: /** @type {1} */ (1),
+      harnesses: selectedHarnesses,
+      worker: selectedWorker,
+      judge: selectedJudge,
+      updatedAt: new Date().toISOString(),
+    };
+    writeUserConfig(env, config);
+    if (!json) stdout(`${statusToken("ok", level)} config · ${configPath(faberunHome(env))}\n`);
 
-  if (json) {
-    stdout(`${JSON.stringify({ requirements, runtimes, config }, null, 2)}\n`);
+    // The offer comes after the config is durable, so a machine that answers
+    // no still has a usable setup. Discovery is `skills.mjs`'s table, reused
+    // rather than re-probed here.
+    const detected = discoverSkillTargets({ env, isInstalled: options.isInstalled })
+      .filter((target) => target.dir !== null && target.dirExists && target.installed && !target.unsupported);
+    if (options.skill !== false && detected.length > 0) {
+      let register = true;
+      if (interactive) {
+        const answer = (await asker.ask(`Register the faberun skill for ${detected.map((target) => target.harness).join(", ")}? [Y/n] `)).trim();
+        register = !answer.toLowerCase().startsWith("n");
+      }
+      if (register) {
+        skills = registerSkills({
+          env,
+          level,
+          isInstalled: options.isInstalled,
+          stdout: json ? () => {} : stdout,
+        });
+      }
+    }
+
+    if (json) {
+      stdout(`${JSON.stringify({ requirements, runtimes, config, skills }, null, 2)}\n`);
+      return 0;
+    }
+    stdout("next · faberun init in a repository · faberun doctor\n");
     return 0;
+  } finally {
+    asker.close();
   }
-  stdout(`${statusToken("ok", level)} config · ${configPath(faberunHome(env))}\n`);
-  stdout("next · faberun init in a repository · faberun doctor\n");
-  return 0;
 }
 
 /**
@@ -225,6 +260,50 @@ function missingEnvKeys(runtime, env) {
   return [...new Set(names)];
 }
 
+/**
+ * The recorded harnesses, worker and judge that discovery still reports
+ * available, so a re-run of setup keeps an operator's earlier choices instead
+ * of resetting them to the fresh-machine defaults. A choice discovery cannot
+ * find is dropped, not kept blindly; the caller fills anything empty with
+ * today's defaults. A null `existing` (no config yet, or a malformed one)
+ * yields nothing kept.
+ *
+ * @param {UserConfig|null} existing
+ * @param {Record<string, RuntimeAvailability>} availability
+ * @returns {{harnesses: string[], worker: string, judge: string}}
+ */
+export function mergeExistingConfig(existing, availability) {
+  if (!existing) return { harnesses: [], worker: "", judge: "" };
+  const availableHarnesses = new Set(
+    Object.entries(DISCOVERY_RUNTIME_DEFINITIONS)
+      .filter(([id]) => availability[id]?.available === true)
+      .map(([, definition]) => definition.harness),
+  );
+  const candidateIds = new Set(
+    availableCandidates(DISCOVERY_RUNTIME_DEFINITIONS, availability).map((candidate) => candidate.id),
+  );
+  return {
+    harnesses: existing.harnesses.filter((harness) => availableHarnesses.has(harness)),
+    worker: existing.worker && candidateIds.has(existing.worker) ? existing.worker : "",
+    judge: existing.judge && candidateIds.has(existing.judge) ? existing.judge : "",
+  };
+}
+
+/**
+ * The judge default for the interactive prompt and `--yes`: the recorded judge
+ * when it is still available and still a different vendor than `workerId`,
+ * otherwise the strongest cross-vendor candidate as today.
+ *
+ * @param {{judge: string}} kept
+ * @param {string} workerId
+ * @param {import("../engine/runtime-discovery.mjs").RuntimeCandidate[]} candidates
+ * @returns {string}
+ */
+function keptJudgeDefault(kept, workerId, candidates) {
+  if (kept.judge && crossVendor(kept.judge, workerId)) return kept.judge;
+  return defaultJudge(workerId, candidates);
+}
+
 /**
  * The strongest available runtime whose vendor differs from the worker's. An
  * empty string means no cross-vendor runtime is available, which the caller

package/src/cli/skills.mjs

@@ -1,18 +1,38 @@
 /**
- * `skills` argv: list, install.
+ * `skills` argv: list, install, register.
  *
  * Per-operation options only, so `--force` is rejected by `list`. The
- * behavior lives in `installSkills`, exported because `faberun init` installs
- * the same catalogue into a target repository; this file owns the wire, the
- * same split `seat.mjs` uses.
+ * behavior lives in `installSkills` and `registerSkills`, exported because
+ * `faberun init` installs the same catalogue into a target repository and
+ * `faberun setup` registers the skill into every installed harness; this file
+ * owns the wire, the same split `seat.mjs` uses.
+ *
+ * `install` copies the catalogue into a caller-chosen `.claude/skills`.
+ * `register` discovers each installed harness's own skills directory and links
+ * (or, with `--copy`, copies) the `faberun` skill into it. Discovery is a
+ * measured table below, not a probe of live harness state.
  */
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs as parseFlags } from "node:util";
 
+import { faberunHome, installedVersionDir } from "../host/home.mjs";
+import { findExecutable } from "../host/preflight.mjs";
+import { colorLevel, statusToken } from "./brand.mjs";
+
 const SKILLS_DIR = fileURLToPath(new URL("../../skills", import.meta.url));
+const CHECKOUT_SKILL = join(SKILLS_DIR, "faberun");
 
 /** Flags are scoped to the operation that declares them; all others are rejected. */
 /** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
@@ -23,8 +43,64 @@ const OPERATION_OPTIONS = {
     global: { type: "boolean" },
     force: { type: "boolean" },
   },
+  register: {
+    harness: { type: "string" },
+    copy: { type: "boolean" },
+    force: { type: "boolean" },
+    json: { type: "boolean" },
+  },
 };
 
+/**
+ * Where each operator harness keeps the skills a user can add, measured
+ * 2026-09-16 on the machine this node ran on.
+ *
+ * - `claude` -> `~/.claude/skills` and `codex` -> `~/.codex/skills` are the
+ *   documented conventions; on this machine both directories hold symlinks into
+ *   `~/.agents/skills`.
+ * - `agents` -> `~/.agents/skills` is the shared convention. It is registered
+ *   on its own too, because a harness directory is often a symlink to it, and
+ *   it is optional so a machine without it stays quiet.
+ * - `zcode` 0.16.5: `zcode skills list` labels every local, non-plugin entry
+ *   `(user/agents)` and resolves it under `~/.agents/skills`; `~/.zcode` holds
+ *   only plugin and CLI state, so its user skill convention is the shared one.
+ * - `agy` (Antigravity CLI): the installed binary's embedded guide names
+ *   `~/.gemini/config/` as the global customization root and
+ *   `~/.gemini/config/skills/<name>/` as a global skill; the
+ *   `~/.gemini/antigravity-cli/builtin/skills` tree is shipped, read-only.
+ * - `dsh`: `dsh --help` lists no skills command and no skills directory exists,
+ *   so it has no registration target. It is kept in the table to record the
+ *   measurement, and reported as `no skill support`.
+ *
+ * @type {Record<string, {binary: string|null, optional: boolean, dir: ((home: string) => string)|null}>}
+ */
+const HARNESS_SKILL_DIRS = {
+  claude: { binary: "claude", optional: false, dir: (home) => join(home, ".claude", "skills") },
+  codex: { binary: "codex", optional: false, dir: (home) => join(home, ".codex", "skills") },
+  zcode: { binary: "zcode", optional: false, dir: (home) => join(home, ".agents", "skills") },
+  agy: { binary: "agy", optional: false, dir: (home) => join(home, ".gemini", "config", "skills") },
+  dsh: { binary: "dsh", optional: false, dir: null },
+  agents: { binary: null, optional: true, dir: (home) => join(home, ".agents", "skills") },
+};
+
+/** @typedef {(text: string) => void} Writer */
+/**
+ * @typedef {object} SkillTarget
+ * @property {string} harness
+ * @property {string|null} dir
+ * @property {string|null} binary
+ * @property {boolean} installed
+ * @property {boolean} dirExists
+ * @property {boolean} unsupported
+ * @property {boolean} optional
+ */
+/**
+ * @typedef {object} SkillRegistration
+ * @property {string} harness
+ * @property {string|null} dir
+ * @property {"linked"|"copied"|"unchanged"|"skipped"|"no_dir"|"not_installed"|"unsupported"} action
+ */
+
 /**
  * @param {string[]} args
  * @returns {void}
@@ -39,12 +115,30 @@ export function skillsCli(args) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     return usage();
   }
-  const values = /** @type {{target?: string, global?: boolean, force?: boolean}} */ (parsed.values);
+  const values = /** @type {{target?: string, global?: boolean, force?: boolean, copy?: boolean, json?: boolean, harness?: string}} */ (parsed.values);
   if (operation === "list") {
     if (parsed.positionals.length) return usage();
     for (const name of catalog()) process.stdout.write(`${name}\n`);
     return;
   }
+  if (operation === "register") {
+    if (parsed.positionals.length) return usage();
+    try {
+      const results = registerSkills({
+        harnesses: splitHarnesses(values.harness),
+        copy: values.copy === true,
+        force: values.force === true,
+        env: process.env,
+        level: values.json === true ? 0 : colorLevel(process.env, process.stdout.isTTY),
+        stdout: values.json === true ? () => {} : (text) => process.stdout.write(text),
+      });
+      if (values.json === true) process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      return usage();
+    }
+    return;
+  }
   const skillsDir = values.global
     ? join(homedir(), ".claude", "skills")
     : join(values.target ? resolve(values.target) : process.cwd(), ".claude", "skills");
@@ -88,6 +182,212 @@ export function installSkills({ names, skillsDir, force, stdout }) {
   return { installed, skipped };
 }
 
+/**
+ * The harness skills directories that exist on this machine, in table order,
+ * deduplicated by directory. `zcode` and the shared `agents` entry name the
+ * same `~/.agents/skills`; whichever is installed first claims it. A filter of
+ * harness names limits the result and rejects a name that is not in the table.
+ *
+ * @param {{env?: NodeJS.ProcessEnv, harnesses?: string[], isInstalled?: (name: string) => boolean}} [options]
+ * @returns {SkillTarget[]}
+ */
+export function discoverSkillTargets(options = {}) {
+  const env = options.env ?? process.env;
+  const home = skillHome(env);
+  const requested = options.harnesses && options.harnesses.length ? options.harnesses : null;
+  if (requested) {
+    for (const name of requested) {
+      if (!Object.hasOwn(HARNESS_SKILL_DIRS, name)) {
+        throw new Error(`no harness named "${name}" (choose from ${Object.keys(HARNESS_SKILL_DIRS).join(", ")})`);
+      }
+    }
+  }
+  const filter = requested ? new Set(requested) : null;
+  const isInstalled = options.isInstalled ?? ((name) => findExecutable(name) !== null);
+  /** @type {SkillTarget[]} */
+  const targets = [];
+  const claimed = new Set();
+  for (const [harness, entry] of Object.entries(HARNESS_SKILL_DIRS)) {
+    if (filter && !filter.has(harness)) continue;
+    const dir = entry.dir ? entry.dir(home) : null;
+    const installed = entry.binary ? isInstalled(entry.binary) : true;
+    if (dir && claimed.has(dir)) continue;
+    if (installed && dir && !entry.optional) claimed.add(dir);
+    targets.push({
+      harness,
+      dir,
+      binary: entry.binary,
+      installed,
+      dirExists: dir !== null && existsSync(dir),
+      unsupported: dir === null,
+      optional: entry.optional,
+    });
+  }
+  return targets;
+}
+
+/**
+ * Link or copy the `faberun` skill into every installed harness's skills
+ * directory. A harness whose binary is absent is reported and skipped; one
+ * whose directory is missing is a `[warn]` unless `force` creates it. A real
+ * directory already at the destination is left alone unless `force`. The
+ * caller owns the wire and the streams; `--json` passes a no-op writer.
+ *
+ * @param {{harnesses?: string[], copy?: boolean, force?: boolean, env?: NodeJS.ProcessEnv, level?: number, stdout?: Writer, isInstalled?: (name: string) => boolean}} [options]
+ * @returns {SkillRegistration[]}
+ */
+export function registerSkills(options = {}) {
+  const env = options.env ?? process.env;
+  const home = skillHome(env);
+  const stdout = options.stdout ?? ((text) => process.stdout.write(text));
+  const level = options.level ?? 0;
+  const force = options.force === true;
+  const source = skillSource(env);
+  const targets = discoverSkillTargets({ env, harnesses: options.harnesses, isInstalled: options.isInstalled });
+  /** @type {SkillRegistration[]} */
+  const results = [];
+  for (const target of targets) {
+    if (target.unsupported || target.dir === null) {
+      results.push({ harness: target.harness, dir: null, action: "unsupported" });
+      stdout(`${statusToken("ok", level)} ${target.harness} · no skill support\n`);
+      continue;
+    }
+    const dir = target.dir;
+    const destination = join(dir, "faberun");
+    if (!target.installed) {
+      results.push({ harness: target.harness, dir: destination, action: "not_installed" });
+      stdout(`${statusToken("ok", level)} ${target.harness} · not installed\n`);
+      continue;
+    }
+    if (!target.dirExists && !force) {
+      if (target.optional) continue;
+      results.push({ harness: target.harness, dir: destination, action: "no_dir" });
+      stdout(`${statusToken("warn", level)} ${target.harness} · no skills directory (${displayPath(dir, home)})\n`);
+      continue;
+    }
+    mkdirSync(dir, { recursive: true });
+    const action = options.copy === true ? copySkill(source, destination, force) : linkSkill(source, destination, force);
+    results.push({ harness: target.harness, dir: destination, action });
+    const path = displayPath(destination, home);
+    if (action === "skipped") {
+      stdout(`${statusToken("warn", level)} ${target.harness} · ${path} · exists, use --force\n`);
+    } else {
+      stdout(`${statusToken("ok", level)} ${target.harness} · ${path} · ${action}\n`);
+    }
+  }
+  return results;
+}
+
+/**
+ * The skill tree a registration points at: `$FABERUN_HOME/current/skills/faberun`
+ * when this CLI runs from the installed home layout, so the link follows every
+ * update, and this checkout's `skills/faberun` otherwise.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+function skillSource(env) {
+  const home = faberunHome(env);
+  return installedVersionDir(process.argv[1], home) ? join(home, "current", "skills", "faberun") : CHECKOUT_SKILL;
+}
+
+/**
+ * @param {string} source
+ * @param {string} destination
+ * @param {boolean} force
+ * @returns {"linked"|"unchanged"|"skipped"}
+ */
+function linkSkill(source, destination, force) {
+  const existing = lstatOrNull(destination);
+  if (existing) {
+    if (existing.isSymbolicLink() && !force && resolvesTo(destination, source)) return "unchanged";
+    if (!existing.isSymbolicLink() && !force) return "skipped";
+    rmSync(destination, { recursive: true, force: true });
+  }
+  symlinkSync(source, destination);
+  return "linked";
+}
+
+/**
+ * @param {string} source
+ * @param {string} destination
+ * @param {boolean} force
+ * @returns {"copied"|"unchanged"|"skipped"}
+ */
+function copySkill(source, destination, force) {
+  const existing = lstatOrNull(destination);
+  if (existing) {
+    if (existing.isDirectory() && !force) return "unchanged";
+    if (!force && !existing.isSymbolicLink()) return "skipped";
+    rmSync(destination, { recursive: true, force: true });
+  }
+  cpSync(source, destination, { recursive: true });
+  return "copied";
+}
+
+/**
+ * @param {string} path
+ * @returns {import("node:fs").Stats|null}
+ */
+function lstatOrNull(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    // A path that does not exist has no stats; the caller treats that as "free".
+    return null;
+  }
+}
+
+/**
+ * @param {string} destination
+ * @param {string} source
+ * @returns {boolean}
+ */
+function resolvesTo(destination, source) {
+  try {
+    return realpathSync(destination) === realpathSync(source);
+  } catch {
+    // Either path may be a dangling symlink; it cannot already point at source.
+    return false;
+  }
+}
+
+/**
+ * The home directory the skill directories hang off. `HOME` is honoured so a
+ * test or an install can point the whole discovery at a temporary tree.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+function skillHome(env) {
+  const configured = env.HOME;
+  if (typeof configured === "string" && configured) return configured;
+  return homedir();
+}
+
+/**
+ * Render a path under the home directory as `~/…` for the human lines; the
+ * machine-readable `dir` stays absolute.
+ *
+ * @param {string} path
+ * @param {string} home
+ * @returns {string}
+ */
+function displayPath(path, home) {
+  const prefix = home.endsWith(sep) ? home : `${home}${sep}`;
+  if (path === home) return "~";
+  return path.startsWith(prefix) ? `~${sep}${path.slice(prefix.length)}` : path;
+}
+
+/**
+ * @param {string|undefined} text
+ * @returns {string[]}
+ */
+function splitHarnesses(text) {
+  if (typeof text !== "string" || !text) return [];
+  return [...new Set(text.split(",").map((name) => name.trim()).filter(Boolean))];
+}
+
 /**
  * @returns {string[]} catalogue entries that carry a SKILL.md
  */
@@ -100,6 +400,6 @@ function catalog() {
 
 /** @returns {void} */
 function usage() {
-  process.stderr.write("usage: faberun skills <list|install> [<name>...] [--target <dir>] [--global] [--force]\n");
+  process.stderr.write("usage: faberun skills <list|install|register> [<name>...] [--target <dir>] [--global] [--force] [--copy] [--harness <a,b>] [--json]\n");
   process.exitCode = 2;
 }

package/src/cli.mjs

@@ -102,7 +102,7 @@ const COMMAND_OPTIONS = {
   "bulk-read": { question: { type: "string" }, paths: { type: "string", multiple: true }, json: { type: "boolean" } },
   next: { cwd: { type: "string" }, json: { type: "boolean" } },
   update: { check: { type: "boolean" }, json: { type: "boolean" } },
-  setup: { yes: { type: "boolean" }, harnesses: { type: "string" }, worker: { type: "string" }, judge: { type: "string" }, json: { type: "boolean" } },
+  setup: { yes: { type: "boolean" }, harnesses: { type: "string" }, worker: { type: "string" }, judge: { type: "string" }, "no-skill": { type: "boolean" }, json: { type: "boolean" } },
   init: { cwd: { type: "string" }, yes: { type: "boolean" }, "no-skill": { type: "boolean" }, agentkit: { type: "boolean" }, greenfield: { type: "boolean" }, stable: { type: "boolean" }, json: { type: "boolean" } },
   metrics: METRICS_OPTIONS,
 };
@@ -251,6 +251,7 @@ async function main(argv) {
       harnesses: typeof values.harnesses === "string" ? values.harnesses : undefined,
       worker: typeof values.worker === "string" ? values.worker : undefined,
       judge: typeof values.judge === "string" ? values.judge : undefined,
+      skill: values["no-skill"] !== true,
       json: values.json === true,
       env: process.env,
       isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),

package/src/contract/final-verification.mjs

@@ -5,8 +5,11 @@
  * `contract.finalVerification` is the contract-wide proof that the phase as a
  * whole closes: the controller runs it before the judge on the phase-terminal
  * node (the node no other node depends on), so no final checkpoint is ever
- * approved on partial verification. The persisted node-snapshot shape for
- * verification evidence lives here too, next to the schema it records.
+ * approved on partial verification. `contract.sharedVerification` carries the
+ * same command schema but is appended to every node's attempt and integration
+ * candidate, for the fast repository ratchets a node's write set can break.
+ * The persisted node-snapshot shape for verification evidence lives here too,
+ * next to the schema it records.
  */
 
 import { Buffer } from "node:buffer";
@@ -29,6 +32,32 @@ export function validateFinalVerification(value, label = "contract.finalVerifica
   return validateVerificationCommands(value, label);
 }
 
+/**
+ * Validate the optional contract-level `sharedVerification` field. It carries
+ * the identical verification-command schema as `finalVerification`; only the
+ * audience differs.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {VerificationCommand[]|undefined}
+ */
+export function validateSharedVerification(value, label = "contract.sharedVerification") {
+  if (value === undefined) return undefined;
+  return validateVerificationCommands(value, label);
+}
+
+/**
+ * The contract's `sharedVerification` commands, which every node's verification
+ * carries on both its attempt and its integration candidate. Absent means none,
+ * so a contract that declares nothing is unchanged.
+ *
+ * @param {{sharedVerification?: VerificationCommand[]}} contract
+ * @returns {VerificationCommand[]}
+ */
+export function sharedVerificationCommands(contract) {
+  return contract.sharedVerification ?? [];
+}
+
 /**
  * The contract's `finalVerification` commands when this node is the one that
  * closes the phase, otherwise none. A node is phase-terminal when no other