arkaos 4.13.2 → 4.14.0

package/installer/index.js

@@ -6,7 +6,9 @@ import { fileURLToPath } from "node:url";
 import { getRuntimeConfig } from "./detect-runtime.js";
 import { findSystemPython, ensureVenv, getArkaosPython, getArkaosPip, pipInstall } from "./python-resolver.js";
 import { IS_WINDOWS, HOOK_EXT } from "./platform.js";
-import { copyHookLib } from "./hook-lib.js";
+import { copyHookLib, copyHookAssets } from "./hook-lib.js";
+import { deploySkills } from "./skill-deploy.js";
+import { resolveSkillsMode } from "./skills-mode.js";
 import { deployCoreSnapshot } from "./core-snapshot.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -677,6 +679,8 @@ function installHooks(installDir) {
     "cwd-changed",
     "pre-tool-use",
     "stop",
+    "subagent-stop",
+    "session-end",
   ];
   const hookExt = HOOK_EXT;
 
@@ -712,171 +716,51 @@ function installHooks(installDir) {
   if (copyHookLib(srcHooksDir, hooksDir)) {
     ok("Hook lib: _lib/");
   }
-}
-
-// Safe directory iteration. Returns an empty array instead of throwing
-// when the target does not exist, which lets us skip missing sources
-// (fresh repo checkouts may omit optional department resource dirs).
-function listSubdirs(parent) {
-  if (!existsSync(parent)) return [];
-  try {
-    return readdirSync(parent, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .map((e) => e.name);
-  } catch {
-    return [];
-  }
-}
 
-// Port of the "Resources" copy loop from install.sh:399-403. Copies any
-// of scripts/references/assets that exist next to a skill's SKILL.md
-// into the deployed skill directory. Silent no-op when a resource dir
-// does not exist. Each copy is wrapped in a try/catch so a partial
-// failure on one resource doesn't block the rest of the deployment.
-function copySkillResources(skillSrcDir, skillDestDir) {
-  const resources = ["scripts", "references", "assets"];
-  for (const res of resources) {
-    const src = join(skillSrcDir, res);
-    if (!existsSync(src)) continue;
-    try {
-      cpSync(src, join(skillDestDir, res), { recursive: true });
-    } catch {
-      // Best-effort — a single missing resource dir shouldn't break install.
-    }
+  // F2-6 fast-path shims + gate manifest (shared deploy — the asset
+  // list lives in hook-lib.js so this path and update.js cannot drift).
+  const assetCount = copyHookAssets(srcHooksDir, hooksDir);
+  if (assetCount > 0) {
+    ok(`Hook fast-path assets: ${assetCount}`);
   }
 }
 
-// Deploy one skill directory as a top-level `arka-<name>/` under the
-// Claude Code skills base. Mirrors install.sh lines 396-405 and 414-425.
-// Returns true if SKILL.md was deployed, false otherwise.
-function deployTopLevelSkill(skillSrcDir, arkaName, skillsBase) {
-  const skillMd = join(skillSrcDir, "SKILL.md");
-  if (!existsSync(skillMd)) return false;
-  const dest = join(skillsBase, arkaName);
-  ensureDir(dest);
-  copyFileSync(skillMd, join(dest, "SKILL.md"));
-  copySkillResources(skillSrcDir, dest);
-  return true;
-}
-
 function installSkill(config, installDir) {
-  // ── Main /arka skill ────────────────────────────────────────────────
-  const skillSrc = join(ARKAOS_ROOT, "arka", "SKILL.md");
+  // Single shared deployment (installer/skill-deploy.js) — main /arka
+  // skill + nested reference bundle + department hubs + sub-skills +
+  // meta skills + agent personas. update.js §6 calls the SAME function,
+  // so install and update can no longer drift (F2-7c-pre: update-only
+  // machines were missing the 14 meta skills, including arka-flow).
   const skillsBase = config.skillsDir || join(homedir(), ".claude", "skills");
   const skillDest = join(skillsBase, "arka");
-
-  ensureDir(skillDest);
-
-  if (existsSync(skillSrc)) {
-    copyFileSync(skillSrc, join(skillDest, "SKILL.md"));
-    writeFileSync(join(skillDest, ".repo-path"), ARKAOS_ROOT);
-    writeFileSync(join(skillDest, "VERSION"), VERSION);
-    // Nested arka/skills/ (conclave, human-writing) is copied as a
-    // reference bundle under the main /arka skill, preserving the
-    // old behaviour for anything that reads from that path.
-    const nestedSkillsSrc = join(ARKAOS_ROOT, "arka", "skills");
-    if (existsSync(nestedSkillsSrc)) {
-      const nestedSkillsOut = join(skillDest, "skills");
-      ensureDir(nestedSkillsOut);
-      try {
-        cpSync(nestedSkillsSrc, nestedSkillsOut, { recursive: true });
-      } catch {
-        // Silent — these are bundled references, not user-facing skills.
-      }
-    }
+  // Fresh installs default to the curated cut (F2-7c); a machine that
+  // already chose a mode keeps it (install --force over an existing
+  // setup must not flip the operator's choice).
+  const skillsMode = resolveSkillsMode({ fresh: true });
+  const skillCounts = deploySkills({
+    repoRoot: ARKAOS_ROOT,
+    skillsBase,
+    agentsBase: join(homedir(), ".claude", "agents"),
+    version: VERSION,
+    mode: skillsMode.mode,
+  });
+  ok(`skill set mode: ${skillsMode.mode}`);
+  if (skillCounts.main) {
     ok("/arka skill installed");
   } else {
     warn("arka/SKILL.md not found in package");
   }
-
-  // ── Department skills ───────────────────────────────────────────────
-  // For each `departments/<dept>/SKILL.md`, deploy as top-level
-  // `~/.claude/skills/arka-<dept>/`. Mirrors install.sh:391-406, but
-  // iterates the source directory dynamically instead of hardcoding a
-  // department list (the bash list is stale — ships 8 of the 18 real
-  // departments on disk, so half are silently skipped on macOS/Linux
-  // too until a user edits install.sh).
-  const deptRoot = join(ARKAOS_ROOT, "departments");
-  let deptDeployed = 0;
-  for (const dept of listSubdirs(deptRoot)) {
-    if (deployTopLevelSkill(join(deptRoot, dept), `arka-${dept}`, skillsBase)) {
-      deptDeployed++;
-    }
-  }
-  if (deptDeployed > 0) {
-    ok(`${deptDeployed} department skills installed (/arka-<dept>)`);
-  }
-
-  // ── Sub-skills (departments/*/skills/*) ─────────────────────────────
-  // For each `departments/<dept>/skills/<skill>/SKILL.md`, deploy as
-  // top-level `~/.claude/skills/arka-<skill>/`. Mirrors install.sh:411-425.
-  // Collisions between departments (two depts defining the same
-  // sub-skill name) are resolved by "later wins", same semantics as
-  // the bash loop — in practice the repo has no collisions today.
-  let subSkillDeployed = 0;
-  for (const dept of listSubdirs(deptRoot)) {
-    const deptSkillsDir = join(deptRoot, dept, "skills");
-    for (const subSkill of listSubdirs(deptSkillsDir)) {
-      const subSkillSrc = join(deptSkillsDir, subSkill);
-      if (deployTopLevelSkill(subSkillSrc, `arka-${subSkill}`, skillsBase)) {
-        subSkillDeployed++;
-      }
-    }
+  if (skillCounts.depts > 0) {
+    ok(`${skillCounts.depts} department skills installed (/arka-<dept>)`);
   }
-  if (subSkillDeployed > 0) {
-    ok(`${subSkillDeployed} sub-skills installed (/arka-<skill>)`);
+  if (skillCounts.subs > 0) {
+    ok(`${skillCounts.subs} sub-skills installed (/arka-<skill>)`);
   }
-
-  // ── Meta skills (arka/skills/*) ─────────────────────────────────────
-  // For each `arka/skills/<skill>/SKILL.md`, deploy as top-level
-  // `~/.claude/skills/arka-<skill>/`. These are cross-cutting meta
-  // orchestrators (e.g. forge, platform-arka) that don't belong to a
-  // single department. They ALSO remain copied as bundled references
-  // under `~/.claude/skills/arka/skills/` by the nested block above —
-  // this additional deployment makes them invocable as `arka-<skill>`.
-  const arkaSkillsDir = join(ARKAOS_ROOT, "arka", "skills");
-  let metaSkillDeployed = 0;
-  for (const metaSkill of listSubdirs(arkaSkillsDir)) {
-    const metaSkillSrc = join(arkaSkillsDir, metaSkill);
-    if (deployTopLevelSkill(metaSkillSrc, `arka-${metaSkill}`, skillsBase)) {
-      metaSkillDeployed++;
-    }
+  if (skillCounts.meta > 0) {
+    ok(`${skillCounts.meta} meta skills installed (/arka-<skill>)`);
   }
-  if (metaSkillDeployed > 0) {
-    ok(`${metaSkillDeployed} meta skills installed (/arka-<skill>)`);
-  }
-
-  // ── Agent personas ──────────────────────────────────────────────────
-  // For each `departments/<dept>/agents/<name>.md`, deploy to
-  // `~/.claude/agents/arka-<name>.md`. Mirrors install.sh:436-443.
-  // The agents dir parallels skillsBase — Claude Code reads it
-  // separately from the skills tree.
-  const agentsBase = join(homedir(), ".claude", "agents");
-  ensureDir(agentsBase);
-  let agentDeployed = 0;
-  for (const dept of listSubdirs(deptRoot)) {
-    const agentsSrc = join(deptRoot, dept, "agents");
-    if (!existsSync(agentsSrc)) continue;
-    try {
-      for (const agentFile of readdirSync(agentsSrc)) {
-        if (!agentFile.endsWith(".md")) continue;
-        const srcFile = join(agentsSrc, agentFile);
-        // Safety: don't deploy anything that's not a regular file.
-        try {
-          if (!statSync(srcFile).isFile()) continue;
-        } catch {
-          continue;
-        }
-        const baseName = agentFile.replace(/\.md$/, "");
-        copyFileSync(srcFile, join(agentsBase, `arka-${baseName}.md`));
-        agentDeployed++;
-      }
-    } catch {
-      // Silently skip departments with unreadable agents dirs.
-    }
-  }
-  if (agentDeployed > 0) {
-    ok(`${agentDeployed} agent personas installed (~/.claude/agents/arka-*.md)`);
+  if (skillCounts.agents > 0) {
+    ok(`${skillCounts.agents} agent personas installed (~/.claude/agents/arka-*.md)`);
   }
 
   // ── MCP infrastructure ──────────────────────────────────────────────
@@ -922,7 +806,18 @@ function installSkill(config, installDir) {
       }
     }
 
-    ok("MCP infrastructure deployed (profiles, stacks, scripts, arka-prompts server)");
+    // Deploy arka-tools server to mcp-tools/ (F2-3: programmatic tools)
+    const mcpToolsSrc = join(mcpsSrc, "arka-tools");
+    const mcpToolsDest = join(skillsBase, "arka", "mcp-tools");
+    if (existsSync(mcpToolsSrc)) {
+      ensureDir(mcpToolsDest);
+      for (const f of ["server.py", "pyproject.toml"]) {
+        const src = join(mcpToolsSrc, f);
+        if (existsSync(src)) copyFileSync(src, join(mcpToolsDest, f));
+      }
+    }
+
+    ok("MCP infrastructure deployed (profiles, stacks, scripts, arka-prompts + arka-tools servers)");
 
     // Higgsfield MCP is registered but requires an account + API key to connect.
     // Non-blocking warning: the install succeeds even without a Higgsfield account.

package/installer/mcp-runner.js

@@ -0,0 +1,108 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+import { getArkaosPython, getRepoRoot } from "./python-resolver.js";
+
+// F2-7a — `npx arkaos mcp start`: run the arka-tools MCP server (stdio)
+// outside Claude Code (other runtimes, debugging, CI smoke tests).
+//
+// Resolution order mirrors production first: mcps/registry.json runs the
+// server via `uv --directory <toolsDir> run server.py`, so when uv is on
+// PATH we replicate that exact invocation. Fallback is the ArkaOS venv
+// python — but NO installer pip path installs `mcp[cli]` (the pyproject
+// [mcp] extra exists for tests only), so the fallback preflights
+// `import mcp` and fails HONESTLY with both remediations instead of a
+// stack trace at first tool call.
+
+export function toolsDir(home = homedir()) {
+  return join(home, ".claude", "skills", "arka", "mcp-tools");
+}
+
+function uvAvailable(spawn = spawnSync) {
+  const probe = spawn("uv", ["--version"], { stdio: "ignore", timeout: 5000 });
+  return !probe.error && probe.status === 0;
+}
+
+function venvHasMcp(py, spawn = spawnSync) {
+  const probe = spawn(py, ["-c", "import mcp"], {
+    stdio: "ignore",
+    timeout: 15000,
+  });
+  return !probe.error && probe.status === 0;
+}
+
+/**
+ * Resolve how to launch the arka-tools server.
+ * Returns {cmd, args, kind: "uv"|"venv"} or {error: string}.
+ * Injectable deps keep this unit-testable without real binaries.
+ */
+export function resolveRunner({
+  home = homedir(),
+  spawn = spawnSync,
+  pythonResolver = getArkaosPython,
+} = {}) {
+  const dir = toolsDir(home);
+  if (!existsSync(join(dir, "server.py"))) {
+    return {
+      error:
+        "arka-tools is not deployed (missing " + join(dir, "server.py") +
+        ").\nRun: npx arkaos install",
+    };
+  }
+  if (uvAvailable(spawn)) {
+    // Exact replica of the mcps/registry.json invocation Claude Code uses.
+    return { kind: "uv", cmd: "uv", args: ["--directory", dir, "run", "server.py"] };
+  }
+  const py = pythonResolver();
+  if (!py) {
+    return { error: "No Python found. Run: npx arkaos install" };
+  }
+  if (!venvHasMcp(py, spawn)) {
+    return {
+      error:
+        "arka-tools needs the MCP SDK and neither runner is ready. Fix one of:\n" +
+        "  1. Install uv (recommended): https://docs.astral.sh/uv\n" +
+        "  2. ~/.arkaos/venv/bin/pip install 'mcp[cli]>=1.2.0'",
+    };
+  }
+  return { kind: "venv", cmd: py, args: [join(dir, "server.py")] };
+}
+
+/**
+ * Start the server in the foreground (stdio transport — the MCP client
+ * owns the lifecycle; there is no daemon to manage). Returns the exit
+ * code to propagate.
+ */
+export function startServer({
+  write = false,
+  home = homedir(),
+  spawn = spawnSync,
+  pythonResolver = getArkaosPython,
+  repoRootResolver = getRepoRoot,
+  log = console.error,
+} = {}) {
+  const runner = resolveRunner({ home, spawn, pythonResolver });
+  if (runner.error) {
+    log(runner.error);
+    return 1;
+  }
+  const env = { ...process.env };
+  // repoRootResolver walks .repo-path/install-manifest — NEVER anchor on
+  // the npx cache dir, which `npm cache clean` purges at any time.
+  // Injectable so tests assert the positive ARKA_OS path (QG 7a M1).
+  const repoRoot = repoRootResolver();
+  if (repoRoot) env.ARKA_OS = repoRoot;
+  if (write) {
+    env.ARKA_TOOLS_WRITE = "1"; // server.py requires the exact value "1"
+  }
+  log(`arka-tools MCP server starting (${runner.kind}, stdio)` +
+    (write ? " — WRITES ENABLED (ARKA_TOOLS_WRITE=1)" : " — read-only"));
+  const result = spawn(runner.cmd, runner.args, { stdio: "inherit", env });
+  if (result.error) {
+    log(`Failed to start: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 0;
+}

package/installer/skill-deploy.js

@@ -0,0 +1,189 @@
+import {
+  copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync,
+  statSync, writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { resolveFile } from "./path-resolver.js";
+
+// Single skill-deployment implementation shared by the fresh-install
+// path (index.js::installSkill) and the update path (update.js §6) —
+// the same single-source pattern as hook-lib.js::copyHookLib, and for
+// the same reason: the two loops HAD drifted. update.js §6 deployed
+// hubs + sub-skills + agents but never the 14 meta skills
+// (arka/skills/* — including arka-flow, the evidence-flow
+// NON-NEGOTIABLE) nor the nested reference bundle, so any update-only
+// machine was silently missing them (F2-7c-pre).
+//
+// Markdown semantics: safeResolveMarkdown everywhere — resolveFile
+// substitutes ${VAR} path tokens and falls back to a raw copy when
+// resolution fails. This is the update.js behavior; index.js used to
+// raw-copy, so unifying on the resolving superset fixes install too.
+
+function listSubdirs(parent) {
+  if (!existsSync(parent)) return [];
+  try {
+    return readdirSync(parent, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+function safeResolveMarkdown(src, dst) {
+  try {
+    resolveFile(src, dst);
+  } catch {
+    copyFileSync(src, dst);
+  }
+}
+
+export function copySkillResources(skillSrcDir, skillDestDir) {
+  for (const res of ["scripts", "references", "assets"]) {
+    const src = join(skillSrcDir, res);
+    if (!existsSync(src)) continue;
+    try {
+      cpSync(src, join(skillDestDir, res), { recursive: true });
+    } catch {
+      // Best-effort — a missing resource dir must not break deploy.
+    }
+  }
+}
+
+function deployTopLevelSkill(skillSrcDir, arkaName, skillsBase) {
+  const skillMd = join(skillSrcDir, "SKILL.md");
+  if (!existsSync(skillMd)) return false;
+  const dest = join(skillsBase, arkaName);
+  mkdirSync(dest, { recursive: true });
+  safeResolveMarkdown(skillMd, join(dest, "SKILL.md"));
+  copySkillResources(skillSrcDir, dest);
+  return true;
+}
+
+/**
+ * Deploy the full skill surface: main /arka skill (+ nested reference
+ * bundle), department hubs, sub-skills, meta skills and agent personas.
+ * Copy-only — never deletes anything already deployed.
+ *
+ * Returns per-category counts so both callers can keep their own log
+ * style. `version`/`repoRoot` stamp the main skill's VERSION and
+ * .repo-path exactly as both callers did before.
+ */
+export function deploySkills({
+  repoRoot,
+  skillsBase,
+  agentsBase = null,
+  version = "",
+  mode = "full",
+  log = () => {},
+}) {
+  const counts = { main: 0, bundle: 0, depts: 0, subs: 0, meta: 0, agents: 0 };
+  // Curated mode (F2-7c): sub-skills outside the curated cut stay in
+  // the repo and ship via the marketplace plugins instead. The curated
+  // classification comes from the GENERATED knowledge/skills-manifest
+  // (drift-locked to config/skills-curated.yaml). Manifest unreadable
+  // -> deploy everything (fail-open: never silently shrink an install
+  // because a file was missing).
+  const curatedFilter = mode === "curated"
+    ? loadCuratedFilter(repoRoot)
+    : null;
+
+  // ── Main /arka skill + nested reference bundle ──────────────────────
+  const skillSrc = join(repoRoot, "arka", "SKILL.md");
+  const skillDest = join(skillsBase, "arka");
+  mkdirSync(skillDest, { recursive: true });
+  if (existsSync(skillSrc)) {
+    safeResolveMarkdown(skillSrc, join(skillDest, "SKILL.md"));
+    writeFileSync(join(skillDest, ".repo-path"), repoRoot);
+    if (version) writeFileSync(join(skillDest, "VERSION"), version);
+    counts.main = 1;
+    const nestedSrc = join(repoRoot, "arka", "skills");
+    if (existsSync(nestedSrc)) {
+      try {
+        cpSync(nestedSrc, join(skillDest, "skills"), { recursive: true });
+        counts.bundle = 1;
+      } catch {
+        // Bundled references only — never fail the deploy over them.
+      }
+    }
+  }
+
+  // ── Department hubs + sub-skills ────────────────────────────────────
+  const deptRoot = join(repoRoot, "departments");
+  for (const dept of listSubdirs(deptRoot)) {
+    if (deployTopLevelSkill(join(deptRoot, dept), `arka-${dept}`, skillsBase)) {
+      counts.depts++;
+    }
+    const deptSkillsDir = join(deptRoot, dept, "skills");
+    for (const sub of listSubdirs(deptSkillsDir)) {
+      if (curatedFilter && !curatedFilter.has(sub)) continue;
+      if (deployTopLevelSkill(
+        join(deptSkillsDir, sub), `arka-${sub}`, skillsBase)) {
+        counts.subs++;
+      }
+    }
+  }
+
+  // ── Meta skills (arka/skills/* as invocable top-level arka-<skill>) ─
+  const metaRoot = join(repoRoot, "arka", "skills");
+  for (const meta of listSubdirs(metaRoot)) {
+    if (deployTopLevelSkill(join(metaRoot, meta), `arka-${meta}`, skillsBase)) {
+      counts.meta++;
+    }
+  }
+
+  // ── Agent personas ──────────────────────────────────────────────────
+  if (agentsBase) {
+    counts.agents = deployAgents(deptRoot, agentsBase);
+  }
+
+  log(counts);
+  return counts;
+}
+
+function loadCuratedFilter(repoRoot) {
+  try {
+    const manifest = JSON.parse(readFileSync(
+      join(repoRoot, "knowledge", "skills-manifest.json"), "utf-8"));
+    const curated = new Set();
+    for (const [slug, entry] of Object.entries(manifest.skills || {})) {
+      if (entry.curated) curated.add(slug);
+    }
+    return curated.size > 0 ? curated : null;
+  } catch {
+    return null; // fail-open: full deploy beats a silently empty one
+  }
+}
+
+function deployAgents(deptRoot, agentsBase) {
+  mkdirSync(agentsBase, { recursive: true });
+  let deployed = 0;
+  for (const dept of listSubdirs(deptRoot)) {
+    const agentsSrc = join(deptRoot, dept, "agents");
+    if (!existsSync(agentsSrc)) continue;
+    try {
+      deployed += deployDeptAgents(agentsSrc, agentsBase);
+    } catch {
+      // Unreadable agents dir — skip the department, not the deploy.
+    }
+  }
+  return deployed;
+}
+
+function deployDeptAgents(agentsSrc, agentsBase) {
+  let deployed = 0;
+  for (const file of readdirSync(agentsSrc)) {
+    if (!file.endsWith(".md")) continue;
+    const srcFile = join(agentsSrc, file);
+    try {
+      if (!statSync(srcFile).isFile()) continue;
+    } catch {
+      continue;
+    }
+    copyFileSync(
+      srcFile, join(agentsBase, `arka-${file.replace(/\.md$/, "")}.md`));
+    deployed++;
+  }
+  return deployed;
+}

package/installer/skills-mode.js

@@ -0,0 +1,64 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// Persisted skills-deploy mode (F2-7c deprecation window, user-data
+// pattern of v2.19): fresh installs default to the curated cut; update
+// preserves whatever the machine already chose; machines predating the
+// mode file stay on "full" WITH a deprecation notice — an update must
+// never silently shrink an installed surface. Phase 2 (curated default
+// for everyone + whitelist-only sweep) ships separately, gated on
+// doctor telemetry about how many installs remain "full".
+
+const MODE_FILE = () => join(homedir(), ".arkaos", "skills-mode.json");
+const VALID_MODES = new Set(["curated", "full"]);
+
+export function readSkillsMode() {
+  try {
+    const data = JSON.parse(readFileSync(MODE_FILE(), "utf-8"));
+    return VALID_MODES.has(data.mode) ? data.mode : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeSkillsMode(mode) {
+  if (!VALID_MODES.has(mode)) return false;
+  try {
+    mkdirSync(join(homedir(), ".arkaos"), { recursive: true });
+    writeFileSync(MODE_FILE(), JSON.stringify({ mode }) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the mode for THIS run. `flag` is the --skills CLI value
+ * (persisted when valid); `fresh` marks a fresh install (no mode file
+ * -> curated). Returns { mode, deprecated } where `deprecated` flags a
+ * legacy full-mode machine that should see the migration notice.
+ */
+export function resolveSkillsMode({ flag = "", fresh = false } = {}) {
+  if (VALID_MODES.has(flag)) {
+    writeSkillsMode(flag);
+    return { mode: flag, deprecated: false };
+  }
+  const persisted = readSkillsMode();
+  if (persisted) return { mode: persisted, deprecated: false };
+  if (fresh) {
+    writeSkillsMode("curated");
+    return { mode: "curated", deprecated: false };
+  }
+  return { mode: "full", deprecated: true };
+}
+
+export function deprecationNotice() {
+  return (
+    "[arka:deprecated] Full skill set (274) is deprecated; the default "
+    + "becomes the curated 69 in a future release. Switch now: "
+    + "npx arkaos update --skills curated (a la carte packs: "
+    + "/plugin install arkaos-<dept>@arkaos). Opt out permanently: "
+    + "npx arkaos update --skills full"
+  );
+}