@terminus-ai/cli 0.0.1

package/bin/terminus.js

@@ -0,0 +1,3666 @@
+#!/usr/bin/env node
+
+import { Buffer } from "node:buffer";
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, readdir, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+import {
+  commandUsageError,
+  creationPageUrl,
+  emitJson,
+  newCreationUrl,
+  notConnectedHint,
+  parseFlags,
+  saveSession,
+  sessionRecordFromBrowserLogin,
+  webBase,
+} from "./client.mjs";
+import {
+  commandNamed,
+  helpRequested,
+  renderCommands,
+  renderHelp,
+  renderOverview,
+  unknownCommandMessage,
+} from "./commands.mjs";
+import { CliError, authError, errorEnvelope, usageError } from "./errors.mjs";
+import { exists, pathCompare, sha256, walkTree } from "./files.mjs";
+import {
+  Api,
+  CLI_VERSION,
+  DEFAULT_TERMINUS_API_BASE,
+  commandApiBase,
+  connect,
+  normalizeApiBase,
+  presentValue,
+  readSession,
+  sessionPath,
+  sessionTokenIsUsable,
+} from "./http.mjs";
+import { SYNC_DIRECTORY, byKey, entryKey, localChanges, readSyncRecord, writeSyncRecord } from "./sync.mjs";
+import { formatReleaseVersion, parseReleaseVersion } from "./versioning.mjs";
+
+const DEFAULT_MAX_FILES = 512;
+const DEFAULT_MAX_FILE_SIZE_BYTES = 5 * 1024 * 1024;
+const DEFAULT_MAX_TOTAL_SIZE_BYTES = 25 * 1024 * 1024;
+const MAX_REFERENCE_DEPTH = 3;
+const LOGIN_CALLBACK_TIMEOUT_MS = 10 * 60 * 1000;
+
+// What a skill package ships, decided the way terminus-backend decides it
+// (crates/terminus-skill-parser: `should_skip_skill_package_path` and
+// `is_standard_skill_package_path`) and pinned by
+// test/contracts/backend-skill-package-path-vectors.json. A path is relative
+// to the skill's root; a skipped path is never walked into or shipped, and
+// skipping wins over keeping.
+
+/** Directories a package never ships from, at any depth. */
+const PACKAGE_IGNORED_DIRECTORIES = new Set([
+  ".git",
+  ".github",
+  ".claude-plugin",
+  ".terminus",
+  ".terminus-dev",
+  ".workspace",
+  "node_modules",
+  ".venv",
+  "venv",
+  "__pypackages__",
+  "dist",
+  "build",
+  "target",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".vercel",
+  "__pycache__",
+]);
+const PACKAGE_IGNORED_FILE_NAMES = new Set([".DS_Store", "Thumbs.db"]);
+/** Top-level folders a package keeps whole. */
+const PACKAGE_STANDARD_FOLDERS = new Set(["assets", "references", "scripts", "templates", "examples"]);
+
+const CONTENT_TYPES = new Map([
+  [".md", "text/markdown; charset=utf-8"],
+  [".txt", "text/plain; charset=utf-8"],
+  [".yaml", "application/yaml"],
+  [".yml", "application/yaml"],
+  [".json", "application/json"],
+  [".py", "text/x-python; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"],
+  [".ts", "text/typescript; charset=utf-8"],
+  [".html", "text/html; charset=utf-8"],
+  [".htm", "text/html; charset=utf-8"],
+  [".svg", "image/svg+xml"],
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".webp", "image/webp"],
+  [".gif", "image/gif"],
+  [".pdf", "application/pdf"],
+]);
+
+/** Command name → handler. `help` and `version` are answered before
+ * dispatch; every other entry in bin/commands.mjs must appear here (a test
+ * holds the two tables together). */
+const HANDLERS = {
+  login: (args) => loginCommand(args),
+  logout: (args) => logoutCommand(args),
+  account: (args) => accountCommand(args),
+  notifications: (args) => notificationsCommand(args),
+  creations: (args) => creationsCommand(args),
+  drafts: (args) => draftsCommand(args),
+  status: (args) => statusCommand(args),
+  search: (args) => searchCommand(args),
+  connectors: (args) => connectorsCommand(args),
+  skills: (args) => skillsCommand(args),
+  init: (args) => initCommand(args),
+  validate: (args) => validateCommand(args),
+  pull: (args) => pullCommand(args),
+  push: (args) => pushCommand(args),
+  secrets: async (args) => (await import("./apps.mjs")).secretsCommand(args),
+  remote: (args) => remoteCommand(args),
+  build: async (args) => (await import("./apps.mjs")).buildCommand(args),
+  dev: async (args) => (await import("./appdev.mjs")).devCommand(args),
+  data: async (args) => (await import("./capsule-data.mjs")).dataCommand(args),
+  service: (args) => serviceCommand(args),
+  inspect: async (args) => (await import("./apps.mjs")).appCommand("inspect", args),
+  logs: async (args) => (await import("./apps.mjs")).appCommand("logs", args),
+  restore: (args) => restoreCommand(args),
+  log: (args) => logCommand(args),
+  diff: (args) => diffCommand(args),
+  outdated: async (args) => (await import("./apps.mjs")).outdatedCommand(args),
+  fork: async (args) => (await import("./apps.mjs")).forkCommand(args, { cloneOwnedSkill, cloneSkillCopy }),
+  // Apps, agents, and services clone from their draft doors in apps.mjs;
+  // skills have no draft and live here, so the dispatcher hands their clone
+  // in rather than making either module import the other.
+  clone: async (args) => (await import("./apps.mjs")).cloneCommand(args, { cloneOwnedSkill, cloneSkillCopy }),
+};
+
+export const COMMAND_HANDLERS = Object.freeze(Object.keys(HANDLERS));
+
+async function main(argv = process.argv.slice(2)) {
+  const [name, ...rest] = argv;
+  const topic = name === "help" ? rest.filter((arg) => arg !== "--help" && arg !== "-h") : [];
+  if (name === undefined || name === "--help" || name === "-h" || (name === "help" && !topic.length)) {
+    console.log(renderOverview({ version: CLI_VERSION }));
+    return;
+  }
+  if (name === "help") {
+    try {
+      console.log(renderHelp(topic));
+    } catch (error) {
+      throw error.usage ? usageError(error.message) : error;
+    }
+    return;
+  }
+  if (name === "commands") {
+    if (helpRequested(name, rest)) {
+      console.log(renderHelp(["commands"]));
+      return;
+    }
+    if (parseFlags(rest, "commands")._.length) {
+      throw commandUsageError("commands", { reason: "This command takes no arguments." });
+    }
+    console.log(renderCommands());
+    return;
+  }
+  if (name === "version" || name === "--version" || name === "-v") {
+    await versionCommand(name === "version" ? rest : []);
+    return;
+  }
+  const command = commandNamed(name);
+  if (!command || !HANDLERS[command.name]) {
+    throw usageError(unknownCommandMessage(name));
+  }
+  if (helpRequested(command.name, rest)) {
+    const sub = command.subcommands?.length ? rest.find((arg) => !arg.startsWith("-")) : undefined;
+    const topic = sub && command.subcommands.some((entry) => entry.name === sub)
+      ? [command.name, sub]
+      : [command.name];
+    console.log(renderHelp(topic));
+    return;
+  }
+  await HANDLERS[command.name](rest);
+}
+
+async function versionCommand(args) {
+  const flags = parseFlags(args, "version");
+  const version = CLI_VERSION;
+  if (!flags.json) {
+    console.log(`terminus ${version}`);
+    return;
+  }
+  const { APP_SDK_PACKAGE, APP_SDK_VERSION } = await import("./apps.mjs");
+  const { APP_RUNTIME_API_VERSION } = await import("./app-runtime-contract.mjs");
+  emitJson(flags, {
+    version,
+    app_sdk: { package: APP_SDK_PACKAGE, version: APP_SDK_VERSION, install: `npm install ${APP_SDK_PACKAGE}` },
+    runtime_api_version: APP_RUNTIME_API_VERSION,
+  });
+}
+
+/** Whether `args` name an app, agent, or service package (terminus.json).
+ * Flags are parsed first so `publish --strategy paid ./pkg` looks at ./pkg,
+ * not at the flag's value. */
+async function packageTarget(name, args) {
+  const target = parseFlags(args, name)._[0] ?? ".";
+  const apps = await import("./apps.mjs");
+  return { apps, isPackage: Boolean(await apps.packageKind(target)), target };
+}
+
+/** In a package or a skill folder, compare it with its draft; anywhere else
+ * there is nothing to compare, and the account lives under `terminus
+ * account`. */
+async function statusCommand(args) {
+  const { apps, isPackage, target } = await packageTarget("status", args);
+  if (isPackage) {
+    await apps.statusAppCommand(args);
+    return;
+  }
+  if (await exists(path.join(path.resolve(target), "SKILL.md"))) {
+    await statusSkillCommand(args);
+    return;
+  }
+  throw usageError(
+    `nothing to compare in ${path.resolve(target)} (no terminus.json or SKILL.md)\n`
+    + "status compares a working copy with its draft. To see your account, run `terminus account`.",
+  );
+}
+
+/** `terminus pull`: bring the draft's commits into this folder. */
+async function pullCommand(args) {
+  const { apps, isPackage, target } = await packageTarget("pull", args);
+  if (isPackage) await apps.pullAppCommand(args);
+  else if (await exists(path.join(path.resolve(target), "SKILL.md"))) await pullSkillCommand(args);
+  else await apps.pullAppCommand(args);
+}
+
+/** `terminus log` / `terminus diff` / `terminus restore`: with an address
+ * they read the catalog, and in a folder they read that working copy — a
+ * package's draft, or a skill's. */
+async function logCommand(args) {
+  const apps = await import("./apps.mjs");
+  if (parseFlags(args, "log")._.length || !(await exists(path.join(process.cwd(), "SKILL.md")))) {
+    await apps.logCommand(args);
+    return;
+  }
+  await logSkillCommand(args);
+}
+
+async function diffCommand(args) {
+  const apps = await import("./apps.mjs");
+  if (parseFlags(args, "diff")._.length || !(await exists(path.join(process.cwd(), "SKILL.md")))) {
+    await apps.diffCommand(args);
+    return;
+  }
+  await diffSkillCommand(args);
+}
+
+async function restoreCommand(args) {
+  const apps = await import("./apps.mjs");
+  // `restore <commit> [<dir>]`: the folder is the second word, not the first.
+  const dir = path.resolve(parseFlags(args, "restore")._[1] ?? ".");
+  if (!(await apps.packageKind(dir)) && await exists(path.join(dir, "SKILL.md"))) {
+    await restoreSkillCommand(args);
+    return;
+  }
+  await apps.restoreCommand(args);
+}
+
+async function validateCommand(args) {
+  const { apps, isPackage } = await packageTarget("validate", args);
+  if (isPackage) await apps.validateAppCommand(args);
+  else await validateSkillCommand(args);
+}
+
+/** `terminus push`: upload a folder to the creation it is linked to. An app,
+ * agent, or service folder holds terminus.json; a skill folder holds
+ * SKILL.md. Push never publishes — that is done on the web. */
+async function pushCommand(args) {
+  const { apps, isPackage } = await packageTarget("push", args);
+  if (isPackage) await apps.pushAppCommand(args);
+  else await pushSkillCommand(args);
+}
+
+/**
+ * `terminus remote` — the connection under git's own name.
+ *
+ * `remote add` records the connection; on its own it reads what the folder
+ * holds and says which creation that is, offline; `remote remove` forgets it.
+ */
+async function remoteCommand(args) {
+  const [verb, ...rest] = args;
+  if (verb === "add") return remoteAddCommand(rest);
+  if (verb === "remove") return removeRemoteCommand(rest);
+  // Anything else is the folder to read — `terminus remote ./my-app` — so a
+  // directory never has to be spelled as a verb it is not.
+  return showRemoteCommand(args);
+}
+
+/** What a folder is connected to, read from the folder alone. */
+async function folderRemote(dir) {
+  const apps = await import("./apps.mjs");
+  const record = await readSyncRecord(dir);
+  const kind = await apps.packageKind(dir);
+  if (kind) {
+    const document = JSON.parse(await readFile(path.join(dir, "terminus.json"), "utf8"));
+    return { address: document.id ?? record?.address ?? null, kind, record };
+  }
+  if (await exists(path.join(dir, "SKILL.md"))) {
+    const metadata = parseFrontmatterMetadata(await readFile(path.join(dir, "SKILL.md"), "utf8"));
+    // A skill records its id; the address is what a person reads, and the
+    // sync record is where a working copy keeps it.
+    return { address: record?.address ?? metadata.id ?? null, id: metadata.id ?? null, kind: "skill", record };
+  }
+  return null;
+}
+
+async function showRemoteCommand(args) {
+  const flags = parseFlags(args, "remote");
+  const dir = path.resolve(flags._[0] ?? ".");
+  const found = await folderRemote(dir);
+  if (!found) {
+    throw usageError(
+      `nothing in ${dir} to connect (no terminus.json or SKILL.md)\n`
+      + "A creation is made on the web; `terminus clone <address>` brings one down.",
+    );
+  }
+  const { shortCommit } = await import("./apps.mjs");
+  const readOnly = found.record?.source === "release";
+  // terminus.json's `id` is what push targets; the sync record says which
+  // address the folder was last in step with. Editing the id by hand parts
+  // them, and the commit then belongs to the creation the folder came FROM.
+  // Printing it under the new address states a fact about neither.
+  //
+  // Two addresses disagreeing is NOT proof of two creations: an address is
+  // renameable (`PATCH /apps/{id}/address`), so the same creation can answer
+  // to a new one. Only push can tell, because only push resolves an address
+  // to the id underneath it; this reads the folder and nothing else, so it
+  // reports the disagreement and lets `remote add` settle it.
+  const recorded = found.record?.source === "draft" ? found.record.address ?? null : null;
+  const retargeted = Boolean(recorded && found.address && recorded !== found.address);
+  const result = {
+    address: found.address,
+    kind: found.kind,
+    dir,
+    commit: !retargeted && found.record?.source === "draft" ? found.record.commit ?? null : null,
+    came_from: retargeted ? recorded : null,
+    read_only: readOnly,
+    release: readOnly ? found.record.release?.label ?? found.record.release?.version ?? null : null,
+  };
+  emitJson(flags, result, () => {
+    if (!result.address) {
+      console.log(`${dir} isn't connected to a creation.`);
+      console.log("Make one on the web, then: terminus remote add <address>");
+      return;
+    }
+    if (readOnly) {
+      const at = result.release ? ` ${creationVersion(result.release)}` : "";
+      console.log(`${dir} → ${result.address} (${result.kind}${at}, a read-only copy).`);
+      console.log(`It isn't yours to push to; to change it: terminus fork ${result.address}`);
+      return;
+    }
+    const at = result.commit ? `, at commit ${shortCommit(result.commit)}` : "";
+    console.log(`${dir} → ${result.address} (${result.kind})${at}.`);
+    // git's own shape for this: state what is true, then the ways out as
+    // indented `(use "...")` lines — the form `git status` uses to tell you
+    // your branch has diverged.
+    if (result.came_from) {
+      console.log(`This folder was last in step with ${result.came_from}, which terminus.json no longer names.`);
+      console.log(`  (use "terminus remote add ${result.address}" to settle which creation it belongs to)`);
+      console.log(`  (or set "id" back to "${result.came_from}" in terminus.json)`);
+      return;
+    }
+    if (!result.commit) {
+      console.log("This folder has no record of which commit it came from; `terminus pull` brings one down.");
+    }
+  });
+}
+
+/** Forget the connection. The files stay exactly as they are — this is
+ *  `git remote remove`, not a delete. */
+async function removeRemoteCommand(args) {
+  const flags = parseFlags(args, "remote");
+  const dir = path.resolve(flags._[0] ?? ".");
+  const found = await folderRemote(dir);
+  if (!found) {
+    throw usageError(`nothing in ${dir} to disconnect (no terminus.json or SKILL.md)`);
+  }
+  if (!found.address) {
+    throw new CliError(`${dir} isn't connected to a creation`);
+  }
+  if (found.kind === "skill") {
+    const skillPath = path.join(dir, "SKILL.md");
+    await writeFile(skillPath, withoutSkillId(await readFile(skillPath, "utf8")));
+  } else {
+    const manifestPath = path.join(dir, "terminus.json");
+    const document = JSON.parse(await readFile(manifestPath, "utf8"));
+    delete document.id;
+    await writeFile(manifestPath, `${JSON.stringify(document, null, 2)}\n`);
+  }
+  // The folder no longer follows anything, so what it matched is not a fact
+  // about it any more.
+  await rm(path.join(dir, SYNC_DIRECTORY), { force: true, recursive: true });
+  const result = { address: found.address, kind: found.kind, dir, connected: false };
+  emitJson(flags, result, () => {
+    console.log(`Disconnected ${dir} from ${result.address}. Every file is where it was.`);
+    console.log(`Connect it again with: terminus remote add ${result.address}`);
+  });
+}
+
+/** SKILL.md without its `id:` line, everything else as written. */
+function withoutSkillId(markdown) {
+  const text = String(markdown);
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return text;
+  const lines = match[1].split(/\r?\n/).filter((line) => frontmatterLineKey(line) !== "id");
+  return `---\n${lines.join("\n")}\n---${text.slice(match[0].length - (match[0].endsWith("\n") ? 1 : 0))}`;
+}
+
+/** `terminus remote add <address> [<dir>]`: connect a folder to a creation
+ * made on the web, the way `git remote add` connects a repository. */
+async function remoteAddCommand(args) {
+  const flags = parseFlags(args, "remote add");
+  const dir = path.resolve(flags._[1] ?? ".");
+  const apps = await import("./apps.mjs");
+  if (await apps.packageKind(dir)) return apps.remoteAddAppCommand(args);
+  // A skill is its SKILL.md, so a folder holding one is linked as a skill.
+  if (await exists(path.join(dir, "SKILL.md"))) return remoteAddSkillCommand(args);
+  // Neither: code that has never met Terminus. The app family writes the
+  // manifest from what the creation says it is; a skill address in such a
+  // folder has nothing to stamp an id into, and says so.
+  try {
+    await apps.remoteAddAppCommand(args);
+  } catch (error) {
+    if (!/is not one of your creations/u.test(String(error?.message ?? ""))) throw error;
+    await remoteAddSkillCommand(args);
+  }
+}
+
+async function serviceCommand(args) {
+  const [verb, ...serviceArgs] = args;
+  const apps = await import("./apps.mjs");
+  if (verb === "test") await apps.testServiceCommand(serviceArgs);
+  else if (verb === "inspect") await apps.inspectServiceCommand(serviceArgs);
+  else if (["submit", "job", "jobs", "cancel", "save"].includes(verb)) await apps.serviceJobCommand(verb, serviceArgs);
+  else {
+    throw commandUsageError("service", verb ? { reason: `'${verb}' is not a service command.` } : {});
+  }
+}
+
+
+
+async function loginCommand(args) {
+  const flags = parseFlags(args, "login");
+  const base = await commandApiBase(flags);
+
+  const existingLogin = await loginFromSavedSession(base);
+  if (existingLogin) {
+    console.log(loginLabel(existingLogin));
+    return;
+  }
+
+  await loginWithBrowser(base, flags);
+}
+
+async function loginFromSavedSession(base) {
+  const session = await readSession();
+  if (!sessionTokenIsUsable(session)) {
+    return null;
+  }
+  try {
+    const login = await loginWithCurrentProfile(new Api({ base, token: session.token.trim() }), session);
+    await saveSession(sessionRecordFromBrowserLogin(base, login, session));
+    return login;
+  } catch {
+    return null;
+  }
+}
+
+async function loginWithBrowser(base, flags = {}) {
+  const state = randomToken();
+  const codeVerifier = randomBytes(32).toString("base64url");
+  const codeChallenge = sha256(codeVerifier, "base64url");
+  // The callback page wears the same logo as the login page the user just
+  // left, served from that same origin (the email does this too).
+  const brandOrigin = webBase(flags);
+  const callback = await startLoginCallbackServer(state, brandOrigin);
+  try {
+    const loginUrl = browserLoginUrl({
+      webBase: brandOrigin,
+      callbackUrl: callback.url,
+      state,
+      apiBaseUrl: base,
+      codeChallenge,
+    });
+
+    console.log("Opening your browser to log in to Terminus.");
+    console.log(`If it does not open, visit:\n${loginUrl}`);
+    if (!flags.no_browser) {
+      await openBrowser(loginUrl);
+    }
+
+    const callbackResult = await callback.wait();
+    try {
+      // The web login page hands back a short-lived one-time CLI login code.
+      // Exchange it directly for a seven-day, server-revocable device session.
+      const sessionBase = callbackApiBase(base, callbackResult.apiUrl);
+      const device = nativeClientMetadata();
+      const exchanged = await exchangeCliLoginCode(
+        sessionBase,
+        callbackResult.code,
+        codeVerifier,
+        device,
+      );
+      const signedIn = new Api({ base: sessionBase, token: exchanged.token });
+      const user = await signedIn.json("GET /v1/auth/me");
+      const login = await loginWithCurrentProfile(signedIn, {
+        ...exchanged,
+        ...device,
+      }, user);
+      await saveSession(
+        sessionRecordFromBrowserLogin(sessionBase, login, {
+          email: user.email ?? callbackResult.email,
+          username: user.username,
+        }),
+      );
+      // The browser tab says "signed in" only once that is true here.
+      callbackResult.succeed(user.email ?? callbackResult.email);
+      console.log(loginLabel(login));
+    } catch (error) {
+      callbackResult.fail(error instanceof CliError ? error.message : "The CLI could not finish signing in.");
+      throw error;
+    }
+  } finally {
+    callback.close();
+  }
+}
+
+async function exchangeCliLoginCode(base, code, codeVerifier, device) {
+  let login;
+  try {
+    login = await new Api({ base }).json("POST /v1/auth/cli-login-code/exchange", {
+      body: { code, code_verifier: codeVerifier, ...device },
+    });
+  } catch (error) {
+    if (error.status === 400 || error.status === 401) {
+      throw authError("Terminus did not accept this sign-in (the code may have expired). Run `terminus login` again.");
+    }
+    throw error;
+  }
+  if (!login?.token) {
+    throw new CliError("Terminus API did not return a session token for the CLI login code");
+  }
+  return login;
+}
+
+function nativeClientMetadata() {
+  return {
+    client_kind: "cli",
+    device_name: os.hostname() || "Terminus CLI",
+    platform: `${process.platform}-${process.arch}`,
+    client_version: CLI_VERSION,
+  };
+}
+
+// The callback may pin the API base the web app actually authenticated
+// against; trust it only when it stays on the origin the login started on.
+function callbackApiBase(base, apiUrl) {
+  if (!apiUrl) {
+    return base;
+  }
+  try {
+    if (new URL(apiUrl).origin === new URL(base).origin) {
+      return normalizeApiBase(apiUrl);
+    }
+  } catch {
+    // Fall through to the base the login started with.
+  }
+  return base;
+}
+
+function browserLoginUrl({ webBase, callbackUrl, state, apiBaseUrl, codeChallenge }) {
+  const url = new URL("/login", webBase);
+  url.searchParams.set("cli_redirect", callbackUrl);
+  url.searchParams.set("cli_state", state);
+  url.searchParams.set("cli_api_url", apiBaseUrl);
+  url.searchParams.set("cli_code_challenge", codeChallenge);
+  return url.toString();
+}
+
+// The last frame of the login flow the user actually looks at, so it is the
+// auth panel rather than a bare sentence — see bin/login-page.mjs. Loaded here
+// rather than at module scope: it is a page of CSS that only a browser login
+// ever needs, and this is already the async step before the browser opens.
+async function startLoginCallbackServer(expectedState, brandOrigin) {
+  const { loginCompletePage, loginFailedPage } = await import("./login-page.mjs");
+  let settled = false;
+  let server;
+  let resolveCallback;
+  let rejectCallback;
+  const waitPromise = new Promise((resolve, reject) => {
+    resolveCallback = resolve;
+    rejectCallback = reject;
+  });
+
+  // A one-shot page carrying the account's address: never store it, and never
+  // let a proxy or the browser sniff it into something else.
+  const sendPage = (response, status, html) => {
+    response.writeHead(status, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Content-Length": Buffer.byteLength(html),
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff",
+    });
+    response.end(html);
+  };
+
+  // The tab that delivered the code waits on its response until the CLI has
+  // exchanged the code, so it can only ever say what actually happened.
+  const finish = (result, response) => {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    let answered = false;
+    const answer = (status, html) => {
+      if (answered || response.headersSent) return;
+      answered = true;
+      sendPage(response, status, html);
+    };
+    resolveCallback({
+      ...result,
+      succeed: (email) => answer(200, loginCompletePage({ email: email ?? result.email, brandOrigin })),
+      fail: (reason) => answer(400, loginFailedPage({ reason, brandOrigin })),
+    });
+  };
+
+  const fail = (message, response) => {
+    if (response && !response.headersSent) {
+      sendPage(response, 400, loginFailedPage({ reason: message, brandOrigin }));
+    }
+    if (!settled) {
+      settled = true;
+      rejectCallback(new CliError(message));
+    }
+  };
+
+  server = createServer((request, response) => {
+    const requestUrl = new URL(request.url ?? "/", `http://${request.headers.host ?? "127.0.0.1"}`);
+    if (request.method !== "GET" || requestUrl.pathname !== "/callback") {
+      response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      response.end("Not found");
+      return;
+    }
+
+    const state = requestUrl.searchParams.get("state") ?? "";
+    const code = requestUrl.searchParams.get("code") ?? "";
+    const email = requestUrl.searchParams.get("email") ?? undefined;
+    const apiUrl = requestUrl.searchParams.get("api_url") ?? undefined;
+    const error = requestUrl.searchParams.get("error");
+    if (state !== expectedState) {
+      // A stray request to the loopback port must not cancel the real login.
+      // Only a callback that proves knowledge of the cryptographic state may
+      // settle the pending attempt — so this answers the browser and leaves
+      // the attempt pending, rather than going through `fail`.
+      sendPage(
+        response,
+        400,
+        loginFailedPage({
+          reason: "This browser tab doesn't match the login the CLI is waiting for.",
+          brandOrigin,
+        }),
+      );
+      return;
+    }
+    if (error) {
+      fail(`Terminus browser login failed: ${error}`, response);
+      return;
+    }
+    if (!code) {
+      fail("Terminus browser login failed: callback did not include a login code", response);
+      return;
+    }
+    finish({ code, email, apiUrl }, response);
+  });
+
+  server.on("error", (error) => {
+    if (!settled) {
+      settled = true;
+      rejectCallback(error);
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  server.removeAllListeners("error");
+  server.on("error", (error) => {
+    if (!settled) {
+      settled = true;
+      rejectCallback(error);
+    }
+  });
+
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    server.close();
+    throw new CliError("failed to start local Terminus login callback server");
+  }
+
+  const timeout = setTimeout(() => {
+    if (!settled) {
+      settled = true;
+      rejectCallback(new CliError("Timed out waiting for browser login to finish"));
+      server.close();
+    }
+  }, LOGIN_CALLBACK_TIMEOUT_MS);
+  waitPromise.then(
+    () => clearTimeout(timeout),
+    () => clearTimeout(timeout),
+  );
+
+  return {
+    url: `http://127.0.0.1:${address.port}/callback`,
+    wait: () => waitPromise,
+    close: () => {
+      try {
+        server.close();
+      } catch {
+        // Server may already be closed after timeout or callback completion.
+      }
+    },
+  };
+}
+
+async function openBrowser(url) {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  return new Promise((resolve) => {
+    try {
+      const child = execFile(command, args, { detached: true, stdio: "ignore" }, (error) => {
+        resolve(!error);
+      });
+      child.unref();
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+/** A login with the profile of the account it signs in as. */
+async function loginWithCurrentProfile(api, login, currentProfile = null) {
+  const profile = currentProfile ?? await api.me();
+  return {
+    ...login,
+    profile,
+    display_name: profile.display_name,
+    username: profile.username ?? login.username,
+    email: profile.email ?? login.email,
+  };
+}
+
+function randomToken() {
+  return randomBytes(24).toString("base64url");
+}
+
+async function logoutCommand(args = []) {
+  if (args.length > 0) {
+    throw commandUsageError("logout", { reason: "This command takes no arguments." });
+  }
+  const session = await readSession();
+  if (sessionTokenIsUsable(session)) {
+    try {
+      // This device's session, revoked on the API it was made against.
+      await new Api({
+        base: session.api_base ?? DEFAULT_TERMINUS_API_BASE,
+        token: session.token.trim(),
+      }).json("POST /v1/auth/logout");
+    } catch {
+      console.error(
+        "Warning: the remote device session could not be revoked; it will expire automatically.",
+      );
+    }
+  }
+  await rm(sessionPath(), { force: true });
+  console.log("Logged out.");
+}
+
+async function accountCommand(args) {
+  const flags = parseFlags(args, "account");
+  if (flags._.length) throw commandUsageError("account", { reason: "This command takes no arguments." });
+  const api = await connect(flags);
+  // TERMINUS_TOKEN is a session the environment supplies: say whose it is,
+  // but never read or rewrite the saved login on its behalf.
+  const override = api.identity.source === "env";
+  const saved = api.identity.session;
+  // A count that cannot be read drops out of the line; who you are never does.
+  const [login, box, creations] = await Promise.all([
+    loginWithCurrentProfile(api, override ? { token: api.token } : saved),
+    readNotificationBox(api).catch(() => null),
+    readCreations(api).catch(() => null),
+  ]);
+  if (!override) await saveSession(sessionRecordFromBrowserLogin(api.base, login, saved));
+
+  const unread = box ? unreadCount(box) : null;
+  const published = creations ? creations.filter((creation) => creation.status === "published").length : null;
+  const output = {
+    ...safeStatusResponse(api.base, login, override ? { auth_method: "token" } : saved),
+    notifications: { unread },
+    creations: { published },
+    ...(override ? { source: "TERMINUS_TOKEN" } : {}),
+  };
+  emitJson(flags, output, () => {
+    const name = accountName(login);
+    console.log(name ? `Hi, ${name}` : "Hi!");
+    const counts = [
+      unread === null ? "" : `Notifications: ${unread}`,
+      published === null ? "" : `Creations: ${published}`,
+    ].filter(Boolean);
+    if (counts.length) console.log(counts.join(" · "));
+    if (override) {
+      console.log("Using the access token in TERMINUS_TOKEN.");
+    } else if (sessionExpiresWithinADay(saved.expires_at)) {
+      console.log(sessionExpiryLine(saved.expires_at));
+    }
+  });
+}
+
+/** "This device's session expires in 6 days." — with a nudge on the last day,
+ * because nothing refreshes a CLI session and it ends mid-task otherwise. */
+export function sessionExpiryLine(expiresAt, now = Date.now()) {
+  const at = Date.parse(expiresAt ?? "");
+  if (!Number.isFinite(at)) return "";
+  const left = at - now;
+  if (left <= 0) return "";
+  const hours = Math.floor(left / 3_600_000);
+  const days = Math.floor(hours / 24);
+  if (days >= 1) return `This device's session expires in ${days} day${days === 1 ? "" : "s"}.`;
+  const span = hours >= 1 ? `${hours} hour${hours === 1 ? "" : "s"}` : "less than an hour";
+  return `This device's session expires in ${span}; run \`terminus login\` again soon.`;
+}
+
+/** `account` stays two lines until the session is into its last day. */
+export function sessionExpiresWithinADay(expiresAt, now = Date.now()) {
+  const at = Date.parse(expiresAt ?? "");
+  return Number.isFinite(at) && at > now && at - now < 86_400_000;
+}
+
+/** The notification box, counted the way the web's feed counts its badge:
+ * pending invitations to collaborate or to join a chat, plus notifications
+ * (unread ones unless `all`). A chat invitation also leaves an `invite`
+ * notification behind; the box shows it once, as the invitation. */
+async function readNotificationBox(api, { all = false, limit = 200 } = {}) {
+  const [feed, collaborations, chats] = await Promise.all([
+    api.json("GET /v1/apps/notifications", { query: { limit, unread: all ? undefined : "true" } }),
+    api.json("GET /v1/collaborations/invitations"),
+    api.json("GET /v1/spaces/invitations"),
+  ]);
+  const listOf = (value) => (Array.isArray(value) ? value.filter(Boolean) : []);
+  return {
+    collaborations: listOf(collaborations?.invitations),
+    chats: listOf(chats?.invitations),
+    notifications: listOf(feed?.notifications).filter((item) => !(
+      item.kind === "invite" && item.data?.kind === "space.invited"
+    )),
+  };
+}
+
+function unreadCount(box) {
+  return box.collaborations.length
+    + box.chats.length
+    + box.notifications.filter((item) => !item.read_at).length;
+}
+
+/** Your creations, as Creations on the web lists them: the apps, agents, and
+ * services you own (not the platform's official rows, not ones shared with
+ * you) and your own skills — the developer overview lists only those. */
+async function readCreations(api) {
+  const [registry, overview] = await Promise.all([
+    api.json("GET /v1/apps", { query: { mine: "true" } }),
+    api.json("GET /v1/dashboard/developer", { query: { days: 1 } }),
+  ]);
+  const creations = [];
+  for (const app of registry.apps ?? []) {
+    if (app.is_official === true || app.viewer_role === "collaborator") continue;
+    creations.push({
+      kind: app.kind,
+      name: app.name,
+      address: app.address,
+      status: app.status,
+      version: creationVersion(app.release_label ?? app.release_version),
+    });
+  }
+  for (const skill of overview.skills ?? []) {
+    creations.push({
+      kind: "skill",
+      name: skill.name,
+      address: skill.address,
+      // A skill Terminus is holding reads as suspended, as it does on the web.
+      status: skill.suspended_at && skill.status !== "deleted" ? "suspended" : skill.status,
+      version: creationVersion(skill.release_version),
+    });
+  }
+  return creations.filter((creation) => creation.status !== "deleted");
+}
+
+/** "v1.2.0", read the way the web reads versions: a legacy ordinal or short
+ * label grows the parts it left out, a codename keeps its spelling, and a
+ * draft (0, null, "") has none. */
+export function creationVersion(value) {
+  if (value === null || value === undefined || value === 0 || String(value).trim() === "") return null;
+  const raw = String(value).trim().replace(/^[vV]/, "");
+  const parsed = parseReleaseVersion(raw)
+    ?? (/^\d+$/.test(raw) ? parseReleaseVersion(`${raw}.0.0`) : null)
+    ?? (/^\d+\.\d+$/.test(raw) ? parseReleaseVersion(`${raw}.0`) : null);
+  return parsed ? formatReleaseVersion(parsed) : `v${raw}`;
+}
+
+async function notificationsCommand(args) {
+  const flags = parseFlags(args, "notifications");
+  if (flags._.length) throw commandUsageError("notifications", { reason: "This command takes no arguments." });
+  const limit = positiveLimit(flags.limit, 20, "notifications");
+  const api = await connect(flags);
+  // Read the whole box (the server caps it at 200) so the count and the
+  // "and N more" line are true; --limit only trims what is printed.
+  const box = await readNotificationBox(api, { all: Boolean(flags.all) });
+  const shown = box.notifications.slice(0, limit);
+  emitJson(flags, {
+    unread: unreadCount(box),
+    invitations: { collaborations: box.collaborations, chats: box.chats },
+    notifications: shown,
+  }, () => printNotificationBox(box, shown, { all: Boolean(flags.all) }));
+}
+
+function positiveLimit(raw, fallback, command) {
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw commandUsageError(command, { reason: "--limit takes a whole number above 0." });
+  }
+  return value;
+}
+
+function printNotificationBox(box, shown, { all }) {
+  const sections = [];
+  const invitations = [
+    ...box.collaborations.map((invite) => {
+      const from = invite.inviter_username ? `, from @${invite.inviter_username}` : "";
+      return `Collaborate on ${invite.name} (${invite.address})${from} · ${ago(invite.invited_at)}`;
+    }),
+    ...box.chats.map((invite) => {
+      const inviter = invite.inviter?.handle
+        ? `, from ${invite.inviter.name ? `${invite.inviter.name} (@${invite.inviter.handle})` : `@${invite.inviter.handle}`}`
+        : "";
+      return `Join the chat "${invite.space_name}"${inviter} · ${ago(invite.created_at)}`;
+    }),
+  ];
+  if (invitations.length) {
+    sections.push([`Invitations (${invitations.length}):`, ...invitations.map((line) => `  ${clip(line, 78)}`)]);
+  }
+  const unread = box.notifications.filter((item) => !item.read_at).length;
+  const title = all ? `Recent (${box.notifications.length}):` : `Unread (${unread}):`;
+  if (shown.length) {
+    const rows = [];
+    for (const item of shown) {
+      const mark = all && !item.read_at ? "•" : " ";
+      const when = ago(item.created_at).padEnd(8);
+      rows.push(clip(`${mark} ${when}  ${item.app_name ? `${item.app_name}: ` : ""}${item.title}`, 80));
+      if (item.body) rows.push(clip(`            ${item.body.replace(/\s+/g, " ").trim()}`, 80));
+    }
+    const hidden = box.notifications.length - shown.length;
+    if (hidden > 0) rows.push(`  …and ${hidden} more (use --limit)`);
+    sections.push([title, ...rows]);
+  }
+  if (!sections.length) {
+    console.log(all ? "No notifications yet." : "No unread notifications.");
+    return;
+  }
+  console.log(sections.map((lines) => lines.join("\n")).join("\n\n"));
+}
+
+async function creationsCommand(args) {
+  const flags = parseFlags(args, "creations");
+  if (flags._.length) throw commandUsageError("creations", { reason: "This command takes no arguments." });
+  const creations = await readCreationsFor(flags);
+  // Published, and any Terminus has suspended; drafts have their own command.
+  const shown = creations.filter((creation) => creation.status !== "draft");
+  emitJson(flags, { creations: shown }, () => {
+    if (shown.length) return printCreationGroups(shown);
+    const drafts = creations.length;
+    console.log("You haven't published anything yet.");
+    if (drafts) console.log(`You have ${drafts} draft${drafts === 1 ? "" : "s"}: terminus drafts`);
+  });
+}
+
+async function draftsCommand(args) {
+  const flags = parseFlags(args, "drafts");
+  if (flags._.length) throw commandUsageError("drafts", { reason: "This command takes no arguments." });
+  const drafts = (await readCreationsFor(flags)).filter((creation) => creation.status === "draft");
+  emitJson(flags, { drafts }, () => {
+    if (drafts.length) return printCreationGroups(drafts);
+    console.log("You have no drafts. Start one with terminus init.");
+  });
+}
+
+async function readCreationsFor(flags) {
+  return readCreations(await connect(flags));
+}
+
+const CREATION_GROUPS = [
+  ["published", "Published"],
+  ["suspended", "Suspended"],
+  ["draft", "Drafts"],
+];
+const KIND_ORDER = ["app", "agent", "service", "skill"];
+
+/** Creations as aligned rows (name, kind, address, version) under one
+ * heading per status, apps before agents, services, and skills. */
+function printCreationGroups(rows) {
+  const order = (creation) => [KIND_ORDER.indexOf(creation.kind), creation.name.toLowerCase()];
+  const sorted = [...rows].sort((a, b) => {
+    const [ka, na] = order(a);
+    const [kb, nb] = order(b);
+    return ka - kb || na.localeCompare(nb);
+  });
+  const width = (key) => Math.max(...sorted.map((creation) => String(creation[key] ?? "").length));
+  const [nameWidth, kindWidth, addressWidth] = [width("name"), width("kind"), width("address")];
+  const row = (creation) => clip(
+    `  ${creation.name.padEnd(nameWidth)}  ${creation.kind.padEnd(kindWidth)}  ${creation.address.padEnd(addressWidth)}  ${creation.version ?? ""}`.trimEnd(),
+    100,
+  );
+  const known = new Set(CREATION_GROUPS.map(([status]) => status));
+  const groups = [
+    ...CREATION_GROUPS,
+    ...[...new Set(sorted.map((creation) => creation.status))].filter((status) => !known.has(status)).map((status) => [status, status]),
+  ];
+  const sections = [];
+  for (const [status, title] of groups) {
+    const members = sorted.filter((creation) => creation.status === status);
+    if (members.length) sections.push([`${title} (${members.length}):`, ...members.map(row)].join("\n"));
+  }
+  console.log(sections.join("\n\n"));
+}
+
+/** "3h ago" for a timestamp, a date past a month. */
+function ago(iso, now = Date.now()) {
+  const at = Date.parse(iso ?? "");
+  if (!Number.isFinite(at)) return "";
+  const minutes = Math.floor(Math.max(0, now - at) / 60_000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days}d ago`;
+  return new Date(at).toISOString().slice(0, 10);
+}
+
+function clip(text, width) {
+  return text.length <= width ? text : `${text.slice(0, width - 1)}…`;
+}
+
+/** How many results `terminus search` shows without --limit. */
+const SEARCH_DEFAULT_LIMIT = 10;
+
+/** Where a search came from, in the search door's own vocabulary (web,
+ * chat, agent, cli, api): the CLI is `cli`, run on its own or inside a
+ * coding agent alike. */
+const SEARCH_SOURCE = "cli";
+
+async function searchCommand(args) {
+  const flags = parseFlags(args, "search");
+  const query = flags._.join(" ").trim();
+  if (!query) {
+    throw commandUsageError("search");
+  }
+
+  const kind = flags.kind === undefined ? undefined : String(flags.kind);
+  if (kind !== undefined && !["skill", "service", "app", "agent"].includes(kind)) {
+    throw usageError("--kind must be skill, service, app, or agent");
+  }
+  const api = await connect(flags);
+  const results = await api.json("GET /v1/skills/search", {
+    query: {
+      q: query,
+      source: SEARCH_SOURCE,
+      limit: flags.limit ?? SEARCH_DEFAULT_LIMIT,
+      kinds: kind,
+    },
+  });
+  emitJson(flags, results, () => printSearchResults(results));
+}
+
+async function connectorsCommand(args) {
+  const flags = parseFlags(args, "connectors");
+  if (flags._.length > 1) {
+    throw commandUsageError("connectors", { reason: "This command takes at most one SLUG argument." });
+  }
+  const requestedSlug = flags._[0]?.trim().toLowerCase();
+  const api = await connect(flags);
+  const response = await api.json("GET /v1/connectors");
+  const connectors = Array.isArray(response.connectors) ? response.connectors : [];
+  if (requestedSlug) {
+    const connector = connectors.find((entry) => entry?.slug === requestedSlug);
+    if (!connector) {
+      throw new CliError(`connector '${requestedSlug}' is not available to this account`);
+    }
+    emitJson(flags, connector, () => printConnectorDetail(connector));
+    return;
+  }
+  const result = { connectors };
+  emitJson(flags, result, () => printConnectorList(connectors));
+}
+
+function connectorProfiles(connector) {
+  return Array.isArray(connector?.profiles) ? connector.profiles : [];
+}
+
+function printConnectorList(connectors) {
+  if (connectors.length === 0) {
+    console.log("No connectors are available.");
+    return;
+  }
+  for (const connector of connectors) {
+    const profiles = connectorProfiles(connector);
+    const status = connector.enabled === false ? " · disabled" : "";
+    console.log(`${connector.name ?? connector.slug} (${connector.slug})${status}`);
+    console.log(`  Tools: ${profiles.length ? profiles.map((profile) => profile.id).join(", ") : "none"}`);
+  }
+  console.log("\nRun `terminus connectors <slug>` to see operations and required scopes.");
+}
+
+function printConnectorDetail(connector) {
+  const profiles = connectorProfiles(connector);
+  const status = connector.enabled === false ? " · disabled" : "";
+  console.log(`${connector.name ?? connector.slug} (${connector.slug})${status}`);
+  if (connector.description) console.log(connector.description);
+  if (profiles.length === 0) {
+    console.log("\nAgent tools: none (exact resource grants are still available).");
+    return;
+  }
+  console.log(`\nAgent tools (${profiles.length}):`);
+  for (const profile of profiles) {
+    console.log(`  ${profile.id} — ${profile.name}`);
+    if (profile.description) console.log(`    ${profile.description}`);
+    const operations = Array.isArray(profile.operations) ? profile.operations : [];
+    console.log(`    Operations: ${operations.length ? operations.join("; ") : "none listed"}`);
+    const scopes = Array.isArray(profile.required_scopes) ? profile.required_scopes : [];
+    console.log(`    Required scopes: ${scopes.length ? scopes.join(", ") : "connector or token configuration"}`);
+  }
+}
+
+const SKILL_COMMANDS = {
+  install: (args) => installCommand(args),
+  list: (args) => installedCommand(args),
+  update: (args) => updateCommand(args),
+  uninstall: (args) => uninstallCommand(args),
+  use: (args) => useCommand(args),
+  fetch: (args) => fetchCommand(args),
+  files: (args) => filesCommand(args),
+  file: (args) => fileCommand(args),
+};
+
+export const SKILL_COMMAND_HANDLERS = Object.freeze(Object.keys(SKILL_COMMANDS));
+
+/** `terminus skills <command>`. On its own it is the page of every skill
+ * command, the same as `terminus help skills`. */
+async function skillsCommand(args) {
+  const [verb, ...rest] = args;
+  if (verb === undefined) {
+    console.log(renderHelp(["skills"]));
+    return;
+  }
+  const run = verb.startsWith("-") ? null : SKILL_COMMANDS[verb];
+  if (!run) {
+    throw commandUsageError("skills", verb.startsWith("-") ? {} : { reason: `'${verb}' is not a skills command.` });
+  }
+  await run(rest);
+}
+
+async function useCommand(args) {
+  const flags = parseFlags(args, "skills use");
+  const query = flags._.join(" ").trim();
+  if (!query) {
+    throw commandUsageError("skills", { sub: "use" });
+  }
+
+  const limit = Number.parseInt(flags.limit ?? "5", 10);
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw usageError("--limit must be a positive integer");
+  }
+
+  const api = await connect(flags);
+
+  // Addresses and ids skip search: installed pointer skills use exactly the
+  // skill they were installed for. A 404 falls back to the search flow.
+  if (!flags.search && looksLikeSkillReference(query)) {
+    const direct = await useSkillAsAccount(api, query, query).catch((error) => {
+      if (error.status === 404) return null;
+      throw error;
+    });
+    if (direct) {
+      emitJson(flags, direct, () => printSkillUseResult(accountUseResult(direct)));
+      return;
+    }
+  }
+
+  const results = await api.json("GET /v1/skills/search", {
+    query: { q: query, limit, source: SEARCH_SOURCE },
+  });
+  const skills = Array.isArray(results.skills) ? results.skills : [];
+  if (skills.length === 0) {
+    emitJson(flags, { query, selected: null, result_count: 0 }, () => printSearchResults(results));
+    return;
+  }
+
+  let selectedIndex = selectedSkillIndex(flags, skills.length);
+  if (selectedIndex == null) {
+    if (flags.json) {
+      throw usageError("terminus skills use --json requires --select <n> or --use-first");
+    }
+    printSearchResults(results);
+    selectedIndex = await promptSkillSelection(skills.length);
+    if (selectedIndex == null) {
+      console.log("Canceled.");
+      return;
+    }
+  }
+
+  const useResult = await useSkillAsAccount(api, skills[selectedIndex].uid, query, {
+    searchEventId: results.search_event_id,
+    name: skills[selectedIndex].address,
+  });
+  emitJson(flags, useResult, () => printSkillUseResult(accountUseResult(useResult)));
+}
+
+async function filesCommand(args) {
+  const flags = parseFlags(args, "skills files");
+  const skillRef = flags._[0]?.trim();
+  if (!skillRef) {
+    throw commandUsageError("skills", { sub: "files" });
+  }
+
+  const api = await connect(flags, { auth: "optional" });
+  const skill = await skillDetail(api, skillRef);
+  await refuseClosedSkill(api, skill, "list its files");
+  const result = await skillFiles(api, skill.uid, { includeContent: false });
+  emitJson(flags, { skill_ref: skill.uid, ...result }, () => printSkillFileManifest(skill.uid, result));
+}
+
+async function fileCommand(args) {
+  const flags = parseFlags(args, "skills file");
+  const skillRef = flags._[0]?.trim();
+  const filePath = flags._.slice(1).join(" ").trim();
+  if (!skillRef || !filePath) {
+    throw commandUsageError("skills", { sub: "file" });
+  }
+
+  const api = await connect(flags, { auth: "optional" });
+  const skill = await skillDetail(api, skillRef);
+  await refuseClosedSkill(api, skill, "print its files");
+  const resolvedRef = skill.uid;
+  const result = await skillFiles(api, resolvedRef, { includeContent: true, path: filePath });
+  const file = Array.isArray(result.files) ? result.files[0] : null;
+  if (!file) {
+    throw new CliError(`remote skill file not found: ${filePath}`);
+  }
+  const content = skillFileText(file);
+  emitJson(
+    flags,
+    {
+      skill_ref: resolvedRef,
+      path: file.path,
+      content_type: file.content_type,
+      size_bytes: file.size_bytes,
+      asset_url: file.asset_url,
+      content,
+    },
+    () => printSkillFileContent(resolvedRef, file, content),
+  );
+}
+
+const INSTALL_MANIFEST_NAME = ".terminus-install.json";
+
+// Skill directories the coding agents preload at session start; mirrors the
+// layout `npx skills` installs into.
+const AGENT_SKILL_DIRS = {
+  claude: [".claude", "skills"],
+  codex: [".codex", "skills"],
+};
+
+function defaultInstallAgent() {
+  if (process.env.CODEX_SHELL || process.env.CODEX_THREAD_ID || process.env.CODEX_CI) {
+    return "codex";
+  }
+  return "claude";
+}
+
+function installAgents(flags) {
+  const agent = String(flags.agent ?? defaultInstallAgent()).toLowerCase();
+  if (agent === "both" || agent === "all") {
+    return Object.keys(AGENT_SKILL_DIRS);
+  }
+  if (!AGENT_SKILL_DIRS[agent]) {
+    throw usageError("--agent must be claude, codex, or both");
+  }
+  return [agent];
+}
+
+function installTargetDirs(flags) {
+  if (flags.dir) {
+    return [{ agent: "custom", dir: path.resolve(flags.dir) }];
+  }
+  const scopeRoot = flags.global ? os.homedir() : process.cwd();
+  return installAgents(flags).map((agent) => ({
+    agent,
+    dir: path.join(scopeRoot, ...AGENT_SKILL_DIRS[agent]),
+  }));
+}
+
+function installScanDirs(flags) {
+  if (flags.dir) {
+    return [{ agent: "custom", scope: "custom", dir: path.resolve(flags.dir) }];
+  }
+  const scans = [];
+  for (const agent of Object.keys(AGENT_SKILL_DIRS)) {
+    scans.push({ agent, scope: "project", dir: path.join(process.cwd(), ...AGENT_SKILL_DIRS[agent]) });
+    scans.push({ agent, scope: "global", dir: path.join(os.homedir(), ...AGENT_SKILL_DIRS[agent]) });
+  }
+  return scans;
+}
+
+/** The catalog's row for a skill named by its address, uid, or id — or, when
+ * nothing answers to that name, the best search match for it. */
+async function skillDetail(api, ref) {
+  const direct = await api.json("GET /v1/skills/{ref}", { params: { ref } }).catch((error) => {
+    if (error.status === 404) return null;
+    throw error;
+  });
+  if (direct) return direct;
+  // `track=false` keeps ref resolution out of the search analytics.
+  const search = await api.json("GET /v1/skills/search", {
+    query: { q: ref, limit: 1, track: "false", source: SEARCH_SOURCE },
+  });
+  const skill = Array.isArray(search.skills) ? search.skills[0] : null;
+  if (!skill) {
+    throw new CliError(`skill not found on Terminus: ${ref}`);
+  }
+  return skill;
+}
+
+function skillDirName(skill) {
+  return slugify(skill.slug);
+}
+
+/** `name` is the skill's folder, which the frontmatter must match; `skill
+ * update` passes the folder it found so a renamed slug never moves it. */
+function pointerStubMarkdown(skill, address, name = skillDirName(skill)) {
+  const description = String(skill.description || `Terminus skill ${address}`)
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 1024);
+  return `---
+name: ${JSON.stringify(name)}
+description: ${JSON.stringify(description)}
+---
+
+# ${skill.name ?? name}
+
+This skill lives on the Terminus platform. Load it at use time instead of keeping a local copy.
+
+When this skill triggers, run:
+
+\`\`\`bash
+terminus skills use ${JSON.stringify(address)}
+\`\`\`
+
+If \`terminus\` is not on PATH, run \`npx -y @terminus-ai/cli skills use ${JSON.stringify(address)}\`.
+
+Read the printed TERMINUS SKILL CONTENT block and follow it as the active skill instructions. If those
+instructions reference supporting files, run \`terminus skills fetch ${JSON.stringify(address)}\` and read the files
+from the printed local cache path.
+`;
+}
+
+/** Whether Terminus hands out this skill's content: the same rule as the
+ * server's use door. */
+function skillContentIsOpen(skill) {
+  return skill.content_visibility === "open_source" || Boolean(skill.is_external);
+}
+
+/**
+ * A closed skill's content stays on Terminus, where it is used — metered,
+ * and for a paid skill, paid for. `skills fetch`, `files`, and `file` refuse
+ * one up front rather than fail halfway, unless the caller is the skill's
+ * owner, who reads their own files the way Terminus serves them.
+ */
+async function refuseClosedSkill(api, skill, action) {
+  if (skillContentIsOpen(skill)) return;
+  if (api.token && skill.owner_user_id && (await api.me()).id === skill.owner_user_id) return;
+  throw closedSkillError(skill, action);
+}
+
+function closedSkillError(skill, action) {
+  return new CliError(
+    `${skill.address} isn't open source: its content stays on Terminus, so terminus can't ${action}`,
+    { code: "forbidden" },
+  );
+}
+
+/** The use door's refusal of a closed skill, said as what it is. */
+function skillUseRefusal(reference) {
+  return (error) => {
+    if (error?.status !== 403) throw error;
+    throw new CliError(
+      `${reference} isn't open source: its content stays on Terminus, and \`terminus skills use\` loads only open-source skills`,
+      { code: "forbidden", status: error.status, apiCode: error.apiCode, details: error.details },
+    );
+  };
+}
+
+async function writeLocalSkillPackage(target, copy) {
+  await writeSkillFiles(target, copy.files);
+  if (copy.skillMd != null) {
+    await writeFile(path.join(target, "SKILL.md"), copy.skillMd);
+  }
+}
+
+/** A --local copy's content, checked before anything touches the disk: the
+ * package's files, plus the delivered markdown as SKILL.md when the package
+ * has none. Copying content to disk is a delivery, so it is counted like a
+ * use. */
+async function downloadSkillPackage(api, skill, address) {
+  const useResult = await useSkillAsAccount(api, skill.uid, address, { name: address });
+  const manifest = await skillFiles(api, skill.uid, { includeContent: true });
+  const files = (Array.isArray(manifest.files) ? manifest.files : []).filter(
+    (file) => file.content_available && file.content_base64 != null,
+  );
+  const hasSkillMd = files.some((file) => normalizePackageFilePath(file.path) === "SKILL.md");
+  const contentMarkdown = useResult.content ?? "";
+  if (!hasSkillMd && !contentMarkdown.trim()) {
+    throw new CliError("skill package did not include SKILL.md content");
+  }
+  return { files, skillMd: hasSkillMd ? null : contentMarkdown };
+}
+
+/** The `.terminus-install.json` beside every skill terminus installed: what
+ * `skills list`, `skills update`, and `skills uninstall` look for. */
+async function writeInstallManifest(skillDir, { mode, address, skill, base, agent, installedAt, updatedAt }) {
+  await writeFile(
+    path.join(skillDir, INSTALL_MANIFEST_NAME),
+    JSON.stringify(
+      {
+        installer: "terminus",
+        installer_version: CLI_VERSION,
+        mode,
+        address,
+        uid: skill.uid,
+        skill_id: skill.id,
+        change_hash: skill.change_hash,
+        api_base: base,
+        agent,
+        installed_at: installedAt,
+        ...(updatedAt ? { updated_at: updatedAt } : {}),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+async function installCommand(args) {
+  const flags = parseFlags(args, "skills install");
+  const ref = flags._.join(" ").trim();
+  if (!ref) {
+    throw commandUsageError("skills", { sub: "install" });
+  }
+
+  const api = await connect(flags);
+  const skill = await skillDetail(api, ref);
+  // Both kinds of install load through the use door — a pointer each time
+  // it is used, a --local copy as it is made — and that door serves only
+  // open-source skills, to everyone, their owner included.
+  if (!skillContentIsOpen(skill)) throw closedSkillError(skill, "install it");
+  const { address } = skill;
+  const dirName = skillDirName(skill);
+  const mode = flags.local ? "local" : "pointer";
+
+  // Every target is checked before a --local download counts a use.
+  const targets = installTargetDirs(flags).map((target) => ({ ...target, skillDir: path.join(target.dir, dirName) }));
+  for (const { skillDir } of flags.force ? [] : targets) {
+    if (await exists(skillDir)) {
+      throw new CliError(`already installed: ${skillDir} (terminus skills update refreshes it; --force replaces it)`);
+    }
+  }
+
+  let copy = null;
+  if (mode === "local") {
+    copy = await downloadSkillPackage(api, skill, address);
+  }
+
+  const installed = [];
+  for (const { agent, skillDir } of targets) {
+    await rm(skillDir, { recursive: true, force: true });
+    await mkdir(skillDir, { recursive: true });
+    if (mode === "pointer") {
+      await writeFile(path.join(skillDir, "SKILL.md"), pointerStubMarkdown(skill, address));
+    } else {
+      await writeLocalSkillPackage(skillDir, copy);
+    }
+    await writeInstallManifest(skillDir, {
+      mode,
+      address,
+      skill,
+      base: api.base,
+      agent,
+      installedAt: new Date().toISOString(),
+    });
+    installed.push({ agent, dir: skillDir });
+  }
+
+  emitJson(flags, { mode, address, name: dirName, installed }, () => {
+    for (const entry of installed) {
+      console.log(`Installed ${mode === "pointer" ? "pointer for" : "local copy of"} ${address} → ${entry.dir}`);
+    }
+    if (mode === "pointer") {
+      console.log("Content stays on Terminus and loads at use time (counted per use).");
+    } else {
+      console.log("Local copies do not count uses; run terminus skills update to refresh them.");
+    }
+  });
+}
+
+async function readInstallManifest(skillDir) {
+  try {
+    const manifest = JSON.parse(await readFile(path.join(skillDir, INSTALL_MANIFEST_NAME), "utf8"));
+    return manifest?.installer === "terminus" ? manifest : null;
+  } catch {
+    return null;
+  }
+}
+
+async function collectInstalledSkills(flags = {}) {
+  const found = [];
+  for (const scan of installScanDirs(flags)) {
+    let entries;
+    try {
+      entries = await readdir(scan.dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const skillDir = path.join(scan.dir, entry.name);
+      const manifest = await readInstallManifest(skillDir);
+      if (manifest) {
+        found.push({ name: entry.name, dir: skillDir, scope: scan.scope, manifest });
+      }
+    }
+  }
+  return found;
+}
+
+function installedSkillMatches(entry, ref) {
+  const wanted = ref.trim().toLowerCase();
+  const candidates = [
+    entry.name,
+    entry.manifest.address,
+    entry.manifest.uid,
+    entry.manifest.skill_id,
+  ];
+  return candidates.some((candidate) => String(candidate ?? "").toLowerCase() === wanted);
+}
+
+async function uninstallCommand(args) {
+  const flags = parseFlags(args, "skills uninstall");
+  const ref = flags._.join(" ").trim();
+  if (!ref) {
+    throw commandUsageError("skills", { sub: "uninstall" });
+  }
+
+  const installed = await collectInstalledSkills(flags);
+  const matches = installed.filter((entry) => installedSkillMatches(entry, ref));
+  if (matches.length === 0) {
+    throw new CliError(`no skill installed by terminus matches ${ref} (see terminus skills list)`);
+  }
+  const removed = [];
+  for (const entry of matches) {
+    await rm(entry.dir, { recursive: true, force: true });
+    removed.push({ address: entry.manifest.address ?? null, name: entry.name, dir: entry.dir, scope: entry.scope });
+  }
+  emitJson(flags, { removed }, () => {
+    for (const entry of removed) console.log(`Removed ${entry.address ?? entry.name} → ${entry.dir}`);
+  });
+}
+
+/** `terminus skills update [<skill>]`: brings what terminus installed in step
+ * with Terminus. A pointer already loads the latest instructions at every
+ * use, so only its stub is rewritten, and only when it would read
+ * differently (a new name, description, or address, or older wording). A
+ * --local copy downloads again when the skill's change hash moved, counted as
+ * a use like its install. A skill that is gone is reported and left alone. */
+async function updateCommand(args) {
+  const flags = parseFlags(args, "skills update");
+  const ref = flags._.join(" ").trim();
+  const installed = await collectInstalledSkills(flags);
+  const entries = ref ? installed.filter((entry) => installedSkillMatches(entry, ref)) : installed;
+  if (ref && entries.length === 0) {
+    throw new CliError(`no skill installed by terminus matches ${ref} (see terminus skills list)`);
+  }
+  if (entries.length === 0) {
+    emitJson(flags, { skills: [] }, () => {
+      console.log("No skills installed by terminus yet. Try: terminus skills install <skill> --agent claude");
+    });
+    return;
+  }
+
+  // One lookup, and at most one download, per skill, however many folders
+  // it is installed in. Signed in, like install: private catalog grants and
+  // the use door both need the account.
+  const context = {
+    api: await connect(flags),
+    details: new Map(),
+    copies: new Map(),
+  };
+  const skills = [];
+  for (const entry of entries) {
+    skills.push(await updateInstalledSkill(entry, context));
+  }
+  emitJson(flags, { skills }, () => printSkillUpdates(skills));
+  const failed = skills.filter((skill) => skill.status === "failed").length;
+  if (failed) {
+    throw new CliError(`${failed === 1 ? "1 skill" : `${failed} skills`} could not be updated`);
+  }
+}
+
+function memoized(cache, key, load) {
+  if (!cache.has(key)) {
+    cache.set(key, load());
+  }
+  return cache.get(key);
+}
+
+/** The catalog's current row for an installed skill, by the uid its install
+ * recorded (an address can be renamed). Unlike skillDetail this never falls
+ * back to search: a skill that is gone must not be swapped for a look-alike. */
+async function installedSkillDetail(api, ref) {
+  try {
+    return { skill: await api.json("GET /v1/skills/{ref}", { params: { ref } }) };
+  } catch (error) {
+    if (error.status === 404) return { problem: "It is no longer on Terminus." };
+    if (error.status === 403) return { problem: "You no longer have access to it." };
+    throw error;
+  }
+}
+
+async function updateInstalledSkill(entry, { api, details, copies }) {
+  const { manifest } = entry;
+  const mode = manifest.mode === "local" ? "local" : "pointer";
+  const report = (status, extra = {}) => ({
+    name: entry.name,
+    address: manifest.address ?? null,
+    dir: entry.dir,
+    scope: entry.scope,
+    mode,
+    status,
+    ...extra,
+  });
+  const ref = manifest.uid ?? manifest.skill_id ?? manifest.address;
+  if (!ref) {
+    return report("failed", { reason: "Its install record does not say which skill it is; install it again." });
+  }
+  const found = await memoized(details, ref, () => installedSkillDetail(api, ref));
+  if (!found.skill) {
+    return report("failed", { reason: `${found.problem} Remove it with: terminus skills uninstall ${entry.name}` });
+  }
+  const { skill } = found;
+  const address = skill.address;
+  const now = new Date().toISOString();
+  const record = {
+    mode,
+    address,
+    skill,
+    base: api.base,
+    agent: manifest.agent ?? null,
+    installedAt: manifest.installed_at ?? now,
+    updatedAt: now,
+  };
+
+  if (mode === "pointer") {
+    const stub = pointerStubMarkdown(skill, address, entry.name);
+    const skillMd = path.join(entry.dir, "SKILL.md");
+    if ((await readFile(skillMd, "utf8").catch(() => null)) === stub) {
+      return report("up_to_date", { address });
+    }
+    await writeFile(skillMd, stub);
+    await writeInstallManifest(entry.dir, record);
+    return report("updated", { address });
+  }
+
+  if (manifest.change_hash && manifest.change_hash === skill.change_hash) {
+    return report("up_to_date", { address });
+  }
+  if (!skillContentIsOpen(skill)) {
+    return report("failed", { address, reason: "It is no longer open source, so terminus cannot refresh this copy." });
+  }
+  const copy = await memoized(copies, skill.uid, () => downloadSkillPackage(api, skill, address));
+  await rm(entry.dir, { recursive: true, force: true });
+  await mkdir(entry.dir, { recursive: true });
+  await writeLocalSkillPackage(entry.dir, copy);
+  await writeInstallManifest(entry.dir, record);
+  return report("updated", { address });
+}
+
+function printSkillUpdates(skills) {
+  for (const skill of skills) {
+    const label = skill.address ?? skill.name;
+    if (skill.status === "updated") {
+      console.log(`Updated ${label} → ${skill.dir}`);
+    } else if (skill.status === "up_to_date") {
+      console.log(`Up to date: ${label} → ${skill.dir}`);
+    } else {
+      console.log(`Could not update ${label} → ${skill.dir}`);
+      console.log(`  ${skill.reason}`);
+    }
+  }
+}
+
+async function installedCommand(args) {
+  const flags = parseFlags(args, "skills list");
+  const installed = await collectInstalledSkills(flags);
+  emitJson(flags, { installed }, () => {
+    if (installed.length === 0) {
+      console.log("No skills installed by terminus yet. Try: terminus skills install <skill> --agent claude");
+      return;
+    }
+    console.log(`Installed Terminus skills (${installed.length}):`);
+    for (const entry of installed) {
+      const mode = entry.manifest.mode ?? "pointer";
+      console.log(`- ${entry.name} [${mode}, ${entry.scope}] ${entry.manifest.address ?? ""}`);
+      console.log(`  ${entry.dir}`);
+    }
+  });
+}
+
+function cacheRoot() {
+  return path.join(os.homedir(), ".terminus", "cache");
+}
+
+function sanitizeCacheSegment(value) {
+  return String(value ?? "unknown").replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 80) || "unknown";
+}
+
+async function fetchCommand(args) {
+  const flags = parseFlags(args, "skills fetch");
+  const ref = flags._.join(" ").trim();
+  if (!ref) {
+    throw commandUsageError("skills", { sub: "fetch" });
+  }
+
+  const api = await connect(flags);
+  const skill = await skillDetail(api, ref);
+  await refuseClosedSkill(api, skill, "download its files");
+  const { uid } = skill;
+  const revision = sanitizeCacheSegment(skill.change_hash?.slice(0, 16) || "latest");
+  const cacheDir = path.join(cacheRoot(), `${sanitizeCacheSegment(uid)}@${revision}`);
+  const marker = path.join(cacheDir, ".terminus-cache.json");
+
+  let fromCache = !flags.refresh && (await exists(marker));
+  let fileCount;
+  if (fromCache) {
+    fileCount = JSON.parse(await readFile(marker, "utf8")).file_count;
+  } else {
+    const manifest = await skillFiles(api, uid, { includeContent: true });
+    const files = (Array.isArray(manifest.files) ? manifest.files : []).filter(
+      (file) => file.content_available && file.content_base64 != null,
+    );
+    if (files.length === 0) {
+      throw new CliError(`skill has no downloadable files: ${ref}`);
+    }
+    await rm(cacheDir, { recursive: true, force: true });
+    await writeSkillFiles(cacheDir, files);
+    fileCount = files.length;
+    await writeFile(
+      marker,
+      JSON.stringify(
+        {
+          uid,
+          address: skill.address,
+          change_hash: skill.change_hash,
+          file_count: fileCount,
+          cached_at: new Date().toISOString(),
+        },
+        null,
+        2,
+      ),
+    );
+  }
+
+  emitJson(
+    flags,
+    { skill_ref: uid, cache_dir: cacheDir, file_count: fileCount, from_cache: fromCache },
+    () => {
+      console.log(`Skill files ${fromCache ? "already cached" : "cached"}: ${cacheDir}`);
+      console.log(`Files: ${formatNumber(fileCount)} (read them from this directory; safe to delete anytime)`);
+    },
+  );
+}
+
+/**
+ * `terminus clone <@handle/skill>` for a skill this account owns — the skill
+ * half of the app-family clone in apps.mjs, which calls this when no owned
+ * app, agent, or service answers the address. Returns null when the account
+ * owns no such skill, so the caller can report one "nothing matches" error.
+ *
+ * A skill's draft is written through `PATCH /dashboard/developer/skills/{id}`
+ * (each change a commit in its history), so the local loop is clone → edit →
+ * `terminus push`, and the web publishes it.
+ */
+async function cloneOwnedSkill({ api, flags, ref, dir: requestedDir, extra = {} }) {
+  const skill = await ownedSkill(api, ref, flags, { missing: null });
+  if (!skill) {
+    return null;
+  }
+
+  const skillRef = skill.uid;
+  const manifest = await skillFiles(api, skillRef, { includeContent: true, developer: true });
+  const packageFiles = Array.isArray(manifest.files) ? manifest.files : [];
+
+  const address = skill.address;
+  const dir = path.resolve(requestedDir ?? skill.slug);
+  await mkdir(dir, { recursive: true });
+  if ((await readdir(dir)).length) {
+    throw new CliError(`${dir} is not empty — clone into a fresh directory`);
+  }
+
+  let packageSkillMarkdown = null;
+  const files = [];
+  for (const file of packageFiles) {
+    const relative = normalizePackageFilePath(file.path);
+    const bytes = skillFileBytes(
+      file.content_available && file.content_base64 != null
+        ? file
+        : await remoteSkillFile(api, skillRef, relative),
+    );
+    // SKILL.md is the skill itself rather than one of its files: the platform
+    // keeps it as `content_markdown` (frontmatter parsed off), and web edits
+    // never resend it, so the package copy is only good for its frontmatter.
+    if (relative === "SKILL.md") {
+      packageSkillMarkdown = bytes.toString("utf8");
+      continue;
+    }
+    files.push({ relative, bytes });
+  }
+  files.unshift({
+    relative: "SKILL.md",
+    bytes: Buffer.from(skillWorkingCopyMarkdown(skill, packageSkillMarkdown), "utf8"),
+  });
+
+  for (const file of files) {
+    const target = path.join(dir, ...file.relative.split("/"));
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, file.bytes);
+  }
+  // Like git's origin/main: the clone knows which commit it holds, so push
+  // can refuse to clobber later ones and pull can merge them in.
+  const entries = files
+    .map((file) => ({ path: file.relative, sha256: sha256(file.bytes) }))
+    .sort((left, right) => left.path.localeCompare(right.path));
+  const history = await skillHistory(api, skillRef, 1).catch(() => ({}));
+  await recordSkillSync(dir, {
+    skill,
+    commit: history.head_revision_id ?? null,
+    draft: entries,
+    local: entries,
+  });
+
+  const { status } = skill;
+  const result = {
+    ...extra,
+    address,
+    dir,
+    files: files.length,
+    kind: "skill",
+    status,
+    publish_url: creationPageUrl(flags, skill.uid),
+  };
+  emitJson(flags, result, () => {
+    console.log(`Cloned ${address} → ${dir} (${formatNumber(files.length)} file${files.length === 1 ? "" : "s"})`);
+    console.log("Next:");
+    console.log(`  cd ${path.relative(process.cwd(), dir) || "."}`);
+    console.log("  terminus push             # send your changes to its draft");
+    console.log(status === "draft"
+      ? `Publish it on the web when it is ready: ${result.publish_url}`
+      : `It is published: pushes land on its draft until you publish again — ${result.publish_url}`);
+  });
+  return result;
+}
+
+async function remoteSkillFile(api, skillRef, filePath) {
+  const result = await skillFiles(api, skillRef, {
+    includeContent: true,
+    developer: true,
+    path: filePath,
+  });
+  const files = Array.isArray(result.files) ? result.files : [];
+  // The path door answers with that one file; match it by name anyway so a
+  // server that answers with the whole package cannot cross the contents over.
+  const file = files.find((candidate) => String(candidate?.path ?? "").replaceAll("\\", "/") === filePath);
+  if (!file) {
+    throw new CliError(`remote skill file not found: ${filePath}`);
+  }
+  return file;
+}
+
+function normalizeSkillReference(value) {
+  const text = String(value ?? "").trim().toLowerCase();
+  return text.startsWith("@") ? text.slice(1) : text;
+}
+
+/** Every name one skill answers to: uid, id, slug, and address (with or
+ * without the leading `@`). */
+function skillReferenceMatches(skill, ref) {
+  const wanted = normalizeSkillReference(ref);
+  if (!wanted) {
+    return false;
+  }
+  return [skill?.uid, skill?.id, skill?.slug, skill?.address, skill?.address_path]
+    .some((candidate) => candidate && normalizeSkillReference(candidate) === wanted);
+}
+
+/**
+ * The SKILL.md a working copy gets. The platform stores a skill's markdown
+ * body without its frontmatter, so the file is rebuilt: the package copy's
+ * own frontmatter when the skill was published from a package, otherwise the
+ * two fields the platform keeps, plus the `id` a later `terminus push`
+ * resolves back to this exact skill.
+ */
+function skillWorkingCopyMarkdown(skill, packageSkillMarkdown, options = {}) {
+  const frontmatter = skillWorkingCopyFrontmatter(skill, packageSkillMarkdown, options);
+  const body = String(skill.content_markdown ?? "").trim();
+  return body ? `${frontmatter}\n\n${body}\n` : `${frontmatter}\n`;
+}
+
+function skillWorkingCopyFrontmatter(skill, packageSkillMarkdown, { linked = true } = {}) {
+  const metadata = packageSkillMarkdown ? parseFrontmatterMetadata(packageSkillMarkdown) : {};
+  let lines = frontmatterLines(packageSkillMarkdown);
+  // Name and description are the platform's copies; a rename on the web must
+  // not travel back as a rename to the name the package still carries.
+  if (skill.name?.trim() && metadata.name !== skill.name.trim()) {
+    lines = withFrontmatterEntry(lines, "name", skill.name.trim());
+  }
+  if (skill.description?.trim() && metadata.description !== skill.description.trim()) {
+    lines = withFrontmatterEntry(lines, "description", skill.description.trim());
+  }
+  // The publish door takes uid, id, slug, or address; record the id unless the
+  // package already names this same skill, so an edited name still updates it.
+  // A read-only copy of someone else's skill records none: it is linked to
+  // nothing this account can push to.
+  if (!linked) {
+    lines = lines.filter((line) => frontmatterLineKey(line) !== "id");
+  } else if (!skillReferenceMatches(skill, metadata.id)) {
+    lines = withFrontmatterEntry(lines, "id", skill.id ?? skill.uid);
+  }
+  return ["---", ...lines, "---"].join("\n");
+}
+
+function frontmatterLines(content) {
+  const match = String(content ?? "").match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  return match ? match[1].split(/\r?\n/) : [];
+}
+
+function frontmatterLineKey(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) {
+    return null;
+  }
+  const index = trimmed.indexOf(":");
+  return index < 0 ? null : trimmed.slice(0, index).trim();
+}
+
+function withFrontmatterEntry(lines, key, value) {
+  const entry = `${key}: ${JSON.stringify(String(value))}`;
+  const index = lines.findIndex((line) => frontmatterLineKey(line) === key);
+  return index < 0 ? [...lines, entry] : lines.map((line, at) => (at === index ? entry : line));
+}
+
+async function initCommand(args) {
+  const flags = parseFlags(args, "init");
+  const kindAliases = new Map([
+    ["skill", "skill"], ["skills", "skill"],
+    ["app", "app"], ["apps", "app"],
+    ["agent", "agent"], ["agents", "agent"],
+    ["service", "service"], ["services", "service"],
+  ]);
+  const positionalKind = kindAliases.get(String(flags._[0] ?? "").toLowerCase());
+  const requestedKind = flags.kind
+    ? (kindAliases.get(String(flags.kind).toLowerCase()) ?? String(flags.kind).toLowerCase())
+    : null;
+  if (positionalKind && requestedKind && positionalKind !== requestedKind) {
+    throw usageError(`positional kind '${positionalKind}' conflicts with --kind '${requestedKind}'`);
+  }
+  const kind = positionalKind ?? requestedKind ?? "skill";
+  const targetIndex = positionalKind ? 1 : 0;
+  if (flags._.length > targetIndex + 1) {
+    throw usageError("init accepts at most one target directory");
+  }
+  const target = path.resolve(flags._[targetIndex] ?? ".");
+  if (kind !== "skill") {
+    await (await import("./apps.mjs")).initAppCommand(target, kind, flags);
+    return;
+  }
+  const skillPath = path.join(target, "SKILL.md");
+  // A skill cloned from an empty draft is frontmatter alone: which skill it
+  // is, with its name and description. init writes the body around them and
+  // never drops the id a skill folder is linked by.
+  const existing = (await exists(skillPath)) ? await readFile(skillPath, "utf8") : null;
+  const existingMeta = existing === null ? {} : parseFrontmatterMetadata(existing);
+  const bodyless = existing !== null
+    && !existing.replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/, "").trim();
+  if (!flags.force && existing !== null && !bodyless) {
+    throw new CliError(`SKILL.md already exists in ${target} (use --force to overwrite)`);
+  }
+
+  const name = flags.name ? slugify(flags.name) : existingMeta.name ?? slugify(path.basename(target));
+  const description = String(
+    flags.description ?? existingMeta.description
+      ?? "Replace with one sentence describing when an agent should use this skill.",
+  ).trim();
+  const markdown = initialSkillMarkdown(name, description);
+  await mkdir(target, { recursive: true });
+  await writeFile(skillPath, existingMeta.id ? withSkillId(markdown, existingMeta.id) : markdown);
+
+  emitJson(flags, { path: skillPath, name, description, id: existingMeta.id ?? null }, () => {
+    console.log(`Created ${skillPath}`);
+    console.log("Next steps:");
+    console.log("  1. Edit SKILL.md; the frontmatter name/description drive search and agent triggering.");
+    console.log(`  2. terminus validate ${target}`);
+    if (!existingMeta.id) {
+      console.log(`  3. Create it on the web (${newCreationUrl(flags)}), then: terminus remote add <address> ${target}`);
+    }
+    console.log(`  ${existingMeta.id ? 3 : 4}. terminus push ${target}    # upload it; publish it on the web`);
+  });
+}
+
+function initialSkillMarkdown(name, description) {
+  return `---
+name: ${JSON.stringify(name)}
+description: ${JSON.stringify(description)}
+---
+
+# ${name}
+
+Explain step by step how an agent should perform this skill. Write instructions,
+not marketing: assume the reader is an AI coding agent that will follow them literally.
+
+## When to use
+
+Describe the trigger conditions in the frontmatter description above; expand edge cases here.
+
+## Steps
+
+1. First step.
+2. Second step.
+
+## Supporting files (optional)
+
+Reference extra files with relative paths (for example \`references/style.md\` or
+\`scripts/export.sh\`). Files referenced from SKILL.md are packaged automatically by
+\`terminus push\`; unreferenced files are dropped.
+`;
+}
+
+/** "Winston Gao (@winstongu)": the display name and the address people see
+ * on your creations (the publisher handle, else the username). */
+function accountName(session) {
+  const displayName = presentValue(
+    session.display_name ?? session.profile?.display_name ?? session.user?.display_name,
+  );
+  const handle = presentValue(
+    session.profile?.publisher_handle ?? session.publisher_handle
+      ?? session.username ?? session.profile?.username ?? session.user?.username,
+  )?.replace(/^@/, "");
+  if (displayName && handle) return `${displayName} (@${handle})`;
+  return handle ? `@${handle}` : displayName ?? "";
+}
+
+function loginLabel(session) {
+  const name = accountName(session);
+  return name ? `Logged in as ${name}` : "Logged in";
+}
+
+function safeStatusResponse(base, login, savedSession, artifactSummary = null) {
+  const output = {
+    authenticated: true,
+    auth_method: savedSession?.auth_method ?? "browser",
+    api_base: base,
+    expires_at: savedSession?.expires_at ?? login.expires_at ?? null,
+  };
+  const profile = login.profile ?? {};
+  return {
+    ...output,
+    device: {
+      name: savedSession?.device_name ?? null,
+      platform: savedSession?.platform ?? null,
+      client_version: savedSession?.client_version ?? null,
+    },
+    user: {
+      id: profile.id ?? login.user?.id ?? null,
+      display_name: profile.display_name ?? login.display_name ?? null,
+      username: profile.username ?? login.username ?? login.user?.username ?? null,
+      publisher_handle: profile.publisher_handle ?? null,
+      avatar_url: Object.hasOwn(profile, "avatar_url")
+        ? profile.avatar_url
+        : login.user?.avatar_url ?? null,
+    },
+    ...(artifactSummary ? { artifacts: artifactSummary } : {}),
+  };
+}
+
+function printSearchResults(results) {
+  const skills = Array.isArray(results.skills) ? results.skills : [];
+  console.log(
+    `Terminus search: ${JSON.stringify(results.query ?? "")} (${formatNumber(results.result_count ?? skills.length)} results)`,
+  );
+  if (skills.length === 0) {
+    console.log("No matching skills.");
+    return;
+  }
+
+  skills.forEach((skill, index) => {
+    const rank = skill.search_rank ?? index + 1;
+    if (index > 0) {
+      console.log("");
+    }
+    console.log(`${rank}. ${skill.name ?? "Untitled skill"}`);
+    for (const row of searchResultRows(skill)) {
+      printSearchResultField(row.label, row.value);
+    }
+    const summary = skill.description;
+    if (summary) {
+      printSearchResultField("Summary", summary);
+    }
+  });
+}
+
+function selectedSkillIndex(flags, skillCount) {
+  if (flags.use_first) {
+    return 0;
+  }
+  if (flags.select == null) {
+    return null;
+  }
+  const selected = Number.parseInt(flags.select, 10);
+  if (!Number.isInteger(selected) || selected < 1 || selected > skillCount) {
+    throw usageError(`--select must be between 1 and ${skillCount}`);
+  }
+  return selected - 1;
+}
+
+async function promptSkillSelection(skillCount) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw usageError("terminus skills use needs a selection in non-interactive shells; pass --select <n> or --use-first");
+  }
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+  try {
+    while (true) {
+      const answer = (await promptLine(rl, "Choose a skill number, or press Enter to cancel: ")).trim();
+      if (!answer) {
+        return null;
+      }
+      const selected = Number.parseInt(answer, 10);
+      if (Number.isInteger(selected) && selected >= 1 && selected <= skillCount) {
+        return selected - 1;
+      }
+      console.log(`Enter a number from 1 to ${skillCount}.`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function promptLine(rl, prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, resolve);
+  });
+}
+
+/** One counted use of a skill, as the account: the door answers with its
+ * content. `searchEventId` ties the use to the search it was picked from;
+ * `name` is how a refusal names the skill (its address, when known). */
+function useSkillAsAccount(api, reference, query, { searchEventId, name } = {}) {
+  return api.json("POST /v1/terminus/skills/use", {
+    body: { reference, query, search_event_id: searchEventId },
+  }).catch(skillUseRefusal(name ?? reference));
+}
+
+/** The account use door answers flat; reshape it for the shared printer. */
+function accountUseResult(body) {
+  return {
+    use_id: body.use_id,
+    counted: true,
+    skill: {
+      name: body.name,
+      address: body.address,
+      uid: body.uid,
+      description: body.description,
+      content_markdown: body.content,
+    },
+  };
+}
+
+function printSkillUseResult(result) {
+  const skill = result.skill ?? {};
+  const address = skillReference(skill);
+  const content = typeof skill.content_markdown === "string" ? skill.content_markdown.trimEnd() : "";
+
+  console.log(`Selected: ${skill.name ?? "Terminus skill"} ${address}`);
+  console.log(`Use ID: ${result.use_id ?? "unknown"} (${result.counted ? "counted" : "not counted"})`);
+  const metadata = searchResultMetadata(skill);
+  if (metadata) {
+    console.log(metadata);
+  }
+  const remoteRef = skill.uid;
+  if (remoteRef) {
+    console.log(`Supporting files: terminus skills fetch ${remoteRef} (or terminus skills files ${remoteRef} to browse remotely)`);
+  }
+  const summary = skill.description;
+  if (summary) {
+    console.log(summary);
+  }
+  if (!content.trim()) {
+    console.log("No skill content was returned.");
+    return;
+  }
+  console.log("");
+  console.log("--- TERMINUS SKILL CONTENT START ---");
+  console.log(content);
+  console.log("--- TERMINUS SKILL CONTENT END ---");
+}
+
+function searchResultMetadata(skill) {
+  const parts = [];
+  if (skill.publisher_handle) {
+    parts.push(`publisher ${skill.publisher_handle}`);
+  }
+  if (typeof skill.external_repository_stars === "number") {
+    parts.push(`${formatNumber(skill.external_repository_stars)} stars`);
+  }
+  const updated = skill.external_repository_updated_at ?? skill.external_last_indexed_at ?? skill.updated_at;
+  if (updated) {
+    parts.push(`updated ${formatDate(updated)}`);
+  }
+  if (skill.version || skill.release_version) {
+    parts.push(`version ${skill.release_version ?? skill.version}`);
+  }
+  if (skill.billing_mode && skill.billing_mode !== "free") {
+    parts.push(`billing ${skill.billing_mode}`);
+  } else if (skill.pricing) {
+    parts.push(`pricing ${skill.pricing}`);
+  }
+  return parts.join(" · ");
+}
+
+function searchResultRows(skill) {
+  const rows = [{ label: "Address", value: skillReference(skill) }];
+  if (skill.publisher_handle) {
+    rows.push({ label: "Publisher", value: skill.publisher_handle });
+  }
+  if (typeof skill.external_repository_stars === "number") {
+    rows.push({ label: "Stars", value: formatNumber(skill.external_repository_stars) });
+  }
+  const updated = skill.external_repository_updated_at ?? skill.external_last_indexed_at ?? skill.updated_at;
+  if (updated) {
+    rows.push({ label: "Updated", value: formatDate(updated) });
+  }
+  if (skill.version || skill.release_version) {
+    rows.push({ label: "Version", value: skill.release_version ?? skill.version });
+  }
+  if (skill.billing_mode && skill.billing_mode !== "free") {
+    rows.push({ label: "Billing", value: skill.billing_mode });
+  } else if (skill.pricing) {
+    rows.push({ label: "Pricing", value: skill.pricing });
+  }
+  return rows;
+}
+
+function printSearchResultField(label, value) {
+  const labelText = `${label}:`.padEnd(10);
+  const firstPrefix = `   ${labelText} `;
+  const nextPrefix = " ".repeat(visibleWidth(firstPrefix));
+  for (const line of wrapText(value, { firstPrefix, nextPrefix })) {
+    console.log(line);
+  }
+}
+
+function wrapText(value, { firstPrefix = "", nextPrefix = "", columns = outputColumns() } = {}) {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (!text) {
+    return [];
+  }
+
+  const lines = [];
+  let current = "";
+  let limit = Math.max(20, columns - visibleWidth(firstPrefix));
+
+  for (const word of text.split(" ")) {
+    if (!word) {
+      continue;
+    }
+
+    if (!current) {
+      if (visibleWidth(word) <= limit) {
+        current = word;
+        continue;
+      }
+      const chunks = splitByDisplayWidth(word, limit);
+      lines.push(...chunks.slice(0, -1));
+      current = chunks.at(-1) ?? "";
+      limit = Math.max(20, columns - visibleWidth(nextPrefix));
+      continue;
+    }
+
+    if (visibleWidth(current) + 1 + visibleWidth(word) <= limit) {
+      current = `${current} ${word}`;
+      continue;
+    }
+
+    lines.push(current);
+    current = "";
+    limit = Math.max(20, columns - visibleWidth(nextPrefix));
+
+    if (visibleWidth(word) <= limit) {
+      current = word;
+    } else {
+      const chunks = splitByDisplayWidth(word, limit);
+      lines.push(...chunks.slice(0, -1));
+      current = chunks.at(-1) ?? "";
+    }
+  }
+
+  if (current) {
+    lines.push(current);
+  }
+
+  return lines.map((line, index) => `${index === 0 ? firstPrefix : nextPrefix}${line}`);
+}
+
+function splitByDisplayWidth(value, limit) {
+  const chunks = [];
+  let current = "";
+  for (const char of Array.from(String(value))) {
+    if (current && visibleWidth(current) + visibleWidth(char) > limit) {
+      chunks.push(current);
+      current = char;
+    } else {
+      current += char;
+    }
+  }
+  if (current) {
+    chunks.push(current);
+  }
+  return chunks;
+}
+
+function outputColumns() {
+  const explicit = Number.parseInt(process.env.COLUMNS ?? "", 10);
+  const columns = Number.isInteger(explicit) ? explicit : process.stdout.columns;
+  if (!Number.isInteger(columns) || columns <= 0) {
+    return 100;
+  }
+  return Math.max(60, Math.min(columns, 120));
+}
+
+function visibleWidth(value) {
+  let width = 0;
+  for (const char of Array.from(String(value))) {
+    width += codePointWidth(char.codePointAt(0));
+  }
+  return width;
+}
+
+function codePointWidth(codePoint) {
+  if (codePoint == null || codePoint === 0) {
+    return 0;
+  }
+  if (codePoint < 32 || (codePoint >= 0x7f && codePoint < 0xa0)) {
+    return 0;
+  }
+  if (
+    (codePoint >= 0x0300 && codePoint <= 0x036f) ||
+    (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
+    (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
+    (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
+    (codePoint >= 0xfe20 && codePoint <= 0xfe2f)
+  ) {
+    return 0;
+  }
+  return isFullwidthCodePoint(codePoint) ? 2 : 1;
+}
+
+function isFullwidthCodePoint(codePoint) {
+  return (
+    codePoint >= 0x1100 &&
+    (codePoint <= 0x115f ||
+      codePoint === 0x2329 ||
+      codePoint === 0x232a ||
+      (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+      (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+      (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+      (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+      (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+      (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+      (codePoint >= 0xffe0 && codePoint <= 0xffe6))
+  );
+}
+
+function formatDate(value) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return String(value);
+  }
+  return date.toISOString().slice(0, 10);
+}
+
+function looksLikeSkillReference(value) {
+  const text = String(value).trim();
+  if (!text || text.includes(" ")) {
+    return false;
+  }
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(text)) {
+    return true;
+  }
+  return /^@?[a-z0-9][a-z0-9_.-]*\/[a-z0-9_.:@-]+$/i.test(text);
+}
+
+/** The package files behind a skill. `developer: true` reads the owner's own
+ * door, which serves a skill's files whatever its source visibility; the
+ * catalog door is the public one every read command uses. */
+function skillFiles(api, skillRef, { includeContent = false, path: filePath, developer = false } = {}) {
+  return api.json(
+    developer ? "GET /v1/dashboard/developer/skills/{ref}/skill-files" : "GET /v1/skills/{ref}/skill-files",
+    {
+      params: { ref: skillRef },
+      query: { include_content: includeContent ? "true" : "false", path: filePath },
+    },
+  );
+}
+
+function printSkillFileManifest(skillRef, result) {
+  const files = Array.isArray(result.files) ? result.files : [];
+  console.log(`Remote skill files: ${skillRef} (${formatNumber(files.length)} files)`);
+  if (files.length === 0) {
+    console.log("No skill files.");
+    return;
+  }
+  for (const file of files) {
+    const size = typeof file.size_bytes === "number" ? ` ${formatNumber(file.size_bytes)} bytes` : "";
+    const type = file.content_type ? ` ${file.content_type}` : "";
+    console.log(`- ${file.path}${size}${type}`);
+  }
+}
+
+function printSkillFileContent(skillRef, file, content) {
+  console.log(`Remote skill file: ${skillRef}/${file.path}`);
+  if (file.content_type) {
+    console.log(`Content-Type: ${file.content_type}`);
+  }
+  if (typeof file.size_bytes === "number") {
+    console.log(`Size: ${formatNumber(file.size_bytes)} bytes`);
+  }
+  console.log("");
+  console.log("--- TERMINUS REMOTE FILE START ---");
+  console.log(content);
+  console.log("--- TERMINUS REMOTE FILE END ---");
+}
+
+function skillFileBytes(file) {
+  if (!file.content_available || !file.content_base64) {
+    throw new CliError(`remote skill file content is not available: ${file.path ?? "unknown"}`);
+  }
+  return Buffer.from(file.content_base64, "base64");
+}
+
+function skillFileText(file) {
+  return skillFileBytes(file).toString("utf8");
+}
+
+function formatNumber(value) {
+  return new Intl.NumberFormat("en-US").format(Number.isFinite(Number(value)) ? Number(value) : 0);
+}
+
+async function validateSkillCommand(args) {
+  const flags = parseFlags(args, "validate");
+  const target = flags._[0] ?? ".";
+  const packages = await validatePath(target, SKILL_PACKAGE_POLICY);
+  const response = {
+    path: path.resolve(target),
+    skill_count: packages.length,
+    skills: packages.map(packageSummary),
+  };
+  emitJson(flags, response, () => {
+    for (const pkg of response.skills) {
+      console.log(`Valid: ${pkg.name} (${pkg.file_count} files, ${pkg.total_bytes} bytes)`);
+    }
+  });
+}
+
+/**
+ * A skill of yours, by the uid, id, slug, or address a folder names — the
+ * owner's door answers only the caller's own skills. One that is not yours
+ * is refused with the web hint, or answered as `missing` when a caller asks
+ * for that instead. The door also knows the catalog rows of your apps,
+ * agents, and services; those are not skills.
+ */
+async function ownedSkill(api, ref, flags, options = {}) {
+  let found;
+  try {
+    found = await api.json("GET /v1/dashboard/developer/skills/{ref}", { params: { ref } });
+  } catch (error) {
+    if (error.status !== 404) throw error;
+    if (Object.hasOwn(options, "missing")) return options.missing;
+    throw new CliError(`${ref} is not one of your skills on Terminus — ${notConnectedHint(flags)}`);
+  }
+  const { skill } = found;
+  if (skill.kind !== "skill") {
+    throw new CliError(`${ref} is ${skill.kind === "app" || skill.kind === "agent" ? `an ${skill.kind}` : `a ${skill.kind}`}, not a skill`);
+  }
+  return skill;
+}
+
+/* ── A skill folder as a working copy ─────────────────────────────────── */
+
+/**
+ * A skill folder against the skill it is linked to: which commit it matches,
+ * what it holds now, and what the skill's draft holds.
+ *
+ * Apps keep their files in a package manifest; a skill keeps SKILL.md — the
+ * skill itself, which the platform stores as its markdown — plus the files it
+ * references. Everything else here is the same working copy the app family
+ * has: `.terminus/sync.json` remembers the commit, `status`, `diff`, `log`,
+ * `pull` and `restore` read against it, and `push` refuses to clobber commits
+ * it has not seen.
+ */
+async function skillWorkingCopy(flags, { dir: requestedDir, action = "status" } = {}) {
+  const dir = path.resolve(requestedDir ?? ".");
+  const skillPath = path.join(dir, "SKILL.md");
+  if (!(await exists(skillPath))) {
+    throw usageError(
+      `no skill in ${dir} (no SKILL.md)\n`
+      + `${action} reads a working copy against the creation it is linked to.`,
+    );
+  }
+  const packages = await validatePath(dir, SKILL_PACKAGE_POLICY);
+  if (packages.length !== 1) {
+    throw new CliError(`${action} takes one skill at a time; ${dir} holds ${packages.length}`);
+  }
+  const [pkg] = packages;
+  const record = await readSyncRecord(dir);
+  const ref = String(pkg.metadata.id ?? "").trim() || record?.id;
+  if (!ref) {
+    throw new CliError(`this folder is not connected to a skill on Terminus — ${notConnectedHint(flags)}`);
+  }
+  const api = await connect(flags);
+  const skill = await ownedSkill(api, ref, flags);
+  return { dir, pkg, record, api, skill, ref: skill.uid };
+}
+
+/** What the folder holds, as the sync record counts files. */
+function localSkillEntries(pkg) {
+  return pkg.files
+    .map((file) => ({ path: normalizePackageFilePath(file.path), sha256: sha256(file.contentBytes) }))
+    .sort((left, right) => left.path.localeCompare(right.path));
+}
+
+/**
+ * The skill's draft as a folder holds it: its package files, and SKILL.md
+ * rebuilt from the platform's copy the way `clone` writes it.
+ *
+ * `at` pins an earlier commit by its change hash, which is how a three-way
+ * merge reads the state both sides started from.
+ */
+async function remoteSkillTree(api, skill, { at } = {}) {
+  const ref = at ? `${skill.address}@${at}` : skill.uid;
+  const manifest = await skillFiles(api, ref, { includeContent: true, developer: true });
+  const bytes = new Map();
+  let packageSkillMarkdown = null;
+  for (const file of Array.isArray(manifest.files) ? manifest.files : []) {
+    const relative = normalizePackageFilePath(file.path);
+    const content = skillFileBytes(
+      file.content_available && file.content_base64 != null
+        ? file
+        : await remoteSkillFile(api, ref, relative),
+    );
+    // SKILL.md is the skill itself, not one of its files: the platform keeps
+    // it as content_markdown, so the folder's copy is rebuilt rather than
+    // downloaded, exactly as `terminus clone` writes it.
+    if (relative === "SKILL.md") packageSkillMarkdown = content.toString("utf8");
+    else bytes.set(relative, content);
+  }
+  bytes.set("SKILL.md", Buffer.from(skillWorkingCopyMarkdown(skill, packageSkillMarkdown), "utf8"));
+  const entries = [...bytes.keys()]
+    .sort((left, right) => left.localeCompare(right))
+    .map((file) => ({ path: file, sha256: sha256(bytes.get(file)) }));
+  return { entries, bytes, read: (entry) => bytes.get(entry.path) ?? null };
+}
+
+/** The skill's history, newest first, and where its draft stands. */
+function skillHistory(api, ref, limit = 100) {
+  return api.json("GET /v1/dashboard/developer/skills/{ref}/revisions", {
+    params: { ref },
+    query: { limit },
+  });
+}
+
+/** The commits recorded after `since`, and whether it is in the history at
+ *  all — what a folder has not pulled. */
+function skillCommitsSince(listing, since) {
+  const revisions = listing.revisions ?? [];
+  if (!since) return { commits: revisions, found: false };
+  const index = revisions.findIndex((revision) => revision.id === since);
+  return index === -1
+    ? { commits: revisions, found: false }
+    : { commits: revisions.slice(0, index), found: true };
+}
+
+async function recordSkillSync(dir, { skill, commit, draft, local }) {
+  const localByKey = byKey(local);
+  await writeSyncRecord(dir, {
+    source: "draft",
+    kind: "skill",
+    address: skill.address,
+    id: skill.uid,
+    commit: commit ?? null,
+    // The content the commit holds: how an earlier state is fetched back.
+    change_hash: skill.change_hash,
+    files: draft.map((entry) => ({
+      path: entry.path,
+      draft: entry.sha256,
+      local: localByKey.get(entryKey(entry))?.sha256 ?? entry.sha256,
+    })),
+  });
+}
+
+/**
+ * `terminus clone <@handle/skill>` for someone else's open-source skill —
+ * a read-only copy, the way git clones a public repository you cannot push
+ * to. The app family's clone in apps.mjs calls this when the address is a
+ * skill nobody in this account owns.
+ *
+ * Returns false when the skill's source is closed, so the caller reports one
+ * honest error instead of writing half a folder.
+ */
+async function cloneSkillCopy({ api, flags, detail, dir: requestedDir, extra = {} }) {
+  if (!skillContentIsOpen(detail)) return false;
+  const { address } = detail;
+  const tree = await publicSkillTree(api, detail.uid, detail);
+  const dir = path.resolve(requestedDir ?? detail.slug);
+  await mkdir(dir, { recursive: true });
+  if ((await readdir(dir)).length) throw new CliError(`${dir} is not empty — clone into a fresh directory`);
+  for (const entry of tree.entries) {
+    const target = path.join(dir, ...entry.path.split("/"));
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, tree.read(entry));
+  }
+  const label = detail.release_version || detail.version || "";
+  await writeSyncRecord(dir, {
+    source: "release",
+    kind: "skill",
+    address,
+    id: detail.uid,
+    release: { version: label, label },
+    change_hash: detail.change_hash,
+    files: tree.entries.map((entry) => ({ path: entry.path, draft: entry.sha256, local: entry.sha256 })),
+  });
+  const summary = {
+    ...extra,
+    address,
+    kind: "skill",
+    dir,
+    files: tree.entries.length,
+    release: label || null,
+    read_only: true,
+  };
+  emitJson(flags, summary, () => {
+    const at = label ? ` ${creationVersion(label)}` : "";
+    console.log(`Cloned ${address}${at} → ${dir} (${tree.entries.length} file${tree.entries.length === 1 ? "" : "s"}).`);
+    console.log("It isn't yours, so this copy can't be pushed. `terminus pull` brings in its newer releases.");
+    console.log(`To make changes you can publish, fork it instead: terminus fork ${address}`);
+  });
+  return summary;
+}
+
+/** An open-source skill as a folder holds it, from the public doors. */
+async function publicSkillTree(api, skillRef, skill) {
+  const manifest = await skillFiles(api, skillRef, { includeContent: true });
+  const bytes = new Map();
+  let packageSkillMarkdown = null;
+  for (const file of Array.isArray(manifest.files) ? manifest.files : []) {
+    const relative = normalizePackageFilePath(file.path);
+    const content = skillFileBytes(file);
+    if (relative === "SKILL.md") packageSkillMarkdown = content.toString("utf8");
+    else bytes.set(relative, content);
+  }
+  // A copy of someone else's skill carries no `id:`: it is not linked to
+  // anything this account can push to.
+  const markdown = skillWorkingCopyMarkdown(skill, packageSkillMarkdown, { linked: false });
+  bytes.set("SKILL.md", Buffer.from(markdown, "utf8"));
+  const entries = [...bytes.keys()]
+    .sort((left, right) => left.localeCompare(right))
+    .map((file) => ({ path: file, sha256: sha256(bytes.get(file)) }));
+  return { entries, bytes, read: (entry) => bytes.get(entry.path) ?? null };
+}
+
+/** A read-only skill copy against the release it holds: what changed here,
+ *  and whether a newer version has been published. */
+async function readOnlySkillCopy(flags, { dir, record, action }) {
+  const api = await connect(flags, { auth: "optional" });
+  const detail = await api.json("GET /v1/skills/{ref}", { params: { ref: record.address } });
+  const packages = await validatePath(dir, SKILL_PACKAGE_POLICY);
+  const tracked = packages.length === 1 ? localSkillEntries(packages[0]) : [];
+  const published = detail.release_version || detail.version || "";
+  const behind = Boolean(published) && published !== (record.release?.version ?? "");
+  return { api, detail, tracked, published, behind, action };
+}
+
+/** `terminus status` in a read-only copy of someone else's skill. */
+async function statusReadOnlySkill(flags, dir, record) {
+  const { detail, tracked, published, behind } = await readOnlySkillCopy(flags, { dir, record, action: "status" });
+  const changes = localChanges(record, tracked);
+  const held = record.release?.label || record.release?.version || "";
+  const result = {
+    address: record.address,
+    kind: "skill",
+    dir,
+    read_only: true,
+    release: held || null,
+    behind: behind ? published : false,
+    changes,
+    synchronized: !changes.length && !behind,
+  };
+  emitJson(flags, result, () => {
+    console.log(`${record.address} (skill, read-only) — ${dir}`);
+    console.log(held ? `This copy holds ${creationVersion(held)}.` : "This copy holds its published state.");
+    if (behind) console.log(`${creationVersion(published)} has been published — run \`terminus pull\`.`);
+    if (!changes.length) return;
+    console.log("Changes here (this copy can't be pushed):");
+    for (const change of changes) console.log(`  ${`${change.status}:`.padEnd(10)}${change.path}`);
+    console.log(`To make changes you can publish, fork it: terminus fork ${record.address}`);
+    void detail;
+  });
+}
+
+/** `terminus diff` in a read-only skill copy. */
+async function diffReadOnlySkill(flags, dir, record) {
+  const { api, detail, tracked } = await readOnlySkillCopy(flags, { dir, record, action: "diff" });
+  const { printWorkingDiff } = await import("./apps.mjs");
+  const held = record.change_hash ? `${record.address}@${record.change_hash}` : detail.uid;
+  const tree = await publicSkillTree(api, held, detail);
+  return printWorkingDiff({
+    dir,
+    flags,
+    changes: localChanges(record, tracked),
+    readBefore: (entry) => tree.read(entry),
+    since: record.release?.label ? creationVersion(record.release.label) : "its published state",
+  });
+}
+
+/** `terminus pull` in a read-only skill copy: bring in its newer release. */
+async function pullReadOnlySkill(flags, dir, record) {
+  const { api, detail, tracked, published, behind } = await readOnlySkillCopy(flags, { dir, record, action: "pull" });
+  const { mergeIntoFolder, mergeSummary } = await import("./apps.mjs");
+  const label = published || record.release?.label || "";
+  const finish = (mode, extra = {}, lines = []) => emitJson(
+    flags,
+    { address: record.address, kind: "skill", read_only: true, release: label || null, mode, ...extra },
+    () => { for (const line of lines) console.log(line); },
+  );
+  if (!behind && !flags.force) {
+    return finish("already-current", {}, [`Already up to date with ${record.address}.`]);
+  }
+  const tree = await publicSkillTree(api, detail.uid, detail);
+  const write = async (entry) => {
+    const target = path.join(dir, ...entry.path.split("/"));
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, tree.read(entry));
+  };
+  const keep = (entries) => writeSyncRecord(dir, {
+    ...record,
+    release: { version: published, label },
+    change_hash: detail.change_hash,
+    files: tree.entries.map((entry) => ({
+      path: entry.path,
+      draft: entry.sha256,
+      local: byKey(entries).get(entryKey(entry))?.sha256 ?? entry.sha256,
+    })),
+  });
+  if (flags.force) {
+    for (const entry of tree.entries) await write(entry);
+    await keep(tree.entries);
+    return finish("replaced", {}, [`Replaced this copy with ${record.address} ${creationVersion(label)}.`]);
+  }
+  const held = record.change_hash ? await publicSkillTree(api, `${record.address}@${record.change_hash}`, detail).catch(() => null) : null;
+  const merged = await mergeIntoFolder({
+    dir,
+    record,
+    local: tracked,
+    incoming: tree.entries,
+    readIncoming: (entry) => tree.read(entry),
+    readBase: (entry) => (held ? held.read(entry) : null),
+    canonicalPackage: (bytes) => bytes,
+  });
+  await keep(merged.localBase);
+  finish(merged.conflicts.length ? "conflicts" : "merged", {
+    updated: merged.updated,
+    added: merged.added,
+    deleted: merged.deleted,
+    merged: merged.merged,
+    conflicts: merged.conflicts,
+  }, [`Pulled ${record.address} ${creationVersion(label)}.`, ...mergeSummary(merged)]);
+}
+
+/** `terminus status` in a skill folder. */
+async function statusSkillCommand(args) {
+  const flags = parseFlags(args, "status");
+  const here = path.resolve(flags._[0] ?? ".");
+  const copy = await readSyncRecord(here);
+  if (copy?.source === "release") return statusReadOnlySkill(flags, here, copy);
+  const { dir, pkg, record, api, skill, ref } = await skillWorkingCopy(flags, {
+    dir: flags._[0],
+    action: "status",
+  });
+  const tracked = localSkillEntries(pkg);
+  const own = record?.source === "draft" && record.id === ref ? record : null;
+  const listing = await skillHistory(api, ref, 100);
+  const head = listing.head_revision_id ?? null;
+  const unseen = own?.commit && own.commit !== head ? skillCommitsSince(listing, own.commit) : null;
+  const changes = own ? localChanges(own, tracked) : [];
+  const { address } = skill;
+  const behind = unseen ? unseen.commits.length : 0;
+
+  const result = {
+    address,
+    kind: "skill",
+    dir,
+    commit: own?.commit ?? null,
+    head,
+    behind,
+    changes,
+    synchronized: Boolean(own) && !changes.length && own.commit === head,
+    draft_changes: Boolean(skill.has_draft_changes),
+    status: skill.status ?? null,
+  };
+  emitJson(flags, result, () => {
+    console.log(`${address} (skill) — ${dir}`);
+    if (!own) {
+      console.log("This folder has no record of which commit it came from; `terminus pull` brings one down.");
+    } else if (behind) {
+      console.log(
+        `The draft has ${behind} commit${behind === 1 ? "" : "s"} this folder hasn't pulled — run \`terminus pull\`.`,
+      );
+    }
+    if (!changes.length) {
+      console.log(own ? "Nothing changed here since the last sync." : "");
+      return;
+    }
+    console.log("Changes not pushed:");
+    for (const change of changes) console.log(`  ${`${change.status}:`.padEnd(10)}${change.path}`);
+  });
+}
+
+/** `terminus log` in a skill folder. */
+async function logSkillCommand(args) {
+  const flags = parseFlags(args, "log");
+  const copy = await readSyncRecord(path.resolve("."));
+  if (copy?.source === "release") {
+    const apps = await import("./apps.mjs");
+    return apps.logCommand([copy.address, ...(flags.json ? ["--json"] : [])]);
+  }
+  const { record, api, skill, ref } = await skillWorkingCopy(flags, { action: "log" });
+  const { shortCommit } = await import("./apps.mjs");
+  const limit = Math.min(Math.max(Number.parseInt(flags.limit ?? "20", 10) || 20, 1), 100);
+  const listing = await skillHistory(api, ref, limit);
+  const { commitPhrase } = await import("./apps.mjs");
+  const here = record?.id === ref ? record.commit : undefined;
+  const { address } = skill;
+  emitJson(flags, { address, ...listing }, () => {
+    const revisions = listing.revisions ?? [];
+    if (!revisions.length) {
+      console.log(`${address}: no history yet — it starts with the first push or save.`);
+      return;
+    }
+    for (const revision of revisions) {
+      const marks = [
+        ...(revision.head ? ["latest"] : []),
+        ...(revision.version ? [creationVersion(revision.version)] : []),
+        ...(revision.id === here ? ["this folder"] : []),
+      ];
+      console.log(`commit ${shortCommit(revision.id)}${marks.length ? ` (${marks.join(", ")})` : ""}`);
+      const who = commitPhrase({ author: revision.author, origin: revision.origin });
+      console.log(`Author: ${who.replace(/^(.*) by (.*)$/, "$2 · $1")}`);
+      console.log(`Date:   ${new Date(revision.created_at).toLocaleString()}`);
+      const said = revision.message || revision.publish_message;
+      if (said) console.log(`\n    ${said}`);
+      console.log("");
+    }
+  });
+}
+
+/** `terminus diff` in a skill folder: what a push would send. */
+async function diffSkillCommand(args) {
+  const flags = parseFlags(args, "diff");
+  const here = path.resolve(".");
+  const copy = await readSyncRecord(here);
+  if (copy?.source === "release") return diffReadOnlySkill(flags, here, copy);
+  const { dir, pkg, record, api, skill, ref } = await skillWorkingCopy(flags, { action: "diff" });
+  const tracked = localSkillEntries(pkg);
+  const own = record?.source === "draft" && record.id === ref ? record : null;
+  const remote = await remoteSkillTree(api, skill, { at: own?.change_hash });
+  const changes = own
+    ? localChanges(own, tracked)
+    : localChanges({ files: remote.entries.map((entry) => ({ ...entry, draft: entry.sha256, local: entry.sha256 })) }, tracked);
+  const { printWorkingDiff, shortCommit } = await import("./apps.mjs");
+  return printWorkingDiff({
+    dir,
+    flags,
+    changes,
+    readBefore: (entry) => remote.read(entry),
+    since: own?.commit ? `the draft at ${shortCommit(own.commit)}` : "the draft",
+  });
+}
+
+/** `terminus pull` in a skill folder: bring the draft's commits in, merging
+ *  rather than replacing what changed here. */
+async function pullSkillCommand(args) {
+  const flags = parseFlags(args, "pull");
+  const here = path.resolve(flags._[0] ?? ".");
+  const copy = await readSyncRecord(here);
+  if (copy?.source === "release") return pullReadOnlySkill(flags, here, copy);
+  const { dir, pkg, record, api, skill, ref } = await skillWorkingCopy(flags, {
+    dir: flags._[0],
+    action: "pull",
+  });
+  const { mergeIntoFolder, mergeSummary, shortCommit } = await import("./apps.mjs");
+  const listing = await skillHistory(api, ref, 100);
+  const head = listing.head_revision_id ?? null;
+  const own = record?.source === "draft" && record.id === ref ? record : null;
+  const { address } = skill;
+  const draft = await remoteSkillTree(api, skill);
+  const finish = (mode, extra = {}, lines = []) => emitJson(
+    flags,
+    { address, kind: "skill", commit: head, mode, ...extra },
+    () => { for (const line of lines) console.log(line); },
+  );
+
+  const writeTree = async () => {
+    for (const entry of draft.entries) {
+      const target = path.join(dir, ...entry.path.split("/"));
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, draft.read(entry));
+    }
+    await recordSkillSync(dir, { dir, skill, commit: head, draft: draft.entries, local: draft.entries });
+  };
+
+  if (flags.force) {
+    await writeTree();
+    return finish("replaced", {}, [`Replaced this folder with ${address}'s draft.`]);
+  }
+  const tracked = localSkillEntries(pkg);
+  if (!own) {
+    const same = byKey(draft.entries);
+    const differs = tracked.length !== draft.entries.length
+      || tracked.some((entry) => same.get(entryKey(entry))?.sha256 !== entry.sha256);
+    if (differs) {
+      throw new CliError(
+        "this folder has no record of which commit it came from, and it differs from the draft, so there is nothing to merge against. "
+        + "`terminus pull --force` replaces this folder with the draft; `terminus push --force` replaces the draft with this folder.",
+      );
+    }
+    await recordSkillSync(dir, { skill, commit: head, draft: draft.entries, local: tracked });
+    return finish("already-current", {}, [`Already up to date with ${address}.`]);
+  }
+  if (own.commit === head) {
+    return finish("already-current", {}, [`Already up to date with ${address}.`]);
+  }
+
+  const wasAt = own.change_hash
+    ? await remoteSkillTree(api, skill, { at: own.change_hash }).catch(() => null)
+    : null;
+  const merged = await mergeIntoFolder({
+    dir,
+    record: own,
+    local: tracked,
+    incoming: draft.entries,
+    readIncoming: (entry) => draft.read(entry),
+    readBase: (entry) => (wasAt ? wasAt.read(entry) : null),
+    canonicalPackage: (bytes) => bytes,
+  });
+  await recordSkillSync(dir, { skill, commit: head, draft: draft.entries, local: merged.localBase });
+  finish(
+    merged.conflicts.length ? "conflicts" : "merged",
+    {
+      updated: merged.updated,
+      added: merged.added,
+      deleted: merged.deleted,
+      merged: merged.merged,
+      conflicts: merged.conflicts,
+    },
+    [`Pulled ${address} (${shortCommit(head)}).`, ...mergeSummary(merged)],
+  );
+}
+
+/** `terminus restore <commit>` in a skill folder. */
+async function restoreSkillCommand(args) {
+  const flags = parseFlags(args, "restore");
+  const wanted = String(flags._[0] ?? "").trim().toLowerCase().replaceAll("-", "");
+  if (!wanted) throw commandUsageError("restore");
+  const { dir, pkg, record, api, skill, ref } = await skillWorkingCopy(flags, {
+    dir: flags._[1],
+    action: "restore",
+  });
+  const { shortCommit } = await import("./apps.mjs");
+  const listing = await skillHistory(api, ref, 100);
+  const revisions = listing.revisions ?? [];
+  const matches = revisions.filter((revision) => shortCommit(revision.id).startsWith(wanted)
+    || String(revision.id).replaceAll("-", "") === wanted);
+  if (!matches.length) {
+    throw new CliError(`no commit in this skill's history starts with ${wanted} — run \`terminus log\` to see them`);
+  }
+  if (matches.length > 1) {
+    throw new CliError(`${wanted} matches ${matches.length} commits — use more of the id`);
+  }
+  const [target] = matches;
+  const tracked = localSkillEntries(pkg);
+  const own = record?.source === "draft" && record.id === ref ? record : null;
+  // A folder that matched the draft follows it back; one with its own
+  // changes keeps them, and `terminus pull` merges the restore in.
+  const followed = Boolean(own) && own.commit === (listing.head_revision_id ?? null)
+    && !localChanges(own, tracked).length;
+
+  const result = await api.json("POST /v1/dashboard/developer/skills/{ref}/draft/restore", {
+    params: { ref },
+    body: { revision: target.id, origin: "cli", ...(flags.message ? { message: flags.message } : {}) },
+  });
+  let folderUpdated = false;
+  if (followed && result.changed) {
+    const restored = await remoteSkillTree(api, await ownedSkill(api, ref, flags));
+    for (const entry of restored.entries) {
+      const file = path.join(dir, ...entry.path.split("/"));
+      await mkdir(path.dirname(file), { recursive: true });
+      await writeFile(file, restored.read(entry));
+    }
+    for (const entry of tracked) {
+      if (!byKey(restored.entries).has(entryKey(entry))) {
+        await rm(path.join(dir, ...entry.path.split("/")), { force: true });
+      }
+    }
+    await recordSkillSync(dir, {
+      skill,
+      commit: result.revision_id,
+      draft: restored.entries,
+      local: restored.entries,
+    });
+    folderUpdated = true;
+  }
+  const { address } = skill;
+  emitJson(flags, { ...result, address, kind: "skill", folder_updated: folderUpdated }, () => {
+    if (!result.changed) {
+      console.log(`${address}'s draft already holds ${shortCommit(target.id)} — nothing to restore.`);
+      return;
+    }
+    console.log(`Restored ${address}'s draft to ${shortCommit(target.id)} (a new commit: ${shortCommit(result.revision_id)}).`);
+    console.log(folderUpdated
+      ? "This folder followed it back."
+      : "This folder has changes of its own — run `terminus pull` to merge the restore in.");
+  });
+}
+
+const PUBLISHED_SKILL_STATES = { published: "published", private: "published privately", suspended: "suspended" };
+
+/**
+ * `terminus push` in a skill folder: SKILL.md and the files it references,
+ * uploaded to the skill the folder is linked to (the `id:` in its
+ * frontmatter). Content only — name and description ride in SKILL.md, while
+ * versions, visibility, and price stay on the web.
+ *
+ * A push lands on the skill's draft, never on what people are using: a
+ * published skill keeps its live version until it is published again on the
+ * web. Each push is a commit, and the draft refuses one that has not seen
+ * the commits already there unless `--force` says to replace them.
+ */
+async function pushSkillCommand(args) {
+  const flags = parseFlags(args, "push");
+  const dir = path.resolve(flags._[0] ?? ".");
+  if (!(await exists(path.join(dir, "SKILL.md")))) {
+    throw new CliError(
+      `nothing to push in ${dir}: it has no terminus.json (an app, agent, or service) or SKILL.md (a skill)`,
+    );
+  }
+  // A read-only copy of someone else's work is refused before anything asks
+  // Terminus about it: it was never yours to push.
+  const copy = await readSyncRecord(dir);
+  if (copy?.source === "release") {
+    throw new CliError(
+      `${copy.address ?? "this creation"} isn't yours, so this folder can't be pushed — `
+      + `fork it to make changes you can publish: terminus fork ${copy.address ?? "<address>"}`,
+    );
+  }
+  const { shortCommit } = await import("./apps.mjs");
+  const { pkg, record, api, skill, ref } = await skillWorkingCopy(flags, {
+    dir: flags._[0],
+    action: "push",
+  });
+  const { address } = skill;
+  const page = creationPageUrl(flags, skill.uid);
+  const own = record?.source === "draft" && record.id === ref ? record : null;
+  await refuseUnresolvedSkillConflicts(dir, own, localSkillEntries(pkg));
+  // The commit this push starts from, which the draft is told so that it
+  // refuses the write rather than overwrite a commit this push has not seen.
+  // A folder that remembers its commit must still be on the head; one with
+  // no record yet (just linked) starts from the head it reads now — never
+  // from nothing. Only --force writes over whatever is there.
+  let head = null;
+  if (!flags.force) {
+    const listing = await skillHistory(api, ref, own ? 100 : 1);
+    head = listing.head_revision_id ?? null;
+    if (own && (own.commit ?? null) !== head) {
+      const count = skillCommitsSince(listing, own.commit).commits.length;
+      throw new CliError(
+        `the draft has ${count || "commits"}${count ? ` commit${count === 1 ? "" : "s"}` : ""} this folder hasn't pulled. `
+        + "Run `terminus pull` to merge them, then push — or `terminus push --force` to replace them with this folder.",
+      );
+    }
+  }
+  const updated = await api.json("PATCH /v1/dashboard/developer/skills/{ref}", {
+    params: { ref },
+    body: {
+      name: pkg.metadata.name,
+      description: pkg.metadata.description,
+      content_markdown: pkg.skillMarkdown,
+      runtime_kind: "markdown",
+      origin: "cli",
+      ...(flags.message ? { message: flags.message } : {}),
+      ...(head ? { expected_revision: head } : {}),
+      graph_manifest: {
+        skills: [],
+        agents: pkg.files.filter((file) => file.path.startsWith("agents/")).map((file) => file.path),
+        skill_files: pkg.files.map((file) => file.path),
+      },
+      skill_files: pkg.files.map((file) => ({
+        path: file.path,
+        content_base64: file.contentBytes.toString("base64"),
+        content_type: file.contentType,
+        size_bytes: file.contentBytes.length,
+      })),
+    },
+  });
+  // Like git's origin/main: the folder now knows which commit it matches —
+  // the one this push recorded, or, when it changed nothing, the head.
+  const commit = updated.recorded_revision_id
+    ?? head
+    ?? (await skillHistory(api, ref, 1)).head_revision_id
+    ?? null;
+  const draft = await remoteSkillTree(api, updated);
+  await recordSkillSync(dir, {
+    skill: updated,
+    commit,
+    draft: draft.entries,
+    local: localSkillEntries(pkg),
+  });
+  const result = {
+    address: updated.address,
+    id: updated.id,
+    status: updated.status,
+    files: pkg.files.length,
+    change_hash: updated.change_hash,
+    commit,
+    changed: Boolean(updated.recorded_revision_id),
+    publish_url: page,
+  };
+  emitJson(flags, result, () => {
+    const at = commit ? ` (${shortCommit(commit)})` : "";
+    console.log(`Pushed ${result.address}${at} — ${formatNumber(result.files)} file${result.files === 1 ? "" : "s"}.`);
+    console.log(result.status === "draft"
+      ? `Publish it on the web when it is ready: ${page}`
+      : `It lands on the draft; people keep the published version until you publish again: ${page}`);
+  });
+}
+
+/** A push never uploads the markers a pull left in a file it could not
+ *  merge: they mean the file still holds two versions. */
+async function refuseUnresolvedSkillConflicts(dir, record, tracked) {
+  const { hasConflictMarkers } = await import("./sync.mjs");
+  const changed = new Set(localChanges(record, tracked)
+    .filter((change) => change.status !== "deleted")
+    .map((change) => entryKey(change)));
+  const unresolved = [];
+  for (const entry of tracked) {
+    if (record && !changed.has(entryKey(entry))) continue;
+    const text = await readFile(path.join(dir, ...entry.path.split("/")), "utf8").catch(() => "");
+    if (hasConflictMarkers(text)) unresolved.push(entry.path);
+  }
+  if (unresolved.length) {
+    throw new CliError(
+      `resolve the conflicts in ${unresolved.join(", ")} before pushing — `
+      + "each still holds both versions between the markers `terminus pull` wrote",
+    );
+  }
+}
+
+/** `terminus remote add <address> [<dir>]` in a skill folder: record which
+ * skill it is as the `id:` in SKILL.md's frontmatter, the way terminus.json
+ * holds an app's address. Nothing is uploaded. */
+async function remoteAddSkillCommand(args) {
+  const flags = parseFlags(args, "remote add");
+  const ref = flags._[0]?.trim();
+  if (!ref) throw commandUsageError("remote", { sub: "add" });
+  const dir = path.resolve(flags._[1] ?? ".");
+  const skillPath = path.join(dir, "SKILL.md");
+  if (!(await exists(skillPath))) {
+    throw new CliError(`nothing to link in ${dir}: it has no terminus.json or SKILL.md`);
+  }
+  const skill = await ownedSkill(await connect(flags), ref, flags);
+  const markdown = await readFile(skillPath, "utf8");
+  await writeFile(skillPath, withSkillId(markdown, skill.id));
+  const localName = parseFrontmatterMetadata(markdown).name;
+  const result = {
+    address: skill.address,
+    id: skill.id,
+    dir,
+    status: skill.status,
+  };
+  emitJson(flags, result, () => {
+    console.log(`Linked ${dir} → ${result.address}.`);
+    if (skill.status !== "draft") {
+      console.log(`It is published, so it changes on the web: ${creationPageUrl(flags, skill.uid)}`);
+      return;
+    }
+    if (localName && skill.name && localName !== skill.name) {
+      console.log(`SKILL.md calls it '${localName}' and Terminus '${skill.name}'; a push renames it to '${localName}'.`);
+    }
+    console.log("terminus push uploads it; publish it on the web when it is ready.");
+  });
+}
+
+/** SKILL.md with its frontmatter `id:` set, everything else as written. */
+function withSkillId(markdown, id) {
+  const text = String(markdown);
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  const lines = withFrontmatterEntry(match ? match[1].split(/\r?\n/) : [], "id", id);
+  const body = match ? text.slice(match[0].length) : `\n${text}`;
+  return `---\n${lines.join("\n")}\n---\n${body}`;
+}
+
+/** How much a skill package may hold. What it ships is
+ * `isStandardPackagePath` plus any file SKILL.md references, never a path
+ * `shouldSkipPackagePath` skips. */
+export const SKILL_PACKAGE_POLICY = Object.freeze({
+  maxFiles: DEFAULT_MAX_FILES,
+  maxFileSizeBytes: DEFAULT_MAX_FILE_SIZE_BYTES,
+  maxTotalSizeBytes: DEFAULT_MAX_TOTAL_SIZE_BYTES,
+});
+
+function evidenceKeptPackagePaths(files) {
+  const kept = new Set();
+  for (const pathName of files.keys()) {
+    if (isStandardPackagePath(pathName)) {
+      kept.add(pathName);
+    }
+  }
+  const processed = new Set();
+  for (let depth = 0; depth < MAX_REFERENCE_DEPTH; depth += 1) {
+    let changed = false;
+    for (const pathName of [...kept]) {
+      if (processed.has(pathName)) {
+        continue;
+      }
+      processed.add(pathName);
+      const file = files.get(pathName);
+      if (!file) {
+        continue;
+      }
+      const references = referencedPackagePaths(file);
+      const baseDir = parentPath(pathName);
+      for (const reference of references) {
+        for (const candidate of resolveReferencedPackagePaths(files, baseDir, reference)) {
+          if (!shouldSkipPackagePath(candidate) && !kept.has(candidate)) {
+            kept.add(candidate);
+            changed = true;
+          }
+        }
+      }
+    }
+    if (!changed) {
+      break;
+    }
+  }
+  return kept;
+}
+
+function referencedPackagePaths(file) {
+  const references = new Set();
+  if (!isTextual(file.contentType, file.path)) {
+    return references;
+  }
+  const content = file.contentBytes.toString("utf8");
+  for (const reference of textRelativePathMentions(content)) {
+    references.add(reference);
+  }
+  if (file.contentType.includes("json") || file.path.toLowerCase().endsWith(".json")) {
+    try {
+      collectJsonRelativePaths(JSON.parse(content), references);
+    } catch {
+      // Invalid JSON is still treated as text above.
+    }
+  }
+  return references;
+}
+
+function collectJsonRelativePaths(value, references) {
+  if (typeof value === "string") {
+    for (const reference of textRelativePathMentions(value)) {
+      references.add(reference);
+    }
+  } else if (Array.isArray(value)) {
+    for (const item of value) collectJsonRelativePaths(item, references);
+  } else if (value && typeof value === "object") {
+    for (const item of Object.values(value)) collectJsonRelativePaths(item, references);
+  }
+}
+
+function textRelativePathMentions(content) {
+  const references = new Set();
+  for (const rawToken of content.split(/[\s"'`\[\]\(\)<>{},]+/u)) {
+    const token = rawToken
+      .replace(/^[;:!?\|#\u0000-\u001F]+/u, "")
+      .replace(/[;:!?\|#.\u0000-\u001F]+$/u, "")
+      .split("#")[0]
+      .split("?")[0]
+      .trim();
+    if (looksLikeRelativeReference(token)) {
+      references.add(token);
+    }
+  }
+  return references;
+}
+
+function looksLikeRelativeReference(value) {
+  if (!value || value.startsWith("/") || value.startsWith("#") || value.includes("\0")) return false;
+  if (/^(https?:|mailto:)/i.test(value)) return false;
+  return value.includes("/") || /\.(md|json|css|js|ts|py|sh|txt|html|ya?ml|toml)$/i.test(value);
+}
+
+function resolveReferencedPackagePaths(files, baseDir, reference) {
+  const resolved = new Set();
+  for (const candidate of [
+    normalizeRelativeReferencePath("", reference),
+    normalizeRelativeReferencePath(baseDir, reference),
+  ]) {
+    if (!candidate) continue;
+    if (files.has(candidate)) resolved.add(candidate);
+    for (const pathName of files.keys()) {
+      if (pathName.startsWith(`${candidate}/`)) resolved.add(pathName);
+    }
+  }
+  return [...resolved].sort(pathCompare);
+}
+
+function normalizeRelativeReferencePath(baseDir, reference) {
+  const clean = String(reference).trim().split("#")[0].split("?")[0].replaceAll("\\", "/");
+  if (!clean || clean.startsWith("/") || clean.includes("\0")) return null;
+  const segments = baseDir.split("/").filter(Boolean);
+  for (const segment of clean.split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (segments.length === 0) return null;
+      segments.pop();
+    } else {
+      segments.push(segment);
+    }
+  }
+  if (segments.length === 0) return null;
+  try {
+    return normalizePackageFilePath(segments.join("/"));
+  } catch {
+    return null;
+  }
+}
+
+export async function validatePath(target, policy = SKILL_PACKAGE_POLICY) {
+  const root = path.resolve(target);
+  const validationBudget = { totalBytes: 0 };
+  const rootStat = await stat(root);
+  if (!rootStat.isDirectory()) {
+    throw new CliError(`path is not a directory: ${root}`);
+  }
+  const rootSkill = path.join(root, "SKILL.md");
+  if (await exists(rootSkill)) {
+    return [await loadLocalSkillPackage(root, policy, validationBudget)];
+  }
+  const entries = await readdir(root, { withFileTypes: true });
+  const packages = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(root, entry.name);
+    if (await exists(path.join(dir, "SKILL.md"))) {
+      packages.push(await loadLocalSkillPackage(dir, policy, validationBudget));
+    }
+  }
+  if (packages.length === 0) {
+    throw new CliError(`no skill packages found in ${root}`);
+  }
+  return packages;
+}
+
+async function loadLocalSkillPackage(root, policy, validationBudget) {
+  const files = await collectLocalFiles(root, policy, validationBudget);
+  ensureTotalSize(files, policy.maxTotalSizeBytes);
+  const map = new Map(files.map((file) => [file.path, file]));
+  const kept = evidenceKeptPackagePaths(map);
+  const packageFiles = [...kept].map((filePath) => map.get(filePath)).filter(Boolean);
+  packageFiles.sort((a, b) => pathCompare(a.path, b.path));
+  const skill = packageFiles.find((file) => file.path === "SKILL.md");
+  if (!skill) {
+    throw new CliError(`skill package must include SKILL.md: ${root}`);
+  }
+  const skillMarkdown = skill.contentBytes.toString("utf8");
+  const metadata = parseFrontmatterMetadata(skillMarkdown);
+  requireMetadata(metadata, "name", root);
+  requireMetadata(metadata, "description", root);
+  return {
+    root,
+    metadata,
+    skillMarkdown,
+    files: packageFiles,
+  };
+}
+
+async function collectLocalFiles(root, policy, validationBudget) {
+  const entries = await walkTree(root, {
+    skip: (relative) => shouldSkipPackagePath(normalizePackageFilePath(relative)),
+    onSymlink: (relative) => {
+      throw new CliError(`symlinks are not supported in skill packages: ${relative}`);
+    },
+  });
+  const files = [];
+  for (const entry of entries) {
+    const relative = normalizePackageFilePath(entry.path);
+    if (files.length >= policy.maxFiles) {
+      throw new CliError(`package contains more than ${policy.maxFiles} files`);
+    }
+    const contentBytes = await readFile(entry.absolute);
+    if (contentBytes.length > policy.maxFileSizeBytes) {
+      throw new CliError(`package file ${relative} exceeds ${policy.maxFileSizeBytes} bytes`);
+    }
+    if (validationBudget.totalBytes + contentBytes.length > policy.maxTotalSizeBytes) {
+      throw new CliError(
+        `validation input exceeds ${policy.maxTotalSizeBytes} bytes; split packages into separate runs`,
+      );
+    }
+    validationBudget.totalBytes += contentBytes.length;
+    files.push({
+      path: relative,
+      contentType: contentTypeForPath(relative),
+      contentBytes,
+    });
+  }
+  return files;
+}
+
+async function writeSkillFiles(target, files) {
+  await mkdir(target, { recursive: true });
+  for (const file of files) {
+    if (!file.content_available || !file.content_base64) {
+      throw new CliError(`backend did not return content for ${file.path}`);
+    }
+    const relative = normalizePackageFilePath(file.path);
+    const output = path.join(target, relative);
+    await mkdir(path.dirname(output), { recursive: true });
+    await writeFile(output, Buffer.from(file.content_base64, "base64"));
+  }
+}
+
+function skillReference(skill) {
+  return skill.address;
+}
+
+function packageSummary(pkg) {
+  return {
+    name: pkg.metadata.name,
+    description: pkg.metadata.description,
+    root: pkg.root,
+    file_count: pkg.files.length,
+    total_bytes: totalBytes(pkg.files),
+    files: pkg.files.map((file) => file.path),
+  };
+}
+
+function parseFrontmatterMetadata(content) {
+  const metadata = {};
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return metadata;
+  for (const line of match[1].split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const index = trimmed.indexOf(":");
+    if (index < 0) continue;
+    const key = trimmed.slice(0, index).trim();
+    const value = parseYamlScalar(trimmed.slice(index + 1));
+    if (value == null) continue;
+    if (["id", "name", "description", "version"].includes(key)) metadata[key] = value;
+  }
+  return metadata;
+}
+
+function parseYamlScalar(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    try {
+      return JSON.parse(trimmed).trim() || null;
+    } catch {
+      return null;
+    }
+  }
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1).replaceAll("''", "'").trim() || null;
+  }
+  return trimmed;
+}
+
+function requireMetadata(metadata, key, root) {
+  if (!metadata[key]?.trim()) {
+    throw new CliError(`${path.join(root, "SKILL.md")} frontmatter must include ${key}`);
+  }
+}
+
+function contentTypeForPath(pathName) {
+  const ext = path.extname(pathName).toLowerCase();
+  if (CONTENT_TYPES.has(ext)) return CONTENT_TYPES.get(ext);
+  if (fileName(pathName).toLowerCase().startsWith("license")) return "text/plain; charset=utf-8";
+  return "application/octet-stream";
+}
+
+function isTextual(contentType, pathName) {
+  return contentType.startsWith("text/") || /json|javascript|typescript|yaml/.test(contentType) || /\.(md|txt|json|toml|ya?ml|html?|js|ts)$/i.test(pathName);
+}
+
+/** The path's segments, slashes trimmed first and backslashes read as
+ * slashes after — the backend's order. */
+function packagePathSegments(pathName) {
+  const clean = String(pathName).replace(/^\/+|\/+$/g, "").replaceAll("\\", "/");
+  return clean ? clean.split("/") : [];
+}
+
+/** ASCII letters lowered, nothing else — Rust's `to_ascii_lowercase`. */
+function asciiLowercase(value) {
+  return value.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+}
+
+/** Credentials by file name, in any case: `.env` files but their templates,
+ * `.npmrc`, `.netrc`, and private keys. */
+function isCredentialFileName(name) {
+  const lower = asciiLowercase(name);
+  if (lower === ".npmrc" || lower === ".netrc" || /^id_(rsa|dsa|ecdsa|ed25519)$/.test(lower)) return true;
+  if (/\.(pem|key|p12|pfx)$/.test(lower)) return true;
+  return lower.startsWith(".env") && !/^\.env\.(example|sample|template)$/.test(lower);
+}
+
+/** Whether a package never ships `pathName`: it sits under an ignored
+ * directory, or it is OS litter or a credential. */
+export function shouldSkipPackagePath(pathName) {
+  const segments = packagePathSegments(pathName);
+  if (segments.length === 0) return false;
+  const name = segments.at(-1);
+  if (PACKAGE_IGNORED_FILE_NAMES.has(name) || isCredentialFileName(name)) return true;
+  return segments.some((segment) => PACKAGE_IGNORED_DIRECTORIES.has(segment));
+}
+
+/** Whether a package keeps `pathName` for what it is: any SKILL.md, README*
+ * or LICENSE* (any depth, any case), or anything under a standard folder. */
+export function isStandardPackagePath(pathName) {
+  const segments = packagePathSegments(pathName);
+  if (segments.length === 0) return false;
+  const name = asciiLowercase(segments.at(-1));
+  if (name === "skill.md" || name.startsWith("readme") || name.startsWith("license")) return true;
+  return PACKAGE_STANDARD_FOLDERS.has(segments[0]);
+}
+
+function normalizePackageFilePath(pathName) {
+  const normalized = pathName.trim().replaceAll("\\", "/");
+  if (!normalized || normalized.startsWith("/") || normalized.length > 512 || normalized.includes("\0")) {
+    throw new CliError("package file path must be a relative path up to 512 characters");
+  }
+  for (const segment of normalized.split("/")) {
+    if (!segment || segment === "." || segment === "..") {
+      throw new CliError(`package file path ${normalized} is not allowed`);
+    }
+  }
+  return normalized;
+}
+
+function ensureTotalSize(files, maxBytes) {
+  const total = totalBytes(files);
+  if (total > maxBytes) {
+    throw new CliError(`skill package is ${total} bytes, which exceeds ${maxBytes} bytes`);
+  }
+}
+
+function totalBytes(files) {
+  return files.reduce((sum, file) => sum + file.contentBytes.length, 0);
+}
+
+function fileName(pathName) {
+  return pathName.split("/").at(-1) ?? pathName;
+}
+
+function parentPath(pathName) {
+  const index = pathName.lastIndexOf("/");
+  return index < 0 ? "" : pathName.slice(0, index);
+}
+
+function slugify(value) {
+  const slug = String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "skill";
+}
+
+async function isMainModule() {
+  if (!process.argv[1]) {
+    return false;
+  }
+  const modulePath = fileURLToPath(import.meta.url);
+  try {
+    return (await realpath(process.argv[1])) === (await realpath(modulePath));
+  } catch {
+    return path.resolve(process.argv[1]) === modulePath;
+  }
+}
+
+if (await isMainModule()) {
+  main().catch((error) => {
+    if (process.argv.includes("--json")) {
+      console.error(JSON.stringify(errorEnvelope(error)));
+    } else if (error instanceof CliError && error.help) {
+      console.error(`${error.help}\n\nError: ${error.message}`);
+    } else {
+      console.error(error instanceof CliError ? error.message : error.stack || error.message);
+    }
+    process.exit(error instanceof CliError ? error.exitCode : 1);
+  });
+}