@cardor/agent-harness-kit 1.10.5 → 1.11.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 import {
   findConfigFile,
   loadConfig
-} from "./chunk-D64KK6UU.js";
+} from "./chunk-U3O77CGE.js";
 import {
   DEFAULT_MARKDOWN_PATH,
   DEFAULT_SQLITE_PATH,
@@ -24,7 +24,7 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 
 // src/core/materializer/claude-code.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
 import { join as join5, resolve as resolve3 } from "path";
 
 // src/utils/file.ts
@@ -335,6 +335,37 @@ import { fileURLToPath as fileURLToPath2 } from "url";
 import { readFileSync as readFileSync3 } from "fs";
 import { dirname as dirname2, join as join3 } from "path";
 import { fileURLToPath } from "url";
+
+// src/core/materializer/agent-restrictions.ts
+var AGENT_RESTRICTIONS = {
+  lead: "no-write",
+  explorer: "no-write",
+  consultant: "no-write",
+  builder: "none",
+  reviewer: "no-write"
+};
+function restrictionFor(agentName) {
+  return AGENT_RESTRICTIONS[agentName] ?? "no-write";
+}
+function claudeDisallowedTools(agentName) {
+  return restrictionFor(agentName) === "no-write" ? ["Write", "Edit"] : [];
+}
+function opencodePermissions(agentName) {
+  return restrictionFor(agentName) === "no-write" ? { edit: "deny" } : {};
+}
+function codexSandboxMode(agentName) {
+  return restrictionFor(agentName) === "no-write" ? "read-only" : "workspace-write";
+}
+var CODEX_READ_ONLY_NOTICE = `## Tool restrictions (enforced by the sandbox)
+
+This agent runs with \`sandbox_mode = "read-only"\`. You MUST NOT create, modify, or delete any file: no \`Write\`, no \`Edit\`, no \`apply_patch\`, and no shell command that writes to disk (\`>\`, \`tee\`, \`sed -i\`, \`mv\`, \`rm\`, ...).
+
+These tools may still appear available to you. The sandbox will reject the call. Do not retry a rejected write \u2014 report it as a blocker instead.`;
+function codexRestrictionNotice(agentName) {
+  return restrictionFor(agentName) === "no-write" ? CODEX_READ_ONLY_NOTICE : "";
+}
+
+// src/core/materializer/templates.ts
 var __dirname = dirname2(fileURLToPath(import.meta.url));
 var TEMPLATES_DIR = join3(__dirname, "agent-templates");
 function loadAgentTemplate(name, vars = {}) {
@@ -530,11 +561,7 @@ If orchestrating: Agent definition files in .claude/agents/
 \`\`\`
 `;
 }
-function modelField(model) {
-  return model ? `, model: ${JSON.stringify(model)}` : "";
-}
 function configObjectBody(params) {
-  const models = params.models ?? {};
   const isGlobal = params.scope === "global";
   const markdownFallbackLine = isGlobal ? `markdownFallback: { enabled: true },` : `markdownFallback: { enabled: true, path: '.harness/current.md' },`;
   return `  project: {
@@ -545,14 +572,13 @@ function configObjectBody(params) {
 
   provider: '${params.provider}',
 
-  agents: {
-    lead:     { instructionsPath: null${modelField(models.lead)} },
-    explorer: { instructionsPath: null, allowedPaths: ['${params.docsPath}', './src']${modelField(models.explorer)} },
-    builder:  { instructionsPath: null, writablePaths: ['./src', './tests']${modelField(models.builder)} },
-    reviewer: { instructionsPath: null${modelField(models.reviewer)} },
-    ${models.consultant ? `consultant: { instructionsPath: null${modelField(models.consultant)} },
-    ` : ""}custom:   [],
-  },
+  // There is no 'agents' key. Agent files are yours: edit the role prompt and
+  // the 'model:' frontmatter line directly in the generated file. 'ahk build'
+  // creates them when missing and never overwrites them \u2014 use
+  // 'ahk build --force' to regenerate them from the packaged templates.
+  // What each role may NOT do is enforced per-tool inside those files
+  // (disallowedTools / permission.edit / sandbox_mode); see
+  // src/core/materializer/agent-restrictions.ts.
 
   // SQLite (default). Switch to postgres/mysql by changing database.type.
   // database: { type: 'postgres', connectionString: process.env.DATABASE_URL },
@@ -587,6 +613,47 @@ function configObjectBody(params) {
   },
 `;
 }
+function configObject(params) {
+  const isGlobal = params.scope === "global";
+  return {
+    project: {
+      name: params.name,
+      description: params.description,
+      docsPath: params.docsPath
+    },
+    provider: params.provider,
+    // There is no 'agents' key here either — it was removed from the config
+    // entirely, so the JSON variant must not reintroduce it.
+    database: { type: "sqlite" },
+    storage: {
+      dir: ".harness",
+      tasks: { adapter: params.tasksAdapter },
+      sections: {
+        toolsUsed: true,
+        filesModified: true,
+        result: true,
+        blockers: true,
+        nextSteps: false
+      },
+      // Same scope rule as configObjectBody(): 'global' has no local path to
+      // declare, so markdownFallback.path is omitted for it.
+      markdownFallback: isGlobal ? { enabled: true } : { enabled: true, path: ".harness/current.md" },
+      scope: params.scope,
+      projectId: params.projectId
+    },
+    health: {
+      scriptPath: "./health.sh",
+      required: true
+    },
+    tools: {
+      mcp: { enabled: true, port: params.port },
+      scripts: { enabled: true, outputDir: "./.harness/scripts" }
+    }
+  };
+}
+function configJson(params) {
+  return JSON.stringify(configObject(params), null, 2) + "\n";
+}
 function configTs(params) {
   return `import type { HarnessConfig } from '@cardor/agent-harness-kit'
 
@@ -643,81 +710,83 @@ function stripFrontmatter(md) {
   }
   return { description, body };
 }
-function toCodexToml(name, description, body, sandboxMode, model) {
+function toCodexToml(tomlName, agentName, description, body) {
   const safe = (s) => s.replace(/"""/g, '""\\u0022');
-  const trimmedModel = model?.trim() ?? "";
-  const modelLine = trimmedModel.length >= 3 ? `model = "${trimmedModel}"
-` : "";
-  return `name = "${name}"
+  const sandboxMode = codexSandboxMode(agentName);
+  const notice = codexRestrictionNotice(agentName);
+  const instructions = notice ? `${body.trimEnd()}
+
+---
+
+${notice}` : body.trimEnd();
+  return `name = "${tomlName}"
 sandbox_mode = "${sandboxMode}"
-${modelLine}
+
 description = """
 ${safe(description)}
 """
 
 developer_instructions = """
-${safe(body.trimEnd())}
+${safe(instructions)}
 """
 `;
 }
 function agentLeadToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("lead", vars));
-  return toCodexToml("lead", description, body, "read-only", vars.model);
+  return toCodexToml("lead", "lead", description, body);
 }
 function agentLeadAsDefaultToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("lead", vars));
-  return toCodexToml("default", description, body, "read-only", vars.model);
+  return toCodexToml("default", "lead", description, body);
 }
 function agentExplorerToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("explorer", vars));
-  return toCodexToml("explorer", description, body, "read-only", vars.model);
+  return toCodexToml("explorer", "explorer", description, body);
 }
 function agentBuilderToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("builder", vars));
-  return toCodexToml("builder", description, body, "workspace-write", vars.model);
+  return toCodexToml("builder", "builder", description, body);
 }
 function agentReviewerToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("reviewer", vars));
-  return toCodexToml("reviewer", description, body, "read-only", vars.model);
+  return toCodexToml("reviewer", "reviewer", description, body);
 }
 function agentConsultantToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("consultant", vars));
-  return toCodexToml("consultant", description, body, "read-only", vars.model);
-}
-function translateFrontmatterForClaudeCode(md, agentName, model) {
-  const permissionsMap = {
-    lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
-    explorer: [...MCP_CLAUDE_PERMISSIONS_EXPLORER],
-    consultant: [...MCP_CLAUDE_PERMISSIONS_CONSULTANT],
-    builder: [...MCP_CLAUDE_PERMISSIONS_BUILDER],
-    reviewer: [...MCP_CLAUDE_PERMISSIONS_REVIEWER]
-  };
-  const permissions = permissionsMap[agentName] ?? MCP_CLAUDE_PERMISSIONS;
-  const mcpLines = permissions.map((t) => `  - ${t}`).join("\n");
-  let result = md.replace(/(tools:\n(?:  - (?!mcp__)[^\n]+\n)+)/, (match) => {
-    const trimmed = match.trimEnd();
-    return `${trimmed}
-  - Task
-${mcpLines}
+  return toCodexToml("consultant", "consultant", description, body);
+}
+function stripFrontmatterBlockSequence(md, key) {
+  const re = new RegExp(`^${key}:\\n(?:  - [^\\n]+\\n)+`, "m");
+  return md.replace(re, "");
+}
+function appendFrontmatterBlockSequence(md, key, values) {
+  if (values.length === 0) return md;
+  const block = `${key}:
+${values.map((v4) => `  - ${v4}`).join("\n")}
 `;
-  });
-  if (model) {
-    result = injectModelFrontmatterLine(result, model);
-  }
-  return result;
+  return md.replace(/^---\n([\s\S]*?)^---\n/m, (_m, body) => `---
+${body}${block}---
+`);
 }
-function injectModelFrontmatterLine(md, model) {
-  if (/^model:\s*.*$/m.test(md)) {
-    return md.replace(/^model:\s*.*$/m, `model: ${model}`);
-  }
-  return md.replace(/^(name:.*)$/m, `$1
-model: ${model}`);
+function appendFrontmatterMapping(md, key, entries) {
+  const keys = Object.keys(entries);
+  if (keys.length === 0) return md;
+  const block = `${key}:
+${keys.map((k) => `  ${k}: ${entries[k]}`).join("\n")}
+`;
+  return md.replace(/^---\n([\s\S]*?)^---\n/m, (_m, body) => `---
+${body}${block}---
+`);
 }
-function translateFrontmatterForOpenCode(md) {
-  return md.replace(/(tools:\n(?:  - [^\n]+\n)+)/, (match) => {
-    const tools = [...match.matchAll(/  - ([^\n]+)/g)].map((m) => m[1].trim());
-    return "tools:\n" + tools.map((t) => `  ${t.toLocaleLowerCase()}: true`).join("\n") + "\n";
-  });
+function translateFrontmatterForClaudeCode(md, agentName) {
+  let result = stripFrontmatterBlockSequence(md, "tools");
+  result = stripFrontmatterBlockSequence(result, "disallowedTools");
+  return appendFrontmatterBlockSequence(result, "disallowedTools", claudeDisallowedTools(agentName));
+}
+function translateFrontmatterForOpenCode(md, agentName) {
+  let result = stripFrontmatterBlockSequence(md, "tools");
+  result = stripFrontmatterBlockSequence(result, "disallowedTools");
+  return appendFrontmatterMapping(result, "permission", opencodePermissions(agentName));
 }
 var GITIGNORE_ENTRIES = `
 # agent-harness-kit
@@ -729,11 +798,43 @@ var GITIGNORE_ENTRIES = `
 
 // src/core/materializer/scaffold-utils.ts
 var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
-function writeAgentFile(cwd2, relPath, content) {
-  const abs = join4(cwd2, relPath);
-  if (existsSync3(abs)) return;
-  mkdirSync3(resolve2(abs, ".."), { recursive: true });
-  writeFileSync3(abs, content, "utf8");
+function writeAgentFiles(cwd2, entries, opts = {}) {
+  const result = { created: [], overwritten: [], preserved: [] };
+  const existing = entries.filter((e) => existsSync3(join4(cwd2, e.relPath)));
+  if (opts.force && existing.length > 0) {
+    if (!opts.backupRoot) {
+      throw new Error(
+        "writeAgentFiles: force is set and existing agent files would be overwritten, but no backupRoot was provided. Refusing to overwrite without a backup."
+      );
+    }
+    const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const backupDir = join4(opts.backupRoot, `agents-${stamp}`);
+    try {
+      for (const entry of existing) {
+        const dest = join4(backupDir, entry.relPath);
+        mkdirSync3(resolve2(dest, ".."), { recursive: true });
+        writeFileSync3(dest, readFileSync4(join4(cwd2, entry.relPath), "utf8"), "utf8");
+      }
+    } catch (err) {
+      throw new Error(
+        `Could not back up existing agent files to ${backupDir} (${err instanceof Error ? err.message : String(err)}). Aborting WITHOUT overwriting anything \u2014 no agent file was modified.`
+      );
+    }
+    result.backupDir = backupDir;
+  }
+  for (const entry of entries) {
+    const abs = join4(cwd2, entry.relPath);
+    const exists = existsSync3(abs);
+    if (exists && !opts.force) {
+      result.preserved.push(entry.relPath);
+      continue;
+    }
+    mkdirSync3(resolve2(abs, ".."), { recursive: true });
+    writeFileSync3(abs, entry.content, "utf8");
+    if (exists) result.overwritten.push(entry.relPath);
+    else result.created.push(entry.relPath);
+  }
+  return result;
 }
 function appendGitignore(cwd2) {
   const giPath = join4(cwd2, ".gitignore");
@@ -758,6 +859,16 @@ function writeSkills(cwd2, skillsDir) {
 }
 
 // src/core/materializer/claude-code.ts
+function claudeAgentFiles(config) {
+  const projectName = config.project.name;
+  return [
+    { relPath: ".claude/agents/lead.md", content: translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead") },
+    { relPath: ".claude/agents/explorer.md", content: translateFrontmatterForClaudeCode(agentExplorer({ projectName }), "explorer") },
+    { relPath: ".claude/agents/consultant.md", content: translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant") },
+    { relPath: ".claude/agents/builder.md", content: translateFrontmatterForClaudeCode(agentBuilder({ projectName }), "builder") },
+    { relPath: ".claude/agents/reviewer.md", content: translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer") }
+  ];
+}
 var ClaudeCodeMaterializer = class {
   async scaffold(config, opts) {
     const { cwd: cwd2 } = opts;
@@ -781,26 +892,14 @@ No tasks in progress.
 `
       );
     }
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    const leadModel = config.agents.lead.model;
-    const explorerModel = config.agents.explorer.model;
-    const consultantModel = config.agents.consultant?.model;
-    const builderModel = config.agents.builder.model;
-    const reviewerModel = config.agents.reviewer.model;
-    writeAgentFile(cwd2, ".claude/agents/lead.md", translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead", leadModel));
-    writeAgentFile(cwd2, ".claude/agents/explorer.md", translateFrontmatterForClaudeCode(agentExplorer({ projectName, allowedPaths }), "explorer", explorerModel));
-    writeAgentFile(cwd2, ".claude/agents/consultant.md", translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant", consultantModel));
-    writeAgentFile(cwd2, ".claude/agents/builder.md", translateFrontmatterForClaudeCode(agentBuilder({ projectName, writablePaths }), "builder", builderModel));
-    writeAgentFile(cwd2, ".claude/agents/reviewer.md", translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer", reviewerModel));
+    writeAgentFiles(cwd2, claudeAgentFiles(config));
     mergeClaudeMcpJson(join5(cwd2, ".mcp.json"), config.tools.mcp.port, detectPackageManager(cwd2));
     mergeClaudeSettingsJson(join5(cwd2, ".claude/settings.json"));
     mergeClaudeSettingsLocalJson(join5(cwd2, ".claude/settings.local.json"));
     appendGitignore(cwd2);
     writeSkills(cwd2, ".claude/skills");
   }
-  async build(config, cwd2) {
+  async build(config, cwd2, opts = {}) {
     const write2 = (relPath, content) => {
       const abs = join5(cwd2, relPath);
       mkdirSync4(resolve3(abs, ".."), { recursive: true });
@@ -808,64 +907,54 @@ No tasks in progress.
     };
     write2("AGENTS.md", agentsMd(config));
     write2("CLAUDE.md", claudeMd(config));
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    const leadModel = config.agents.lead.model;
-    const explorerModel = config.agents.explorer.model;
-    const consultantModel = config.agents.consultant?.model;
-    const builderModel = config.agents.builder.model;
-    const reviewerModel = config.agents.reviewer.model;
-    write2(".claude/agents/lead.md", translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead", leadModel));
-    write2(".claude/agents/explorer.md", translateFrontmatterForClaudeCode(agentExplorer({ projectName, allowedPaths }), "explorer", explorerModel));
-    write2(".claude/agents/consultant.md", translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant", consultantModel));
-    write2(".claude/agents/builder.md", translateFrontmatterForClaudeCode(agentBuilder({ projectName, writablePaths }), "builder", builderModel));
-    write2(".claude/agents/reviewer.md", translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer", reviewerModel));
+    const agents = writeAgentFiles(cwd2, claudeAgentFiles(config), {
+      force: opts.force,
+      backupRoot: join5(cwd2, config.storage.dir, "backups")
+    });
     mergeClaudeMcpJson(join5(cwd2, ".mcp.json"), config.tools.mcp.port, detectPackageManager(cwd2));
     mergeClaudeSettingsJson(join5(cwd2, ".claude/settings.json"));
     mergeClaudeSettingsLocalJson(join5(cwd2, ".claude/settings.local.json"));
     writeSkills(cwd2, ".claude/skills");
+    return { agents };
   }
   async migrate(config, _to, _cwd) {
     void config;
   }
-  async syncPermissions(cwd2) {
-    const AGENT_TOOLS = {
-      lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
-      explorer: [...MCP_CLAUDE_PERMISSIONS_EXPLORER],
-      consultant: [...MCP_CLAUDE_PERMISSIONS_CONSULTANT],
-      builder: [...MCP_CLAUDE_PERMISSIONS_BUILDER],
-      reviewer: [...MCP_CLAUDE_PERMISSIONS_REVIEWER]
-    };
-    for (const [agent, tools] of Object.entries(AGENT_TOOLS)) {
-      const filePath = join5(cwd2, ".claude", "agents", `${agent}.md`);
-      if (!existsSync4(filePath)) {
-        console.log(`  ${agent}.md not found \u2014 skipping`);
-        continue;
-      }
-      const content = readFileSync5(filePath, "utf-8");
-      const updated = content.replace(
-        /(tools:\n)((?:  - [^\n]+\n)*)/m,
-        (_match, header, toolsSection) => {
-          const nativeLines = toolsSection.split("\n").filter((line) => line.trim() && !line.includes("mcp__"));
-          const nativeSection = nativeLines.length ? nativeLines.join("\n") + "\n" : "";
-          const mcpSection = tools.map((t) => `  - ${t}`).join("\n") + "\n";
-          return header + nativeSection + mcpSection;
-        }
-      );
-      if (updated === content) {
-        console.log(`  ${agent}.md already in sync`);
-      } else {
-        writeFileSync4(filePath, updated, "utf-8");
-        console.log(`  ${agent}.md updated`);
-      }
-    }
+  /**
+   * No-op by design.
+   *
+   * This used to rewrite the `tools:` frontmatter block of every agent file,
+   * re-injecting the canonical `mcp__agent-harness-kit__*` allowlist. Agent
+   * files no longer declare `tools` at all: they inherit the full tool set
+   * (Task and every MCP tool included) and express restrictions as a
+   * `disallowedTools` denylist instead.
+   *
+   * Keeping the old rewrite alive would be actively harmful — on a project
+   * upgraded from an older version, whose agent files still carry a legacy
+   * `tools:` block, it would re-inject the allowlist and silently undo the
+   * migration on exactly the files that most need it. Run `ahk build` to
+   * regenerate agent files in the current shape.
+   */
+  async syncPermissions(_cwd) {
+    console.log("  Agent files inherit tools and declare a disallowedTools denylist \u2014");
+    console.log("  there is no permission allowlist to sync. Run `ahk build` to regenerate them.");
   }
 };
 
 // src/core/materializer/codex-cli.ts
 import { existsSync as existsSync5, mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "fs";
 import { join as join6, resolve as resolve4 } from "path";
+function codexAgentFiles(config) {
+  const projectName = config.project.name;
+  return [
+    { relPath: ".codex/agents/lead.toml", content: agentLeadToml({ projectName }) },
+    { relPath: ".codex/agents/explorer.toml", content: agentExplorerToml({ projectName }) },
+    { relPath: ".codex/agents/consultant.toml", content: agentConsultantToml({ projectName }) },
+    { relPath: ".codex/agents/builder.toml", content: agentBuilderToml({ projectName }) },
+    { relPath: ".codex/agents/reviewer.toml", content: agentReviewerToml({ projectName }) },
+    { relPath: ".codex/agents/default.toml", content: agentLeadAsDefaultToml({ projectName }) }
+  ];
+}
 var CodexCliMaterializer = class {
   async scaffold(config, opts) {
     const { cwd: cwd2 } = opts;
@@ -892,47 +981,25 @@ No tasks in progress.
 `
       );
     }
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    const leadModel = config.agents.lead.model;
-    const explorerModel = config.agents.explorer.model;
-    const consultantModel = config.agents.consultant?.model;
-    const builderModel = config.agents.builder.model;
-    const reviewerModel = config.agents.reviewer.model;
-    writeAgentFile(cwd2, ".codex/agents/lead.toml", agentLeadToml({ projectName, model: leadModel }));
-    writeAgentFile(cwd2, ".codex/agents/explorer.toml", agentExplorerToml({ projectName, allowedPaths, model: explorerModel }));
-    writeAgentFile(cwd2, ".codex/agents/consultant.toml", agentConsultantToml({ projectName, model: consultantModel }));
-    writeAgentFile(cwd2, ".codex/agents/builder.toml", agentBuilderToml({ projectName, writablePaths, model: builderModel }));
-    writeAgentFile(cwd2, ".codex/agents/reviewer.toml", agentReviewerToml({ projectName, model: reviewerModel }));
-    writeAgentFile(cwd2, ".codex/agents/default.toml", agentLeadAsDefaultToml({ projectName, model: leadModel }));
+    writeAgentFiles(cwd2, codexAgentFiles(config));
     mergeCodexConfigToml(join6(cwd2, ".codex/config.toml"), config.tools.mcp.port, detectPackageManager(cwd2));
     appendGitignore(cwd2);
     writeSkills(cwd2, ".agents/skills");
   }
-  async build(config, cwd2) {
+  async build(config, cwd2, opts = {}) {
     const write2 = (relPath, content) => {
       const abs = join6(cwd2, relPath);
       mkdirSync5(resolve4(abs, ".."), { recursive: true });
       writeFileSync5(abs, content, "utf8");
     };
     write2("AGENTS.md", agentsMd(config));
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    const leadModel = config.agents.lead.model;
-    const explorerModel = config.agents.explorer.model;
-    const consultantModel = config.agents.consultant?.model;
-    const builderModel = config.agents.builder.model;
-    const reviewerModel = config.agents.reviewer.model;
-    writeAgentFile(cwd2, ".codex/agents/lead.toml", agentLeadToml({ projectName, model: leadModel }));
-    writeAgentFile(cwd2, ".codex/agents/explorer.toml", agentExplorerToml({ projectName, allowedPaths, model: explorerModel }));
-    writeAgentFile(cwd2, ".codex/agents/consultant.toml", agentConsultantToml({ projectName, model: consultantModel }));
-    writeAgentFile(cwd2, ".codex/agents/builder.toml", agentBuilderToml({ projectName, writablePaths, model: builderModel }));
-    writeAgentFile(cwd2, ".codex/agents/reviewer.toml", agentReviewerToml({ projectName, model: reviewerModel }));
-    writeAgentFile(cwd2, ".codex/agents/default.toml", agentLeadAsDefaultToml({ projectName, model: leadModel }));
+    const agents = writeAgentFiles(cwd2, codexAgentFiles(config), {
+      force: opts.force,
+      backupRoot: join6(cwd2, config.storage.dir, "backups")
+    });
     mergeCodexConfigToml(join6(cwd2, ".codex/config.toml"), config.tools.mcp.port, detectPackageManager(cwd2));
     writeSkills(cwd2, ".agents/skills");
+    return { agents };
   }
   async migrate(config, _to, _cwd) {
     void config;
@@ -945,6 +1012,16 @@ No tasks in progress.
 // src/core/materializer/opencode.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync6, writeFileSync as writeFileSync6 } from "fs";
 import { join as join7, resolve as resolve5 } from "path";
+function opencodeAgentFiles(config) {
+  const projectName = config.project.name;
+  return [
+    { relPath: ".opencode/agents/lead.md", content: translateFrontmatterForOpenCode(agentLead({ projectName }), "lead") },
+    { relPath: ".opencode/agents/explorer.md", content: translateFrontmatterForOpenCode(agentExplorer({ projectName }), "explorer") },
+    { relPath: ".opencode/agents/consultant.md", content: translateFrontmatterForOpenCode(agentConsultant({ projectName }), "consultant") },
+    { relPath: ".opencode/agents/builder.md", content: translateFrontmatterForOpenCode(agentBuilder({ projectName }), "builder") },
+    { relPath: ".opencode/agents/reviewer.md", content: translateFrontmatterForOpenCode(agentReviewer({ projectName }), "reviewer") }
+  ];
+}
 var OpenCodeMaterializer = class {
   async scaffold(config, opts) {
     const { cwd: cwd2 } = opts;
@@ -971,35 +1048,25 @@ No tasks in progress.
 `
       );
     }
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    writeAgentFile(cwd2, ".opencode/agents/lead.md", translateFrontmatterForOpenCode(agentLead({ projectName })));
-    writeAgentFile(cwd2, ".opencode/agents/explorer.md", translateFrontmatterForOpenCode(agentExplorer({ projectName, allowedPaths })));
-    writeAgentFile(cwd2, ".opencode/agents/consultant.md", translateFrontmatterForOpenCode(agentConsultant({ projectName })));
-    writeAgentFile(cwd2, ".opencode/agents/builder.md", translateFrontmatterForOpenCode(agentBuilder({ projectName, writablePaths })));
-    writeAgentFile(cwd2, ".opencode/agents/reviewer.md", translateFrontmatterForOpenCode(agentReviewer({ projectName })));
+    writeAgentFiles(cwd2, opencodeAgentFiles(config));
     mergeOpencodeJson(join7(cwd2, "opencode.json"), config.tools.mcp.port, detectPackageManager(cwd2));
     appendGitignore(cwd2);
     writeSkills(cwd2, ".opencode/skills");
   }
-  async build(config, cwd2) {
+  async build(config, cwd2, opts = {}) {
     const write2 = (relPath, content) => {
       const abs = join7(cwd2, relPath);
       mkdirSync6(resolve5(abs, ".."), { recursive: true });
       writeFileSync6(abs, content, "utf8");
     };
     write2("AGENTS.md", agentsMd(config));
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    writeAgentFile(cwd2, ".opencode/agents/lead.md", translateFrontmatterForOpenCode(agentLead({ projectName })));
-    writeAgentFile(cwd2, ".opencode/agents/explorer.md", translateFrontmatterForOpenCode(agentExplorer({ projectName, allowedPaths })));
-    writeAgentFile(cwd2, ".opencode/agents/consultant.md", translateFrontmatterForOpenCode(agentConsultant({ projectName })));
-    writeAgentFile(cwd2, ".opencode/agents/builder.md", translateFrontmatterForOpenCode(agentBuilder({ projectName, writablePaths })));
-    writeAgentFile(cwd2, ".opencode/agents/reviewer.md", translateFrontmatterForOpenCode(agentReviewer({ projectName })));
+    const agents = writeAgentFiles(cwd2, opencodeAgentFiles(config), {
+      force: opts.force,
+      backupRoot: join7(cwd2, config.storage.dir, "backups")
+    });
     mergeOpencodeJson(join7(cwd2, "opencode.json"), config.tools.mcp.port, detectPackageManager(cwd2));
     writeSkills(cwd2, ".opencode/skills");
+    return { agents };
   }
   async migrate(config, _to, _cwd) {
     void config;
@@ -1025,7 +1092,7 @@ function getMaterializer(provider) {
 
 // src/commands/build.ts
 async function runBuild(cwd2, opts) {
-  await buildOnce(cwd2);
+  await buildOnce(cwd2, opts.force);
   if (opts.sync) {
     p.log.step("Syncing agent permissions...");
     const config = await loadConfig(cwd2);
@@ -1037,25 +1104,48 @@ async function runBuild(cwd2, opts) {
     watch(cwd2, { recursive: false }, async (_, filename) => {
       if (filename?.startsWith("agent-harness-kit.config")) {
         p.log.step("Config changed \u2014 rebuilding...");
-        await buildOnce(cwd2);
+        await buildOnce(cwd2, false);
       }
     });
     await new Promise(() => {
     });
   }
 }
-async function buildOnce(cwd2) {
+async function buildOnce(cwd2, force) {
   const spinner6 = p.spinner();
   spinner6.start("Loading config...");
   try {
     const config = await loadConfig(cwd2);
     spinner6.message("Rebuilding files...");
     const materializer = getMaterializer(config.provider);
-    await materializer.build(config, cwd2);
+    const report = await materializer.build(config, cwd2, { force });
     spinner6.stop(pc.green("Build complete"));
     p.log.success("AGENTS.md");
     p.log.success(`Agent definitions (${config.provider})`);
     p.log.success("MCP config");
+    const { created, overwritten, preserved, backupDir } = report.agents;
+    if (created.length > 0) {
+      p.log.info(`Created ${created.length} missing agent file(s):
+  ${created.join("\n  ")}`);
+    }
+    if (overwritten.length > 0) {
+      p.log.warn(
+        pc.yellow(
+          `--force REGENERATED ${overwritten.length} existing agent file(s), discarding any customizations:
+  ` + overwritten.join("\n  ")
+        )
+      );
+      if (backupDir) {
+        p.log.info(pc.yellow(`  Previous content backed up \u2192 ${backupDir}`));
+      }
+    }
+    if (preserved.length > 0) {
+      p.log.info(
+        `Left ${preserved.length} existing agent file(s) untouched \u2014 agent files are yours to edit.
+  Re-run with --force to regenerate them from the packaged templates (this DESTROYS your edits;
+  a backup is written first).`
+      );
+    }
   } catch (err) {
     spinner6.stop(pc.red("Build failed"));
     p.log.error(err instanceof Error ? err.message : String(err));
@@ -1071,7 +1161,7 @@ import pc2 from "picocolors";
 
 // src/core/dashboard-server.ts
 import { watch as watch2 } from "fs";
-import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
 import { extname, join as join8 } from "path";
 import { serve } from "@hono/node-server";
 import { Hono } from "hono";
@@ -1114,7 +1204,7 @@ var MIME = {
   ".ttf": "font/ttf"
 };
 function fileResponse(filePath) {
-  const content = readFileSync6(filePath);
+  const content = readFileSync5(filePath);
   const mime = MIME[extname(filePath)] ?? "application/octet-stream";
   return new Response(content, {
     headers: { "Content-Type": mime, "Cache-Control": "no-cache" }
@@ -1299,7 +1389,7 @@ async function runDashboard(cwd2, opts) {
 import pc3 from "picocolors";
 
 // src/core/doctor.ts
-import { existsSync as existsSync9, readFileSync as readFileSync7 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync6 } from "fs";
 import { dirname as dirname6, join as join11 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 
@@ -1366,68 +1456,15 @@ function getProviderAgentInfo(provider) {
       return { agentsDir: ".claude/agents", ext: ".md" };
   }
 }
-function generateExpectedAgentContent(agentName, provider, vars) {
-  const { projectName, allowedPaths, writablePaths, model } = vars;
-  if (provider === "claude-code") {
-    const templateFns = {
-      lead: () => agentLead({ projectName }),
-      explorer: () => agentExplorer({ projectName, allowedPaths }),
-      consultant: () => agentConsultant({ projectName }),
-      builder: () => agentBuilder({ projectName, writablePaths }),
-      reviewer: () => agentReviewer({ projectName })
-    };
-    return translateFrontmatterForClaudeCode(templateFns[agentName](), agentName, model);
-  }
-  if (provider === "opencode") {
-    const templateFns = {
-      lead: () => agentLead({ projectName }),
-      explorer: () => agentExplorer({ projectName, allowedPaths }),
-      consultant: () => agentConsultant({ projectName }),
-      builder: () => agentBuilder({ projectName, writablePaths }),
-      reviewer: () => agentReviewer({ projectName })
-    };
-    return translateFrontmatterForOpenCode(templateFns[agentName]());
-  }
-  const tomlFns = {
-    lead: () => agentLeadToml({ projectName, model }),
-    explorer: () => agentExplorerToml({ projectName, allowedPaths, model }),
-    consultant: () => agentConsultantToml({ projectName, model }),
-    builder: () => agentBuilderToml({ projectName, writablePaths, model }),
-    reviewer: () => agentReviewerToml({ projectName, model })
-  };
-  return tomlFns[agentName]();
-}
-function checkAgentFilesAtRoot(agentsRoot, ext, provider, projectName, allowedPaths, writablePaths, models) {
+function checkAgentFilesAtRoot(agentsRoot, ext) {
   return AGENT_NAMES.map((name) => {
     const filePath = join11(agentsRoot, `${name}${ext}`);
-    if (!existsSync9(filePath)) {
-      return { name, status: "missing" };
-    }
-    try {
-      const live = readFileSync7(filePath, "utf8");
-      const expected = generateExpectedAgentContent(name, provider, {
-        projectName,
-        allowedPaths,
-        writablePaths,
-        model: models[name]
-      });
-      return { name, status: live === expected ? "ok" : "outdated" };
-    } catch {
-      return { name, status: "outdated" };
-    }
+    return { name, status: existsSync9(filePath) ? "ok" : "missing" };
   });
 }
-function checkAgentFiles(cwd2, provider, projectName, allowedPaths, writablePaths, models) {
+function checkAgentFiles(cwd2, provider) {
   const { agentsDir, ext } = getProviderAgentInfo(provider);
-  return checkAgentFilesAtRoot(
-    join11(cwd2, agentsDir),
-    ext,
-    provider,
-    projectName,
-    allowedPaths,
-    writablePaths,
-    models
-  );
+  return checkAgentFilesAtRoot(join11(cwd2, agentsDir), ext);
 }
 function getProviderSkillsDir(provider) {
   switch (provider) {
@@ -1450,8 +1487,8 @@ function checkSkillsAtRoot(skillsRoot) {
       return { name, status: "missing" };
     }
     try {
-      const live = readFileSync7(livePath, "utf8");
-      const source = readFileSync7(sourcePath, "utf8");
+      const live = readFileSync6(livePath, "utf8");
+      const source = readFileSync6(sourcePath, "utf8");
       return { name, status: live === source ? "ok" : "outdated" };
     } catch {
       return { name, status: "outdated" };
@@ -1475,17 +1512,7 @@ async function getDoctorStatus(cwd2) {
     };
   }
   const provider = config.provider;
-  const projectName = config.project.name;
-  const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-  const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-  const models = {
-    lead: config.agents.lead.model,
-    explorer: config.agents.explorer.model,
-    consultant: config.agents.consultant?.model,
-    builder: config.agents.builder.model,
-    reviewer: config.agents.reviewer.model
-  };
-  const agents = checkAgentFiles(cwd2, provider, projectName, allowedPaths, writablePaths, models);
+  const agents = checkAgentFiles(cwd2, provider);
   const skills = checkSkills(cwd2, provider);
   return { lib, agents, skills };
 }
@@ -1522,17 +1549,13 @@ function printAgentsSection(agents) {
     return;
   }
   const missing = agents.filter((a) => a.status === "missing");
-  const outdated = agents.filter((a) => a.status === "outdated");
-  if (missing.length === 0 && outdated.length === 0) {
-    ok("agent files", "all up to date");
+  if (missing.length === 0) {
+    ok("agent files", "all present");
     return;
   }
   for (const agent of missing) {
     warn("agent files", `${agent.name} missing`, "run: ahk build");
   }
-  for (const agent of outdated) {
-    warn("agent files", `${agent.name} outdated`, "run: ahk build");
-  }
 }
 function printSkillsSection(skills) {
   if (skills.length === 0) {
@@ -1700,9 +1723,9 @@ function getProviderHealthFiles(provider) {
 
 // src/commands/init.ts
 import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync8 } from "fs";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 import * as p3 from "@clack/prompts";
-import pc7 from "picocolors";
+import pc8 from "picocolors";
 
 // src/schema/init.ts
 import * as v from "valibot";
@@ -1755,13 +1778,52 @@ var cliFormWithRetry = async (formFn, schema) => {
 
 // src/commands/init-helpers.ts
 import { randomUUID } from "crypto";
-import { existsSync as existsSync11, readFileSync as readFileSync8 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync8 } from "fs";
+import { join as join14 } from "path";
+import pc7 from "picocolors";
+
+// src/core/local-install-guard.ts
+import { existsSync as existsSync11, readFileSync as readFileSync7 } from "fs";
 import { join as join13 } from "path";
 import pc6 from "picocolors";
+function isLocalInstallSatisfied(cwd2) {
+  const selfPkgPath = join13(cwd2, "package.json");
+  let projectPkg = null;
+  if (existsSync11(selfPkgPath)) {
+    try {
+      const selfPkg = JSON.parse(readFileSync7(selfPkgPath, "utf8"));
+      if (selfPkg?.name === pkg.name) return true;
+      projectPkg = selfPkg;
+    } catch {
+    }
+  }
+  const [scope, name] = pkg.name.split("/");
+  const localPath = pkg.name.startsWith("@") ? join13(cwd2, "node_modules", scope, name) : join13(cwd2, "node_modules", pkg.name);
+  if (existsSync11(localPath)) return true;
+  const isPnp = existsSync11(join13(cwd2, ".pnp.cjs")) || existsSync11(join13(cwd2, ".pnp.loader.mjs"));
+  if (isPnp && projectPkg) {
+    const deps = {
+      ...projectPkg.dependencies ?? {},
+      ...projectPkg.devDependencies ?? {}
+    };
+    if (Object.prototype.hasOwnProperty.call(deps, pkg.name)) return true;
+  }
+  return false;
+}
+function printLocalInstallWarning() {
+  console.error(pc6.yellow(`\u26A0 ${pkg.name} is not installed locally in this project.`));
+  console.error(pc6.dim("  This is only a recommendation for reproducibility: pinning a local"));
+  console.error(pc6.dim("  version keeps behavior consistent across your team and CI, instead of"));
+  console.error(pc6.dim("  drifting with whatever version is installed globally on each machine."));
+  console.error(pc6.dim(`  Run: npm install --save-dev ${pkg.name}`));
+  console.error(pc6.dim("  (or the equivalent for your package manager: pnpm add -D, yarn add --dev, bun add -d)"));
+}
+
+// src/commands/init-helpers.ts
 function readProjectNameFromPackageJson(cwd2) {
   try {
-    const pkgPath2 = join13(cwd2, "package.json");
-    if (!existsSync11(pkgPath2)) return null;
+    const pkgPath2 = join14(cwd2, "package.json");
+    if (!existsSync12(pkgPath2)) return null;
     const content = readFileSync8(pkgPath2, "utf8");
     const pkg2 = JSON.parse(content);
     const name = pkg2?.name;
@@ -1772,10 +1834,11 @@ function readProjectNameFromPackageJson(cwd2) {
   }
 }
 function detectConfigExtension(cwd2) {
+  if (!isLocalInstallSatisfied(cwd2)) return "json";
   try {
-    if (existsSync11(join13(cwd2, "tsconfig.json"))) return "ts";
-    const pkgPath2 = join13(cwd2, "package.json");
-    if (!existsSync11(pkgPath2)) return "mjs";
+    if (existsSync12(join14(cwd2, "tsconfig.json"))) return "ts";
+    const pkgPath2 = join14(cwd2, "package.json");
+    if (!existsSync12(pkgPath2)) return "mjs";
     const pkg2 = JSON.parse(readFileSync8(pkgPath2, "utf8"));
     if (pkg2?.type === "module") return "mjs";
   } catch {
@@ -1783,7 +1846,6 @@ function detectConfigExtension(cwd2) {
   return "mjs";
 }
 function applyConfigDefaults(params) {
-  const models = params.models ?? {};
   const scope = params.scope ?? "local";
   const projectId = params.projectId ?? randomUUID();
   const baseStorage = {
@@ -1806,22 +1868,10 @@ function applyConfigDefaults(params) {
       docsPath: params.docsPath,
       agentsMd: "./AGENTS.md"
     },
-    agents: {
-      lead: { instructionsPath: null, ...models.lead && { model: models.lead } },
-      explorer: {
-        instructionsPath: null,
-        allowedPaths: [params.docsPath, "./src"],
-        ...models.explorer && { model: models.explorer }
-      },
-      builder: {
-        instructionsPath: null,
-        writablePaths: ["./src", "./tests"],
-        ...models.builder && { model: models.builder }
-      },
-      reviewer: { instructionsPath: null, ...models.reviewer && { model: models.reviewer } },
-      ...models.consultant && { consultant: { instructionsPath: null, model: models.consultant } },
-      custom: []
-    },
+    // No `agents` key: per-agent settings (model, role instructions) live in
+    // the generated agent file, which is user-owned. This object is the runtime
+    // twin of the config body emitted by configObjectBody() in templates.ts —
+    // drift between the two is the bug this pairing has to keep out.
     database: { type: "sqlite" },
     storage,
     health: {
@@ -1840,27 +1890,27 @@ function stripAnsi(str2) {
 function drawBox(lines) {
   const width = Math.max(...lines.map((l) => stripAnsi(l).length));
   const border = "\u2500".repeat(width);
-  console.log(pc6.yellow(`\u250C${border}\u2510`));
+  console.log(pc7.yellow(`\u250C${border}\u2510`));
   for (const line of lines) {
     const pad = width - stripAnsi(line).length;
     const padStr = pad > 0 ? " ".repeat(pad) : "";
-    console.log(pc6.yellow("\u2502") + line + padStr + pc6.yellow("\u2502"));
+    console.log(pc7.yellow("\u2502") + line + padStr + pc7.yellow("\u2502"));
   }
-  console.log(pc6.yellow(`\u2514${border}\u2518`));
+  console.log(pc7.yellow(`\u2514${border}\u2518`));
 }
 function printWelcomeMessage(projectName) {
   const sep = "\u2500".repeat(38);
   const lines = [
-    `  ${pc6.bold(pc6.white("agent-harness-kit"))}  `,
-    `  ${pc6.gray("\u2014")} harness scaffolding ${pc6.gray("\u2014")}  `,
-    `  ${pc6.gray(sep)}  `,
-    `  ${pc6.bold("Project:")}  ${projectName || "\u2014"}  `,
-    `  ${pc6.bold("Status:")}   ${pc6.green("ready to configure")}  `,
-    `  ${pc6.gray(sep)}  `,
-    `  ${pc6.gray("Next steps:")}  `,
-    `  ${pc6.gray("\u2192")} ${pc6.gray("Set up your AI provider config")}  `,
-    `  ${pc6.gray("\u2192")} ${pc6.gray("Run your health check to verify")}  `,
-    `  ${pc6.gray("\u2192")} ${pc6.gray("Start adding tasks for your agents")}  `
+    `  ${pc7.bold(pc7.white("agent-harness-kit"))}  `,
+    `  ${pc7.gray("\u2014")} harness scaffolding ${pc7.gray("\u2014")}  `,
+    `  ${pc7.gray(sep)}  `,
+    `  ${pc7.bold("Project:")}  ${projectName || "\u2014"}  `,
+    `  ${pc7.bold("Status:")}   ${pc7.green("ready to configure")}  `,
+    `  ${pc7.gray(sep)}  `,
+    `  ${pc7.gray("Next steps:")}  `,
+    `  ${pc7.gray("\u2192")} ${pc7.gray("Set up your AI provider config")}  `,
+    `  ${pc7.gray("\u2192")} ${pc7.gray("Run your health check to verify")}  `,
+    `  ${pc7.gray("\u2192")} ${pc7.gray("Start adding tasks for your agents")}  `
   ];
   console.log();
   drawBox(lines);
@@ -1872,18 +1922,18 @@ async function runInit(cwd2, flags) {
   const existingConfig = findConfigFile(cwd2);
   if (existingConfig) {
     console.log(
-      pc7.yellow("\u26A0") + " " + pc7.bold("Project already initialized.") + pc7.dim(` (${existingConfig})`)
+      pc8.yellow("\u26A0") + " " + pc8.bold("Project already initialized.") + pc8.dim(` (${existingConfig})`)
     );
     console.log();
-    console.log(pc7.dim("Suggested next steps:"));
+    console.log(pc8.dim("Suggested next steps:"));
     console.log(
-      "  " + pc7.cyan("ahk build") + pc7.dim("         \u2014 re-sync agent files after updating the library")
+      "  " + pc8.cyan("ahk build") + pc8.dim("         \u2014 re-sync agent files after updating the library")
     );
-    console.log("  " + pc7.cyan("ahk build --sync") + pc7.dim("  \u2014 also sync agent permissions"));
+    console.log("  " + pc8.cyan("ahk build --sync") + pc8.dim("  \u2014 also sync agent permissions"));
     console.log(
-      "  " + pc7.cyan("ahk reset") + pc7.dim("         \u2014 wipe and re-initialize from scratch")
+      "  " + pc8.cyan("ahk reset") + pc8.dim("         \u2014 wipe and re-initialize from scratch")
     );
-    console.log("  " + pc7.cyan("ahk dashboard") + pc7.dim("         \u2014 open the harness dashboard"));
+    console.log("  " + pc8.cyan("ahk dashboard") + pc8.dim("         \u2014 open the harness dashboard"));
     process.exit(0);
   }
   const detectedName = flags.name ?? readProjectNameFromPackageJson(cwd2);
@@ -1935,61 +1985,6 @@ async function runInit(cwd2, flags) {
     }
     provider = val;
   }
-  const AGENT_LABELS = [
-    { key: "lead", label: "Lead" },
-    { key: "explorer", label: "Explorer" },
-    { key: "consultant", label: "Consultant" },
-    { key: "builder", label: "Builder" },
-    { key: "reviewer", label: "Reviewer" }
-  ];
-  const modelOverrides = {};
-  if (provider === "claude-code" || provider === "codex-cli") {
-    const wantsModelCustomization = await p3.confirm({
-      message: "Customize the model per agent?",
-      initialValue: false
-    });
-    if (p3.isCancel(wantsModelCustomization)) {
-      p3.cancel("Cancelled.");
-      process.exit(0);
-    }
-    if (wantsModelCustomization) {
-      if (provider === "claude-code") {
-        for (const agent of AGENT_LABELS) {
-          const val = await p3.select({
-            message: `Model for ${agent.label}`,
-            options: [
-              { value: "inherit", label: "inherit (default)" },
-              { value: "haiku", label: "haiku" },
-              { value: "sonnet", label: "sonnet" },
-              { value: "opus", label: "opus" },
-              { value: "fable", label: "fable" }
-            ],
-            initialValue: "inherit"
-          });
-          if (p3.isCancel(val)) {
-            p3.cancel("Cancelled.");
-            process.exit(0);
-          }
-          modelOverrides[agent.key] = val;
-        }
-      } else {
-        for (const agent of AGENT_LABELS) {
-          const val = await p3.text({
-            message: `Model for ${agent.label} (Codex does not validate this value)`,
-            placeholder: "e.g. gpt-5 (empty or <3 chars = no override)"
-          });
-          if (p3.isCancel(val)) {
-            p3.cancel("Cancelled.");
-            process.exit(0);
-          }
-          const trimmed = val.trim();
-          if (trimmed.length >= 3) {
-            modelOverrides[agent.key] = trimmed;
-          }
-        }
-      }
-    }
-  }
   let docsPath;
   if (flags.docs) {
     docsPath = flags.docs;
@@ -2090,14 +2085,13 @@ async function runInit(cwd2, flags) {
       provider,
       docsPath,
       tasksAdapter,
-      models: modelOverrides,
       scope: storageScope
     });
     const materializer = getMaterializer(provider);
     const installDir = cwd2;
     configExt = detectConfigExtension(cwd2);
     const configFileName = `agent-harness-kit.config.${configExt}`;
-    const templateFn = configExt === "ts" ? configTs : configExt === "mjs" ? configMjs : configCjs;
+    const templateFn = configExt === "json" ? configJson : configExt === "ts" ? configTs : configExt === "mjs" ? configMjs : configCjs;
     const configContent = templateFn({
       name,
       description,
@@ -2105,12 +2099,11 @@ async function runInit(cwd2, flags) {
       docsPath,
       tasksAdapter,
       port: config.tools.mcp.port,
-      models: modelOverrides,
       scope: config.storage.scope,
       projectId: config.storage.projectId
     });
-    writeFileSync8(join14(installDir, configFileName), configContent, "utf8");
-    mkdirSync7(join14(installDir, config.storage.dir), { recursive: true });
+    writeFileSync8(join15(installDir, configFileName), configContent, "utf8");
+    mkdirSync7(join15(installDir, config.storage.dir), { recursive: true });
     const db = await openDB(config, installDir);
     await db.writeStorageState(installDir);
     await materializer.scaffold(config, { cwd: installDir, firstTask });
@@ -2130,39 +2123,39 @@ async function runInit(cwd2, flags) {
     p3.log.error(err instanceof Error ? err.message : String(err));
     throw err;
   }
-  console.log(pc7.green("\u2713 Scaffolded harness in current directory"));
+  console.log(pc8.green("\u2713 Scaffolded harness in current directory"));
   const agentsDir = provider === "claude-code" ? ".claude/agents/" : ".opencode/agents/";
   const mcpFile = provider === "claude-code" ? ".claude/mcp.json" : "./opencode.json";
   console.log("");
-  console.log(pc7.green(`\u2713 agent-harness-kit.config.${configExt}`));
-  console.log(pc7.green("\u2713 AGENTS.md"));
-  console.log(pc7.green("\u2713 health.sh"));
+  console.log(pc8.green(`\u2713 agent-harness-kit.config.${configExt}`));
+  console.log(pc8.green("\u2713 AGENTS.md"));
+  console.log(pc8.green("\u2713 health.sh"));
   console.log(
-    pc7.green(
+    pc8.green(
       storageScope === "global" ? "\u2713 ~/.harness/dbs/<projectId>/harness.db" : "\u2713 .harness/harness.db"
     )
   );
   console.log(
-    pc7.green(
+    pc8.green(
       storageScope === "global" ? "\u2713 ~/.harness/dbs/<projectId>/current.md" : "\u2713 .harness/current.md"
     )
   );
-  console.log(pc7.green("\u2713 .harness/storage-state.json"));
-  console.log(pc7.green(`\u2713 ${agentsDir}lead.md`));
-  console.log(pc7.green(`\u2713 ${agentsDir}explorer.md`));
-  console.log(pc7.green(`\u2713 ${agentsDir}builder.md`));
-  console.log(pc7.green(`\u2713 ${agentsDir}reviewer.md`));
-  console.log(pc7.green(`\u2713 ${mcpFile}`));
-  console.log(pc7.green("\u2713 .gitignore entries added"));
+  console.log(pc8.green("\u2713 .harness/storage-state.json"));
+  console.log(pc8.green(`\u2713 ${agentsDir}lead.md`));
+  console.log(pc8.green(`\u2713 ${agentsDir}explorer.md`));
+  console.log(pc8.green(`\u2713 ${agentsDir}builder.md`));
+  console.log(pc8.green(`\u2713 ${agentsDir}reviewer.md`));
+  console.log(pc8.green(`\u2713 ${mcpFile}`));
+  console.log(pc8.green("\u2713 .gitignore entries added"));
   console.log("");
-  console.log(pc7.cyan("\u2192") + ` Edit ${pc7.cyan("health.sh")} with your project checks`);
-  console.log(pc7.cyan("\u2192") + ` ${pc7.cyan("ahk task add")} to queue work for agents`);
+  console.log(pc8.cyan("\u2192") + ` Edit ${pc8.cyan("health.sh")} with your project checks`);
+  console.log(pc8.cyan("\u2192") + ` ${pc8.cyan("ahk task add")} to queue work for agents`);
   console.log(
-    pc7.cyan("\u2192") + ` Enrich your docs with knowledge graphs: ${pc7.cyan("https://github.com/safishamsi/graphify")}`
+    pc8.cyan("\u2192") + ` Enrich your docs with knowledge graphs: ${pc8.cyan("https://github.com/safishamsi/graphify")}`
   );
   const recommendations = [
     `   Give a try to Heimdall MCP: Transparent proxy that traces every MCP tool call with OpenTelemetry.  `,
-    `   Learn more: ${pc7.cyan("https://github.com/enmanuelmag/heimdall-mcp")}                              `
+    `   Learn more: ${pc8.cyan("https://github.com/enmanuelmag/heimdall-mcp")}                              `
   ];
   console.log("");
   drawBox(recommendations);
@@ -2170,7 +2163,7 @@ async function runInit(cwd2, flags) {
 
 // src/commands/migrate.ts
 import * as p4 from "@clack/prompts";
-import pc8 from "picocolors";
+import pc9 from "picocolors";
 async function runMigrate(cwd2, opts) {
   const config = await loadConfig(cwd2);
   let target;
@@ -2192,7 +2185,7 @@ async function runMigrate(cwd2, opts) {
     target = val;
   }
   if (target === config.provider) {
-    console.log(pc8.dim(`Already on ${target} \u2014 nothing to migrate.`));
+    console.log(pc9.dim(`Already on ${target} \u2014 nothing to migrate.`));
     return;
   }
   const spinner6 = p4.spinner();
@@ -2200,21 +2193,21 @@ async function runMigrate(cwd2, opts) {
   try {
     const targetMaterializer = getMaterializer(target);
     await targetMaterializer.build(config, cwd2);
-    spinner6.stop(pc8.green(`Migrated to ${target}`));
+    spinner6.stop(pc9.green(`Migrated to ${target}`));
     p4.log.warn(`Update agent-harness-kit.config.ts: set provider: '${target}'`);
     p4.log.warn(`Then run: ahk build`);
   } catch (err) {
-    spinner6.stop(pc8.red("Migration failed"));
+    spinner6.stop(pc9.red("Migration failed"));
     p4.log.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
 }
 
 // src/commands/migrate-storage.ts
-import { copyFileSync, existsSync as existsSync12, mkdirSync as mkdirSync8, rmSync, writeFileSync as writeFileSync9 } from "fs";
+import { copyFileSync, existsSync as existsSync13, mkdirSync as mkdirSync8, rmSync, writeFileSync as writeFileSync9 } from "fs";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname7, join as join15, resolve as resolve7 } from "path";
-import pc9 from "picocolors";
+import { dirname as dirname7, join as join16, resolve as resolve7 } from "path";
+import pc10 from "picocolors";
 function log5(msg) {
   console.log(msg);
 }
@@ -2225,14 +2218,14 @@ function defaultMarkdownPathForConfig(config) {
   return config.storage.scope === "local" ? config.storage.markdownFallback.path : DEFAULT_MARKDOWN_PATH;
 }
 function currentMdPathForScope(scope, config, cwd2, homeDir) {
-  return scope === "global" ? join15(resolveGlobalStorageDir(config, homeDir), "current.md") : resolve7(cwd2, defaultMarkdownPathForConfig(config));
+  return scope === "global" ? join16(resolveGlobalStorageDir(config, homeDir), "current.md") : resolve7(cwd2, defaultMarkdownPathForConfig(config));
 }
 function defaultSqlitePathForConfig(config) {
   return config.storage.scope === "local" && config.database.type === "sqlite" ? config.storage.sqlitePath ?? DEFAULT_SQLITE_PATH : DEFAULT_SQLITE_PATH;
 }
 async function backupDestination(cwd2, storageDir, data) {
   const backupsDir = resolve7(cwd2, storageDir, "backups");
-  const path = join15(backupsDir, `pre-migrate-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.json`);
+  const path = join16(backupsDir, `pre-migrate-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.json`);
   try {
     mkdirSync8(backupsDir, { recursive: true });
     writeFileSync9(path, JSON.stringify(data, null, 2) + "\n", "utf8");
@@ -2247,11 +2240,11 @@ function copySqliteFile(srcPath, destPath) {
   mkdirSync8(dirname7(destPath), { recursive: true });
   copyFileSync(srcPath, destPath);
   for (const suffix of ["-wal", "-shm"]) {
-    if (existsSync12(`${srcPath}${suffix}`)) {
+    if (existsSync13(`${srcPath}${suffix}`)) {
       copyFileSync(`${srcPath}${suffix}`, `${destPath}${suffix}`);
     }
   }
-  if (!existsSync12(destPath)) {
+  if (!existsSync13(destPath)) {
     throw new Error(`Copy verification failed: ${destPath} does not exist after copy.`);
   }
 }
@@ -2279,13 +2272,13 @@ async function runMigrateStorage(cwd2, opts, homeDir = homedir3()) {
       } finally {
         await db.close();
       }
-      log5(pc9.dim("storage-state.json was missing; no data found at either candidate location. Nothing to migrate \u2014 state recorded."));
+      log5(pc10.dim("storage-state.json was missing; no data found at either candidate location. Nothing to migrate \u2014 state recorded."));
       return;
     }
     realScope = localCount > 0 ? "local" : "global";
     realDbType = "sqlite";
     log5(
-      pc9.yellow(
+      pc10.yellow(
         `storage-state.json was missing. Detected real data at ${realScope} sqlite location (${realScope === "local" ? localPath : globalPath}) \u2014 using it as the migration source.`
       )
     );
@@ -2296,7 +2289,7 @@ async function runMigrateStorage(cwd2, opts, homeDir = homedir3()) {
   const desiredScope = config.storage.scope;
   const desiredDbType = config.database.type;
   if (realScope === desiredScope && realDbType === desiredDbType) {
-    log5(pc9.green(`\u2713 Storage already matches config (scope=${desiredScope}, database=${desiredDbType}) \u2014 nothing to migrate.`));
+    log5(pc10.green(`\u2713 Storage already matches config (scope=${desiredScope}, database=${desiredDbType}) \u2014 nothing to migrate.`));
     return;
   }
   if (realDbType !== "sqlite") {
@@ -2310,7 +2303,7 @@ async function runMigrateStorage(cwd2, opts, homeDir = homedir3()) {
   return migrateAcrossDbType(cwd2, config, homeDir, realScope, opts);
 }
 async function probeTaskCount(dbPath) {
-  if (!existsSync12(dbPath)) return 0;
+  if (!existsSync13(dbPath)) return 0;
   const { SQLiteDriver } = await import("./sqlite-TR4D324R.js");
   const driver = new SQLiteDriver(dbPath);
   try {
@@ -2327,10 +2320,10 @@ async function migrateScopeOnly(cwd2, config, homeDir, fromScope, toScope, opts)
   const destDb = resolveSqlitePathForScope(toScope, sqlitePath, cwd2, config, homeDir);
   const srcMd = currentMdPathForScope(fromScope, config, cwd2, homeDir);
   const destMd = currentMdPathForScope(toScope, config, cwd2, homeDir);
-  if (!existsSync12(srcDb)) {
+  if (!existsSync13(srcDb)) {
     fail(`Source database not found at ${srcDb} (expected ${fromScope} scope) \u2014 nothing to move.`);
   }
-  const destExists = existsSync12(destDb);
+  const destExists = existsSync13(destDb);
   if (destExists) {
     const { SQLiteDriver } = await import("./sqlite-TR4D324R.js");
     const destDriver = new SQLiteDriver(destDb);
@@ -2359,36 +2352,36 @@ async function migrateScopeOnly(cwd2, config, homeDir, fromScope, toScope, opts)
         await backupDriver.close();
       }
       const backupPath = await backupDestination(cwd2, config.storage.dir, data);
-      log5(pc9.yellow(`  Backed up existing destination data \u2192 ${backupPath}`));
+      log5(pc10.yellow(`  Backed up existing destination data \u2192 ${backupPath}`));
     }
   }
   if (opts.dryRun) {
-    log5(pc9.dim(`[dry-run] Would copy ${srcDb} \u2192 ${destDb} (scope ${fromScope} \u2192 ${toScope}), and move current.md.`));
+    log5(pc10.dim(`[dry-run] Would copy ${srcDb} \u2192 ${destDb} (scope ${fromScope} \u2192 ${toScope}), and move current.md.`));
     return;
   }
   copySqliteFile(srcDb, destDb);
-  log5(pc9.green(`\u2713 Copied database ${srcDb} \u2192 ${destDb}`));
-  if (existsSync12(srcMd)) {
+  log5(pc10.green(`\u2713 Copied database ${srcDb} \u2192 ${destDb}`));
+  if (existsSync13(srcMd)) {
     mkdirSync8(dirname7(destMd), { recursive: true });
     copyFileSync(srcMd, destMd);
-    log5(pc9.green(`\u2713 Copied current.md ${srcMd} \u2192 ${destMd}`));
+    log5(pc10.green(`\u2713 Copied current.md ${srcMd} \u2192 ${destMd}`));
   }
   rmSync(srcDb, { force: true });
   rmSync(`${srcDb}-wal`, { force: true });
   rmSync(`${srcDb}-shm`, { force: true });
-  if (existsSync12(srcMd) && srcMd !== destMd) rmSync(srcMd, { force: true });
+  if (existsSync13(srcMd) && srcMd !== destMd) rmSync(srcMd, { force: true });
   const db = await openDB(config, cwd2, homeDir);
   try {
     await db.writeStorageState(cwd2);
   } finally {
     await db.close();
   }
-  log5(pc9.green(`\u2713 Storage migrated: scope ${fromScope} \u2192 ${toScope}`));
+  log5(pc10.green(`\u2713 Storage migrated: scope ${fromScope} \u2192 ${toScope}`));
 }
 async function migrateAcrossDbType(cwd2, config, homeDir, sourceScope, opts) {
   const sqlitePath = defaultSqlitePathForConfig(config);
   const srcPath = resolveSqlitePathForScope(sourceScope, sqlitePath, cwd2, config, homeDir);
-  if (!existsSync12(srcPath)) {
+  if (!existsSync13(srcPath)) {
     fail(`Source sqlite database not found at ${srcPath} (expected ${sourceScope} scope) \u2014 nothing to migrate.`);
   }
   const { SQLiteDriver } = await import("./sqlite-TR4D324R.js");
@@ -2424,7 +2417,7 @@ async function migrateAcrossDbType(cwd2, config, homeDir, sourceScope, opts) {
     }
     if (opts.dryRun) {
       log5(
-        pc9.dim(
+        pc10.dim(
           `[dry-run] Would migrate ${sourceCounts.tasks} task(s) from sqlite (${sourceScope}, ${srcPath}) to ${config.database.type}${destEmpty ? "" : " (destination has data \u2014 would back up first, then overwrite)"}.`
         )
       );
@@ -2434,34 +2427,34 @@ async function migrateAcrossDbType(cwd2, config, homeDir, sourceScope, opts) {
     if (!destEmpty && opts.force) {
       const currentDestData = await destDb.exportJson();
       backupPath = await backupDestination(cwd2, config.storage.dir, currentDestData);
-      log5(pc9.yellow(`  Backed up existing destination data \u2192 ${backupPath}`));
+      log5(pc10.yellow(`  Backed up existing destination data \u2192 ${backupPath}`));
     }
     await destDb.importFullExport(sourceData, config.database.type, { truncateFirst: !destEmpty });
     await destDb.writeStorageState(cwd2);
     log5(
-      pc9.green(
+      pc10.green(
         `\u2713 Migrated ${sourceData.tasks.length} task(s), ${sourceData.actions.length} action(s) from sqlite (${sourceScope}) \u2192 ${config.database.type}.`
       )
     );
-    if (backupPath) log5(pc9.dim(`  Destination backup: ${backupPath}`));
-    log5(pc9.yellow(`  Note: the original sqlite file at ${srcPath} was NOT deleted \u2014 remove it manually once you've verified the migration.`));
+    if (backupPath) log5(pc10.dim(`  Destination backup: ${backupPath}`));
+    log5(pc10.yellow(`  Note: the original sqlite file at ${srcPath} was NOT deleted \u2014 remove it manually once you've verified the migration.`));
   } finally {
     await destDb.close();
   }
 }
 
 // src/commands/reset.ts
-import { existsSync as existsSync13, readdirSync, rmSync as rmSync2 } from "fs";
+import { existsSync as existsSync14, readdirSync, rmSync as rmSync2 } from "fs";
 import { homedir as homedir4 } from "os";
-import { join as join16, resolve as resolve8 } from "path";
+import { join as join17, resolve as resolve8 } from "path";
 import * as p5 from "@clack/prompts";
-import pc10 from "picocolors";
+import pc11 from "picocolors";
 var AGENT_MD_FILES = ["lead", "explorer", "consultant", "builder", "reviewer"];
 async function resetAgentMds(cwd2, provider) {
   const agentDir = provider === "claude-code" ? ".claude/agents" : ".opencode/agents";
   const agentDirPath = resolve8(cwd2, agentDir);
-  if (!existsSync13(agentDirPath)) {
-    console.log(pc10.yellow(`  Skipping agent files \u2014 directory not found: ${agentDirPath}`));
+  if (!existsSync14(agentDirPath)) {
+    console.log(pc11.yellow(`  Skipping agent files \u2014 directory not found: ${agentDirPath}`));
     return;
   }
   const existingFiles = [];
@@ -2473,11 +2466,11 @@ async function resetAgentMds(cwd2, provider) {
       }
     }
   } catch {
-    console.log(pc10.yellow(`  Skipping agent files \u2014 ${agentDirPath} is not readable`));
+    console.log(pc11.yellow(`  Skipping agent files \u2014 ${agentDirPath} is not readable`));
     return;
   }
   if (existingFiles.length === 0) {
-    console.log(pc10.yellow(`  No agent MD files found in ${agentDir}/`));
+    console.log(pc11.yellow(`  No agent MD files found in ${agentDir}/`));
     return;
   }
   for (const file of existingFiles) {
@@ -2486,19 +2479,19 @@ async function resetAgentMds(cwd2, provider) {
       initialValue: true
     });
     if (p5.isCancel(confirm3)) {
-      console.log(pc10.red("  Cancelled by user."));
+      console.log(pc11.red("  Cancelled by user."));
       return;
     }
     if (confirm3) {
       try {
-        const filePath = join16(agentDirPath, file);
+        const filePath = join17(agentDirPath, file);
         rmSync2(filePath, { force: true });
-        console.log(pc10.green(`  Removed ${file}`));
+        console.log(pc11.green(`  Removed ${file}`));
       } catch {
-        console.error(pc10.red(`  Failed to remove ${file}`));
+        console.error(pc11.red(`  Failed to remove ${file}`));
       }
     } else {
-      console.log(pc10.cyan(`  Skipped ${file}`));
+      console.log(pc11.cyan(`  Skipped ${file}`));
     }
   }
 }
@@ -2507,7 +2500,7 @@ async function runReset(cwd2, opts) {
   try {
     config = await loadConfig(cwd2);
   } catch {
-    console.error(pc10.red("\u2717 No agent-harness-kit.config found. Run: ahk init"));
+    console.error(pc11.red("\u2717 No agent-harness-kit.config found. Run: ahk init"));
     process.exit(1);
   }
   const storageDir = config.storage.dir || ".harness";
@@ -2516,12 +2509,12 @@ async function runReset(cwd2, opts) {
   let resetDb = false;
   let resetFeatureList = false;
   let resetAgentMdsFlag = false;
-  if (dbPath && existsSync13(dbPath)) {
+  if (dbPath && existsSync14(dbPath)) {
     if (opts.force) {
       resetDb = true;
     } else {
       if (config.database.type !== "sqlite") {
-        console.log(pc10.yellow(`  Skipping DB reset \u2014 database type "${config.database.type}" is not managed by this command.`));
+        console.log(pc11.yellow(`  Skipping DB reset \u2014 database type "${config.database.type}" is not managed by this command.`));
         resetDb = false;
       } else {
         const confirm3 = await p5.confirm({
@@ -2529,16 +2522,16 @@ async function runReset(cwd2, opts) {
           initialValue: true
         });
         if (p5.isCancel(confirm3)) {
-          console.log(pc10.red("  Cancelled by user."));
+          console.log(pc11.red("  Cancelled by user."));
           return;
         }
         resetDb = confirm3;
       }
     }
   } else if (!dbPath) {
-    console.log(pc10.dim(`  Skipping DB reset \u2014 remote ${config.database.type} database is not managed by this command.`));
+    console.log(pc11.dim(`  Skipping DB reset \u2014 remote ${config.database.type} database is not managed by this command.`));
   }
-  if (existsSync13(featureListPath)) {
+  if (existsSync14(featureListPath)) {
     if (opts.force) {
       resetFeatureList = true;
     } else {
@@ -2547,7 +2540,7 @@ async function runReset(cwd2, opts) {
         initialValue: true
       });
       if (p5.isCancel(confirm3)) {
-        console.log(pc10.red("  Cancelled by user."));
+        console.log(pc11.red("  Cancelled by user."));
         return;
       }
       resetFeatureList = confirm3;
@@ -2561,17 +2554,17 @@ async function runReset(cwd2, opts) {
       rmSync2(dbPath, { force: true });
       rmSync2(`${dbPath}-wal`, { force: true });
       rmSync2(`${dbPath}-shm`, { force: true });
-      console.log(pc10.green(`  \u2713 Removed ${dbPath}`));
+      console.log(pc11.green(`  \u2713 Removed ${dbPath}`));
     } catch {
-      console.error(pc10.red(`  \u2717 Failed to remove ${dbPath}`));
+      console.error(pc11.red(`  \u2717 Failed to remove ${dbPath}`));
     }
   }
   if (resetFeatureList) {
     try {
       rmSync2(featureListPath, { force: true });
-      console.log(pc10.green(`  \u2713 Removed ${storageDir}/feature_list.json`));
+      console.log(pc11.green(`  \u2713 Removed ${storageDir}/feature_list.json`));
     } catch {
-      console.error(pc10.red(`  \u2717 Failed to remove ${featureListPath}`));
+      console.error(pc11.red(`  \u2717 Failed to remove ${featureListPath}`));
     }
   }
   if (resetAgentMdsFlag) {
@@ -2579,16 +2572,16 @@ async function runReset(cwd2, opts) {
     await resetAgentMds(cwd2, opts.provider || "claude-code");
   }
   if (!resetDb && !resetFeatureList && !resetAgentMdsFlag) {
-    console.log(pc10.yellow("  Nothing to reset (all items missing or skipped)."));
+    console.log(pc11.yellow("  Nothing to reset (all items missing or skipped)."));
     return;
   }
   console.log("");
-  console.log(pc10.green('\u2713 Reset complete. Run "ahk init" to scaffold a fresh harness.'));
+  console.log(pc11.green('\u2713 Reset complete. Run "ahk init" to scaffold a fresh harness.'));
 }
 
 // src/core/mcp-server.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync9, readdirSync as readdirSync2, readFileSync as readFileSync10, statSync, writeFileSync as writeFileSync10 } from "fs";
-import { join as join18, resolve as resolve9 } from "path";
+import { existsSync as existsSync16, mkdirSync as mkdirSync9, readdirSync as readdirSync2, readFileSync as readFileSync9, statSync, writeFileSync as writeFileSync10 } from "fs";
+import { join as join19, resolve as resolve9 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -2597,45 +2590,20 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // src/core/permissions-check.ts
-import { existsSync as existsSync14, readFileSync as readFileSync9 } from "fs";
-import { join as join17 } from "path";
-var CANONICAL = {
-  lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
-  explorer: [...MCP_CLAUDE_PERMISSIONS_EXPLORER],
-  consultant: [...MCP_CLAUDE_PERMISSIONS_CONSULTANT],
-  builder: [...MCP_CLAUDE_PERMISSIONS_BUILDER],
-  reviewer: [...MCP_CLAUDE_PERMISSIONS_REVIEWER]
-};
-function parseToolsFromFrontmatter(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---/m);
-  if (!match) return [];
-  const fm = match[1];
-  const toolsMatch = fm.match(/^tools:\n((?:  - [^\n]+\n?)*)/m);
-  if (!toolsMatch) return [];
-  return toolsMatch[1].split("\n").map((l) => l.trim().replace(/^- /, "")).filter((l) => l.startsWith("mcp__"));
-}
+import { existsSync as existsSync15 } from "fs";
+import { join as join18 } from "path";
+var AGENTS = ["lead", "explorer", "consultant", "builder", "reviewer"];
 function checkPermissionsSync(cwd2, config) {
   if (config.provider !== "claude-code") {
     return { in_sync: true };
   }
   const agents = {};
   let in_sync = true;
-  for (const agent of ["lead", "explorer", "consultant", "builder", "reviewer"]) {
-    const filePath = join17(cwd2, ".claude", "agents", `${agent}.md`);
-    if (!existsSync14(filePath)) {
-      const missing2 = CANONICAL[agent];
-      agents[agent] = { ok: false, missing: missing2, extra: [] };
-      in_sync = false;
-      continue;
-    }
-    const content = readFileSync9(filePath, "utf-8");
-    const installed = parseToolsFromFrontmatter(content);
-    const canonical = CANONICAL[agent];
-    const missing = canonical.filter((t) => !installed.includes(t));
-    const extra = installed.filter((t) => !canonical.includes(t));
-    const ok3 = missing.length === 0 && extra.length === 0;
-    if (!ok3) in_sync = false;
-    agents[agent] = { ok: ok3, missing, extra };
+  for (const agent of AGENTS) {
+    const filePath = join18(cwd2, ".claude", "agents", `${agent}.md`);
+    const exists = existsSync15(filePath);
+    if (!exists) in_sync = false;
+    agents[agent] = exists ? { ok: true } : { ok: false, reason: "missing_file" };
   }
   return { in_sync, agents };
 }
@@ -2885,7 +2853,7 @@ var TOOLS = [
   },
   {
     name: "permissions.check",
-    description: "Check whether the .claude/agents/*.md tool permission lists are in sync with the current canonical permission constants. Returns per-agent diff with missing and extra tools. Call this at session start to detect outdated agent files after an ahk upgrade.",
+    description: 'Check that a .claude/agents/*.md definition file exists for every role. Returns { in_sync, agents } where each agent is { ok } or { ok: false, reason: "missing_file" }. Agent file CONTENTS are never inspected \u2014 they are meant to be customised freely \u2014 so this never reports drift, only absence. Run `ahk build` to restore a missing file.',
     inputSchema: { type: "object", properties: {}, required: [] }
   },
   {
@@ -3054,19 +3022,19 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
       return ok2(JSON.stringify(result, null, 2));
     }
     case "deps.snapshot": {
-      const pkgPath2 = join18(cwd2, "package.json");
-      if (!existsSync15(pkgPath2)) {
+      const pkgPath2 = join19(cwd2, "package.json");
+      if (!existsSync16(pkgPath2)) {
         return ok2("package.json not found in project root", true);
       }
-      const pkg2 = JSON.parse(readFileSync10(pkgPath2, "utf8"));
+      const pkg2 = JSON.parse(readFileSync9(pkgPath2, "utf8"));
       const snapshot = {
         capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
         dependencies: pkg2.dependencies ?? {},
         devDependencies: pkg2.devDependencies ?? {}
       };
-      const harnessDir = join18(cwd2, ".harness");
+      const harnessDir = join19(cwd2, ".harness");
       mkdirSync9(harnessDir, { recursive: true });
-      writeFileSync10(join18(harnessDir, "deps-lock.json"), JSON.stringify(snapshot, null, 2), "utf8");
+      writeFileSync10(join19(harnessDir, "deps-lock.json"), JSON.stringify(snapshot, null, 2), "utf8");
       return ok2(
         JSON.stringify({
           message: "Snapshot saved to .harness/deps-lock.json",
@@ -3075,12 +3043,12 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
       );
     }
     case "deps.check": {
-      const pkgPath2 = join18(cwd2, "package.json");
-      const lockPath = join18(cwd2, ".harness", "deps-lock.json");
-      if (!existsSync15(pkgPath2)) {
+      const pkgPath2 = join19(cwd2, "package.json");
+      const lockPath = join19(cwd2, ".harness", "deps-lock.json");
+      if (!existsSync16(pkgPath2)) {
         return ok2("package.json not found in project root", true);
       }
-      if (!existsSync15(lockPath)) {
+      if (!existsSync16(lockPath)) {
         return ok2(
           JSON.stringify({
             status: "no-snapshot",
@@ -3088,8 +3056,8 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
           })
         );
       }
-      const pkg2 = JSON.parse(readFileSync10(pkgPath2, "utf8"));
-      const lock = JSON.parse(readFileSync10(lockPath, "utf8"));
+      const pkg2 = JSON.parse(readFileSync9(pkgPath2, "utf8"));
+      const lock = JSON.parse(readFileSync9(lockPath, "utf8"));
       const current = { ...pkg2.dependencies ?? {}, ...pkg2.devDependencies ?? {} };
       const previous = { ...lock.dependencies ?? {}, ...lock.devDependencies ?? {} };
       const added = [];
@@ -3131,9 +3099,10 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
       const status = await getDoctorStatus(cwd2);
       const result = {
         lib: { current: status.lib.current, latest: status.lib.latest, outdated: status.lib.outdated },
+        // Agents are existence-checked only — there is no `outdated` bucket.
+        // Hand-edited agent definitions are supported and must not be flagged.
         agents: {
           missing: status.agents.filter((a) => a.status === "missing").map((a) => a.name),
-          outdated: status.agents.filter((a) => a.status === "outdated").map((a) => a.name),
           ok: status.agents.filter((a) => a.status === "ok").map((a) => a.name)
         },
         skills: {
@@ -3156,7 +3125,7 @@ function searchDocs(docsPath, query, maxResults = 10) {
     for (const file of files) {
       if (results.length >= maxResults) break;
       try {
-        const content = readFileSync10(file, "utf8");
+        const content = readFileSync9(file, "utf8");
         const lines = content.split("\n");
         for (let i = 0; i < lines.length; i++) {
           const lower = lines[i].toLowerCase();
@@ -3181,7 +3150,7 @@ function collectMarkdownFiles(dir) {
   const files = [];
   try {
     for (const entry of readdirSync2(dir)) {
-      const full = join18(dir, entry);
+      const full = join19(dir, entry);
       const stat = statSync(full);
       if (stat.isDirectory()) {
         files.push(...collectMarkdownFiles(full));
@@ -3217,14 +3186,8 @@ async function runServe(cwd2, opts) {
 `);
   const syncResult = checkPermissionsSync(cwd2, config);
   if (!syncResult.in_sync && syncResult.agents) {
-    const affected = Object.entries(syncResult.agents).filter(([, r]) => !r.ok).map(([name, r]) => {
-      const parts = [];
-      if (r.missing.length) parts.push(`missing: ${r.missing.map((t) => t.replace("mcp__agent-harness-kit__", "")).join(", ")}`);
-      if (r.extra.length) parts.push(`extra: ${r.extra.map((t) => t.replace("mcp__agent-harness-kit__", "")).join(", ")}`);
-      return `${name} (${parts.join("; ")})`;
-    }).join("\n   ");
-    process.stderr.write(`[agent-harness-kit] Agent permissions out of sync. Run: ahk build --sync
-   ${affected}
+    const affected = Object.entries(syncResult.agents).filter(([, r]) => !r.ok).map(([name]) => name).join(", ");
+    process.stderr.write(`[agent-harness-kit] Agent definition files missing: ${affected}. Run: ahk build
 `);
   }
   await startMcpServer(config, cwd2);
@@ -3232,12 +3195,12 @@ async function runServe(cwd2, opts) {
 
 // src/commands/status.ts
 import Table from "cli-table3";
-import pc11 from "picocolors";
+import pc12 from "picocolors";
 var STATUS_COLOR = {
-  pending: (s) => pc11.dim(s),
-  in_progress: (s) => pc11.cyan(s),
-  done: (s) => pc11.green(s),
-  blocked: (s) => pc11.red(s)
+  pending: (s) => pc12.dim(s),
+  in_progress: (s) => pc12.cyan(s),
+  done: (s) => pc12.green(s),
+  blocked: (s) => pc12.red(s)
 };
 async function runStatus(cwd2, opts) {
   const config = await loadConfig(cwd2);
@@ -3258,11 +3221,11 @@ async function runStatus(cwd2, opts) {
       return;
     }
     if (tasks.length === 0) {
-      console.log(pc11.dim("No tasks yet. Run: ahk task add"));
+      console.log(pc12.dim("No tasks yet. Run: ahk task add"));
       return;
     }
     const table = new Table({
-      head: ["ID", "Slug", "Title", "Status", "Assigned", "Started"].map((h) => pc11.bold(h)),
+      head: ["ID", "Slug", "Title", "Status", "Assigned", "Started"].map((h) => pc12.bold(h)),
       style: { head: [], border: [] }
     });
     for (const t of tasks) {
@@ -3280,12 +3243,12 @@ async function runStatus(cwd2, opts) {
     const inProgress = tasks.filter((t) => t.status === "in_progress");
     if (inProgress.length > 0) {
       console.log("");
-      console.log(pc11.bold("Active actions:"));
+      console.log(pc12.bold("Active actions:"));
       for (const t of inProgress) {
         const actions = await db.getActionsForTask(t.id);
         const active = actions.filter((a) => a.status === "in_progress");
         for (const a of active) {
-          console.log(`  ${pc11.cyan(a.agent.padEnd(10))} \u2192 task #${t.id} ${t.slug}`);
+          console.log(`  ${pc12.cyan(a.agent.padEnd(10))} \u2192 task #${t.id} ${t.slug}`);
         }
       }
     }
@@ -3294,10 +3257,10 @@ async function runStatus(cwd2, opts) {
       const fn = STATUS_COLOR[s.status] ?? ((x) => x);
       return `${fn(s.status)}: ${s.total}`;
     });
-    console.log(pc11.dim("Tasks \u2014 ") + parts.join(pc11.dim(" | ")));
+    console.log(pc12.dim("Tasks \u2014 ") + parts.join(pc12.dim(" | ")));
     const archivedTasks = await db.getArchivedTasks();
     if (archivedTasks.length > 0) {
-      console.log(pc11.dim(`${archivedTasks.length} archived (use \`ahk task list --archived\` to view)`));
+      console.log(pc12.dim(`${archivedTasks.length} archived (use \`ahk task list --archived\` to view)`));
     }
   } finally {
     await db.close();
@@ -3305,13 +3268,13 @@ async function runStatus(cwd2, opts) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync16, readFileSync as readFileSync11 } from "fs";
-import { join as join19, resolve as resolve10 } from "path";
-import pc12 from "picocolors";
+import { existsSync as existsSync17, readFileSync as readFileSync10 } from "fs";
+import { join as join20, resolve as resolve10 } from "path";
+import pc13 from "picocolors";
 async function runSync(cwd2, opts) {
   const config = await loadConfig(cwd2);
   const direction = opts.direction ?? "both";
-  const featureListPath = resolve10(join19(cwd2, config.storage.dir, "feature_list.json"));
+  const featureListPath = resolve10(join20(cwd2, config.storage.dir, "feature_list.json"));
   const db = await openDB(config, cwd2);
   try {
     if (direction === "in" || direction === "both") {
@@ -3325,44 +3288,44 @@ async function runSync(cwd2, opts) {
   }
 }
 async function syncIn(featureListPath, db, dryRun) {
-  if (!existsSync16(featureListPath)) {
-    console.log(pc12.dim(`feature_list.json not found at ${featureListPath} \u2014 skipping in-sync`));
+  if (!existsSync17(featureListPath)) {
+    console.log(pc13.dim(`feature_list.json not found at ${featureListPath} \u2014 skipping in-sync`));
     return;
   }
   let seeds;
   try {
-    seeds = JSON.parse(readFileSync11(featureListPath, "utf8"));
+    seeds = JSON.parse(readFileSync10(featureListPath, "utf8"));
   } catch (err) {
-    console.error(pc12.red(`Failed to parse feature_list.json: ${err}`));
+    console.error(pc13.red(`Failed to parse feature_list.json: ${err}`));
     process.exit(1);
   }
   if (dryRun) {
-    console.log(pc12.bold("Dry run \u2014 in-sync (feature_list.json \u2192 SQLite):"));
+    console.log(pc13.bold("Dry run \u2014 in-sync (feature_list.json \u2192 SQLite):"));
     for (const t of seeds) {
       const existing = await db.getTaskBySlug(t.slug);
-      console.log(`  ${existing ? pc12.dim("skip") : pc12.green("add ")} ${t.slug}`);
+      console.log(`  ${existing ? pc13.dim("skip") : pc13.green("add ")} ${t.slug}`);
     }
     return;
   }
   const result = await db.syncFromFeatureList(seeds);
-  console.log(pc12.green(`\u2713 In-sync: ${result.added} added, ${result.skipped} already existed`));
+  console.log(pc13.green(`\u2713 In-sync: ${result.added} added, ${result.skipped} already existed`));
 }
 async function syncOut(db, cwd2, dryRun) {
   if (dryRun) {
     const tasks = await db.getTasks();
-    console.log(pc12.bold("Dry run \u2014 out-sync (SQLite \u2192 feature_list.json):"));
+    console.log(pc13.bold("Dry run \u2014 out-sync (SQLite \u2192 feature_list.json):"));
     console.log(`  ${tasks.length} tasks would be written`);
     return;
   }
   await db.writeFeatureList(cwd2);
-  console.log(pc12.green("\u2713 Out-sync: feature_list.json updated"));
+  console.log(pc13.green("\u2713 Out-sync: feature_list.json updated"));
 }
 
 // src/commands/task/add.ts
 import * as p6 from "@clack/prompts";
-import pc13 from "picocolors";
+import pc14 from "picocolors";
 async function runTaskAdd(cwd2) {
-  p6.intro(pc13.bold("agent-harness-kit \u2014 add task"));
+  p6.intro(pc14.bold("agent-harness-kit \u2014 add task"));
   const title = await cliFormWithRetry(
     async () => {
       const val = await p6.text({ message: "Task title" });
@@ -3405,10 +3368,10 @@ async function runTaskAdd(cwd2) {
     await db.writeFeatureList(cwd2);
     await db.close();
     spinner6.stop("");
-    console.log(pc13.green(`\u2713 Task #${task2.id} added \u2014 ${task2.slug} (pending)`));
-    console.log(pc13.cyan("\u2192") + " " + pc13.cyan("ahk status") + " to see all tasks");
+    console.log(pc14.green(`\u2713 Task #${task2.id} added \u2014 ${task2.slug} (pending)`));
+    console.log(pc14.cyan("\u2192") + " " + pc14.cyan("ahk status") + " to see all tasks");
   } catch (err) {
-    spinner6.stop(pc13.red("Failed"));
+    spinner6.stop(pc14.red("Failed"));
     p6.log.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
@@ -3416,17 +3379,17 @@ async function runTaskAdd(cwd2) {
 
 // src/commands/task/done.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync17 } from "fs";
+import { existsSync as existsSync18 } from "fs";
 import { resolve as resolve11 } from "path";
-import pc14 from "picocolors";
+import pc15 from "picocolors";
 async function runTaskDone(cwd2, idOrSlug) {
   const config = await loadConfig(cwd2);
   if (config.health.required) {
     const scriptPath = resolve11(cwd2, config.health.scriptPath);
-    if (existsSync17(scriptPath)) {
+    if (existsSync18(scriptPath)) {
       const result = spawnSync2("bash", [scriptPath], { cwd: cwd2, stdio: "pipe", encoding: "utf8" });
       if (result.status !== 0) {
-        console.error(pc14.red("\u2717 Health check failed \u2014 cannot mark task as done."));
+        console.error(pc15.red("\u2717 Health check failed \u2014 cannot mark task as done."));
         if (result.stdout) console.error(result.stdout);
         if (result.stderr) console.error(result.stderr);
         process.exit(1);
@@ -3439,16 +3402,16 @@ async function runTaskDone(cwd2, idOrSlug) {
     const isId = !isNaN(parsed);
     const task2 = isId ? await db.getTaskById(parsed) : await db.getTaskBySlug(idOrSlug);
     if (!task2) {
-      console.error(pc14.red(`Task not found: ${idOrSlug}`));
+      console.error(pc15.red(`Task not found: ${idOrSlug}`));
       process.exit(1);
     }
     if (task2.status === "done") {
-      console.log(pc14.dim(`Task #${task2.id} is already done.`));
+      console.log(pc15.dim(`Task #${task2.id} is already done.`));
       return;
     }
     await db.updateTaskStatus(task2.id, "done");
     await db.writeFeatureList(cwd2);
-    console.log(pc14.green(`\u2713 Task #${task2.id} \u2014 ${task2.slug} marked as done`));
+    console.log(pc15.green(`\u2713 Task #${task2.id} \u2014 ${task2.slug} marked as done`));
   } finally {
     await db.close();
   }
@@ -3456,9 +3419,9 @@ async function runTaskDone(cwd2, idOrSlug) {
 
 // src/commands/task/edit.ts
 import * as p7 from "@clack/prompts";
-import pc15 from "picocolors";
+import pc16 from "picocolors";
 async function runTaskEdit(cwd2) {
-  p7.intro(pc15.bold("agent-harness-kit \u2014 edit task"));
+  p7.intro(pc16.bold("agent-harness-kit \u2014 edit task"));
   const config = await loadConfig(cwd2);
   const db = await openDB(config, cwd2);
   try {
@@ -3536,9 +3499,9 @@ async function runTaskEdit(cwd2) {
       await db.updateTaskAcceptance(task2.id, newAcceptance);
       await db.writeFeatureList(cwd2);
       spinner6.stop("");
-      console.log(pc15.green(`\u2713 Task #${task2.id} updated \u2014 ${newSlug}`));
+      console.log(pc16.green(`\u2713 Task #${task2.id} updated \u2014 ${newSlug}`));
     } catch (err) {
-      spinner6.stop(pc15.red("Failed"));
+      spinner6.stop(pc16.red("Failed"));
       p7.log.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -3549,12 +3512,12 @@ async function runTaskEdit(cwd2) {
 
 // src/commands/task/list.ts
 import Table2 from "cli-table3";
-import pc16 from "picocolors";
+import pc17 from "picocolors";
 var STATUS_COLOR2 = {
-  pending: (s) => pc16.dim(s),
-  in_progress: (s) => pc16.cyan(s),
-  done: (s) => pc16.green(s),
-  blocked: (s) => pc16.red(s)
+  pending: (s) => pc17.dim(s),
+  in_progress: (s) => pc17.cyan(s),
+  done: (s) => pc17.green(s),
+  blocked: (s) => pc17.red(s)
 };
 async function runTaskList(cwd2, opts) {
   const config = await loadConfig(cwd2);
@@ -3571,11 +3534,11 @@ async function runTaskList(cwd2, opts) {
       let msg = "No tasks";
       if (filterStatus) msg += ` with status: ${filterStatus}`;
       if (opts.archived) msg += " (archived)";
-      console.log(pc16.dim(msg + "."));
+      console.log(pc17.dim(msg + "."));
       return;
     }
     const table = new Table2({
-      head: ["ID", "Slug", "Title", "Status"].map((h) => pc16.bold(h)),
+      head: ["ID", "Slug", "Title", "Status"].map((h) => pc17.bold(h)),
       style: { head: [], border: [] }
     });
     for (const t of tasks) {
@@ -3586,7 +3549,7 @@ async function runTaskList(cwd2, opts) {
     if (!opts.archived && !opts.includeArchived) {
       const archivedTasks = await db.getArchivedTasks();
       if (archivedTasks.length > 0) {
-        console.log(pc16.dim(`${archivedTasks.length} archived task${archivedTasks.length !== 1 ? "s" : ""} (use --archived to view)`));
+        console.log(pc17.dim(`${archivedTasks.length} archived task${archivedTasks.length !== 1 ? "s" : ""} (use --archived to view)`));
       }
     }
   } finally {
@@ -3594,43 +3557,6 @@ async function runTaskList(cwd2, opts) {
   }
 }
 
-// src/core/local-install-guard.ts
-import { existsSync as existsSync18, readFileSync as readFileSync12 } from "fs";
-import { join as join20 } from "path";
-import pc17 from "picocolors";
-function isLocalInstallSatisfied(cwd2) {
-  const selfPkgPath = join20(cwd2, "package.json");
-  let projectPkg = null;
-  if (existsSync18(selfPkgPath)) {
-    try {
-      const selfPkg = JSON.parse(readFileSync12(selfPkgPath, "utf8"));
-      if (selfPkg?.name === pkg.name) return true;
-      projectPkg = selfPkg;
-    } catch {
-    }
-  }
-  const [scope, name] = pkg.name.split("/");
-  const localPath = pkg.name.startsWith("@") ? join20(cwd2, "node_modules", scope, name) : join20(cwd2, "node_modules", pkg.name);
-  if (existsSync18(localPath)) return true;
-  const isPnp = existsSync18(join20(cwd2, ".pnp.cjs")) || existsSync18(join20(cwd2, ".pnp.loader.mjs"));
-  if (isPnp && projectPkg) {
-    const deps = {
-      ...projectPkg.dependencies ?? {},
-      ...projectPkg.devDependencies ?? {}
-    };
-    if (Object.prototype.hasOwnProperty.call(deps, pkg.name)) return true;
-  }
-  return false;
-}
-function printLocalInstallWarning() {
-  console.error(pc17.yellow(`\u26A0 ${pkg.name} is not installed locally in this project.`));
-  console.error(pc17.dim("  This is only a recommendation for reproducibility: pinning a local"));
-  console.error(pc17.dim("  version keeps behavior consistent across your team and CI, instead of"));
-  console.error(pc17.dim("  drifting with whatever version is installed globally on each machine."));
-  console.error(pc17.dim(`  Run: npm install --save-dev ${pkg.name}`));
-  console.error(pc17.dim("  (or the equivalent for your package manager: pnpm add -D, yarn add --dev, bun add -d)"));
-}
-
 // src/core/update-check.ts
 import pc18 from "picocolors";
 var REGISTRY_URL2 = `https://registry.npmjs.org/${pkg.name}/latest`;
@@ -3672,7 +3598,10 @@ program.name("ahk").description("agent-harness-kit \u2014 CLI scaffolding for mu
 program.command("init").description("Scaffold a harness interactively in the current directory").option("--name <name>", "Project name (skip prompt)").option("--provider <provider>", "AI provider: claude-code | opencode (skip prompt)").option("--docs <path>", "Docs folder path (skip prompt)").option("--tasks <adapter>", "Task adapter: local | jira | linear (skip prompt)").option("--storage-scope <scope>", "Storage scope: local | global (skip prompt)").action(async (opts) => {
   await runInit(cwd, opts);
 });
-program.command("build").description("Regenerate AGENTS.md and provider files from agent-harness-kit.config.ts").option("--watch", "Rebuild on config changes").option("--sync", "Sync tools: frontmatter in existing .claude/agents/*.md to match current permission constants").action(async (opts) => {
+program.command("build").description("Regenerate AGENTS.md and provider files from agent-harness-kit.config.ts").option("--watch", "Rebuild on config changes").option("--sync", "Sync tools: frontmatter in existing .claude/agents/*.md to match current permission constants").option(
+  "--force",
+  "Regenerate agent files that already exist, DESTROYING your customizations (a backup is written first). Without this flag, build only creates agent files that are missing and never modifies existing ones."
+).action(async (opts) => {
   await runBuild(cwd, opts);
 });
 program.command("health").description("Run health.sh and report result").action(async () => {