facult 2.17.4 → 2.17.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.17.4",
+  "version": "2.17.7",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",

package/plugins/fclt/.mcp.json

@@ -5,7 +5,8 @@
       "args": ["./scripts/fclt-mcp.cjs"],
       "env": {
         "FCLT_BIN": "fclt"
-      }
+      },
+      "cwd": "."
     }
   }
 }

package/src/ai.ts

@@ -491,6 +491,18 @@ async function writeProposalReviewArtifact(args: {
   await Bun.write(pathValue, `${body.trimEnd()}\n`);
 }
 
+async function currentDraftBodyForProposal(
+  proposal: AiProposalRecord
+): Promise<string | null> {
+  const draftPath = proposal.draftRefs.find((pathValue) =>
+    pathValue.endsWith(".md")
+  );
+  if (!(draftPath && (await fileExists(draftPath)))) {
+    return null;
+  }
+  return readFile(draftPath, "utf8");
+}
+
 function slugToTitle(value: string): string {
   return value
     .split(SLUG_SPLIT_RE)
@@ -1375,6 +1387,7 @@ export async function refreshAiReviewArtifacts(args: {
       rootDir: args.rootDir,
       proposal,
       writebacks: sourceWritebacks,
+      draftBody: await currentDraftBodyForProposal(proposal),
     });
   }
 

package/src/builtin-assets.ts

@@ -7,5 +7,5 @@ export const BUILTIN_OPERATING_MODEL_FILES = JSON.parse(
 
 export const BUILTIN_FCLT_CODEX_PLUGIN_FILES = JSON.parse(
   // biome-ignore lint/suspicious/noTemplateCurlyInString: Built-in plugin files intentionally contain literal render placeholders.
-  '{".codex-plugin/plugin.json":"{\\n  \\"name\\": \\"fclt\\",\\n  \\"version\\": \\"0.1.0\\",\\n  \\"description\\": \\"Codex workflows and MCP tools for fclt setup, writeback, evolution, and capability review.\\",\\n  \\"license\\": \\"MIT\\",\\n  \\"keywords\\": [\\n    \\"fclt\\",\\n    \\"facult\\",\\n    \\"codex\\",\\n    \\"skills\\",\\n    \\"mcp\\",\\n    \\"writeback\\",\\n    \\"evolution\\"\\n  ],\\n  \\"skills\\": \\"./skills/\\",\\n  \\"mcpServers\\": \\"./.mcp.json\\",\\n  \\"interface\\": {\\n    \\"displayName\\": \\"fclt\\",\\n    \\"shortDescription\\": \\"Capability loops for Codex\\",\\n    \\"longDescription\\": \\"Install and operate fclt from Codex: initialize AI capability roots, inspect setup health, record writebacks, review evolution proposals, and keep skills, snippets, instructions, automations, and MCP surfaces improving over time.\\",\\n    \\"developerName\\": \\"Hack Dance\\",\\n    \\"category\\": \\"Productivity\\",\\n    \\"capabilities\\": [\\"Read\\", \\"Write\\", \\"MCP\\"],\\n    \\"defaultPrompt\\": [\\n      \\"Use fclt to check this repo\'s AI capability setup.\\",\\n      \\"Record useful fclt writeback from this work.\\",\\n      \\"Review fclt evolution proposals and next actions.\\"\\n    ],\\n    \\"brandColor\\": \\"#166534\\"\\n  }\\n}\\n",".mcp.json":"{\\n  \\"mcpServers\\": {\\n    \\"fclt\\": {\\n      \\"command\\": \\"node\\",\\n      \\"args\\": [\\"./scripts/fclt-mcp.cjs\\"],\\n      \\"env\\": {\\n        \\"FCLT_BIN\\": \\"fclt\\"\\n      }\\n    }\\n  }\\n}\\n","scripts/fclt-mcp.cjs":"#!/usr/bin/env node\\n\\"use strict\\";\\n\\nconst { spawn } = require(\\"node:child_process\\");\\n\\nconst FCLT_BIN = process.env.FCLT_BIN || \\"fclt\\";\\nconst DEFAULT_TIMEOUT_MS = Number(process.env.FCLT_MCP_TIMEOUT_MS || 60_000);\\nconst CONTENT_LENGTH_RE = /Content-Length:\\\\s*(\\\\d+)/i;\\n\\nconst tools = [\\n  {\\n    name: \\"fclt_status\\",\\n    description:\\n      \\"Return fclt status for the current, global, or project scope.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n  {\\n    name: \\"fclt_doctor\\",\\n    description: \\"Run read-only fclt doctor checks and return JSON output.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n  {\\n    name: \\"fclt_paths\\",\\n    description: \\"Return canonical, generated, review, and runtime fclt paths.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n  {\\n    name: \\"fclt_init_operating_model\\",\\n    description: \\"Install or update the built-in operating-model pack.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n        update: { type: \\"boolean\\" },\\n        dryRun: { type: \\"boolean\\" },\\n        force: { type: \\"boolean\\" },\\n      },\\n      required: [\\"scope\\"],\\n    },\\n  },\\n  {\\n    name: \\"fclt_writeback_add\\",\\n    description: \\"Record a durable fclt writeback with evidence.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n        kind: { type: \\"string\\" },\\n        summary: { type: \\"string\\" },\\n        asset: { type: \\"string\\" },\\n        evidence: { type: \\"string\\" },\\n        confidence: {\\n          type: \\"string\\",\\n          enum: [\\"low\\", \\"medium\\", \\"high\\"],\\n        },\\n      },\\n      required: [\\"kind\\", \\"summary\\"],\\n    },\\n  },\\n  {\\n    name: \\"fclt_writeback_review\\",\\n    description: \\"List, group, or summarize current fclt writebacks.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n        mode: { type: \\"string\\", enum: [\\"list\\", \\"group\\", \\"summarize\\"] },\\n        by: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n  {\\n    name: \\"fclt_evolve\\",\\n    description:\\n      \\"Assess, list, propose, draft, or review fclt evolution proposals.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n        action: {\\n          type: \\"string\\",\\n          enum: [\\"assess\\", \\"list\\", \\"propose\\", \\"draft\\", \\"review\\", \\"show\\"],\\n        },\\n        id: { type: \\"string\\" },\\n        asset: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n];\\n\\nfunction scopeArgs(scope) {\\n  if (scope === \\"global\\") {\\n    return [\\"--global\\"];\\n  }\\n  if (scope === \\"project\\") {\\n    return [\\"--project\\"];\\n  }\\n  return [];\\n}\\n\\nfunction boolFlag(name, value) {\\n  return value ? [name] : [];\\n}\\n\\nfunction stringFlag(name, value) {\\n  return typeof value === \\"string\\" && value.trim() ? [name, value] : [];\\n}\\n\\nfunction commandForTool(name, args = {}) {\\n  switch (name) {\\n    case \\"fclt_status\\":\\n      return [\\"status\\", ...scopeArgs(args.scope), \\"--json\\"];\\n    case \\"fclt_doctor\\":\\n      return [\\"doctor\\", ...scopeArgs(args.scope), \\"--json\\"];\\n    case \\"fclt_paths\\":\\n      return [\\"paths\\", ...scopeArgs(args.scope), \\"--json\\"];\\n    case \\"fclt_init_operating_model\\":\\n      return [\\n        \\"templates\\",\\n        \\"init\\",\\n        \\"operating-model\\",\\n        ...scopeArgs(args.scope),\\n        ...boolFlag(\\"--update\\", args.update),\\n        ...boolFlag(\\"--dry-run\\", args.dryRun),\\n        ...boolFlag(\\"--force\\", args.force),\\n        \\"--json\\",\\n      ];\\n    case \\"fclt_writeback_add\\":\\n      return [\\n        \\"ai\\",\\n        \\"writeback\\",\\n        ...scopeArgs(args.scope),\\n        \\"add\\",\\n        \\"--kind\\",\\n        args.kind,\\n        \\"--summary\\",\\n        args.summary,\\n        ...stringFlag(\\"--asset\\", args.asset),\\n        ...stringFlag(\\"--evidence\\", args.evidence),\\n        ...stringFlag(\\"--confidence\\", args.confidence),\\n      ];\\n    case \\"fclt_writeback_review\\": {\\n      const mode = args.mode || \\"list\\";\\n      return [\\n        \\"ai\\",\\n        \\"writeback\\",\\n        ...scopeArgs(args.scope),\\n        mode,\\n        ...stringFlag(\\"--by\\", args.by),\\n      ];\\n    }\\n    case \\"fclt_evolve\\": {\\n      const action = args.action || \\"list\\";\\n      return [\\n        \\"ai\\",\\n        \\"evolve\\",\\n        ...scopeArgs(args.scope),\\n        action,\\n        ...(action === \\"assess\\" || action === \\"propose\\"\\n          ? stringFlag(\\"--asset\\", args.asset)\\n          : []),\\n        ...(args.id ? [args.id] : []),\\n        ...(action === \\"assess\\" ? [\\"--json\\"] : []),\\n      ];\\n    }\\n    default:\\n      throw new Error(`Unknown tool: ${name}`);\\n  }\\n}\\n\\nfunction runFclt(args, cwd) {\\n  return new Promise((resolve) => {\\n    const child = spawn(FCLT_BIN, args, {\\n      cwd: cwd || process.cwd(),\\n      env: process.env,\\n      stdio: [\\"ignore\\", \\"pipe\\", \\"pipe\\"],\\n    });\\n    let stdout = \\"\\";\\n    let stderr = \\"\\";\\n    const timer = setTimeout(() => {\\n      child.kill(\\"SIGTERM\\");\\n    }, DEFAULT_TIMEOUT_MS);\\n    child.stdout.on(\\"data\\", (chunk) => {\\n      stdout += chunk.toString();\\n    });\\n    child.stderr.on(\\"data\\", (chunk) => {\\n      stderr += chunk.toString();\\n    });\\n    child.on(\\"close\\", (code) => {\\n      clearTimeout(timer);\\n      resolve({\\n        code,\\n        text: [\\n          `$ ${FCLT_BIN} ${args.join(\\" \\")}`,\\n          stdout.trim(),\\n          stderr.trim() ? `stderr:\\\\n${stderr.trim()}` : \\"\\",\\n        ]\\n          .filter(Boolean)\\n          .join(\\"\\\\n\\\\n\\"),\\n      });\\n    });\\n  });\\n}\\n\\nfunction send(message) {\\n  const body = JSON.stringify(message);\\n  process.stdout.write(\\n    `Content-Length: ${Buffer.byteLength(body)}\\\\r\\\\n\\\\r\\\\n${body}`\\n  );\\n}\\n\\nasync function handle(message) {\\n  if (!message || message.id == null) {\\n    return;\\n  }\\n\\n  try {\\n    if (message.method === \\"initialize\\") {\\n      send({\\n        jsonrpc: \\"2.0\\",\\n        id: message.id,\\n        result: {\\n          protocolVersion: \\"2025-06-18\\",\\n          capabilities: { tools: {} },\\n          serverInfo: { name: \\"fclt\\", version: \\"0.1.0\\" },\\n        },\\n      });\\n      return;\\n    }\\n    if (message.method === \\"tools/list\\") {\\n      send({ jsonrpc: \\"2.0\\", id: message.id, result: { tools } });\\n      return;\\n    }\\n    if (message.method === \\"tools/call\\") {\\n      const { name, arguments: args = {} } = message.params || {};\\n      const command = commandForTool(name, args);\\n      const result = await runFclt(command, args.cwd);\\n      send({\\n        jsonrpc: \\"2.0\\",\\n        id: message.id,\\n        result: {\\n          isError: result.code !== 0,\\n          content: [{ type: \\"text\\", text: result.text }],\\n        },\\n      });\\n      return;\\n    }\\n    send({\\n      jsonrpc: \\"2.0\\",\\n      id: message.id,\\n      error: { code: -32_601, message: `Method not found: ${message.method}` },\\n    });\\n  } catch (error) {\\n    send({\\n      jsonrpc: \\"2.0\\",\\n      id: message.id,\\n      error: {\\n        code: -32_000,\\n        message: error instanceof Error ? error.message : String(error),\\n      },\\n    });\\n  }\\n}\\n\\nlet buffer = Buffer.alloc(0);\\n\\nprocess.stdin.on(\\"data\\", (chunk) => {\\n  buffer = Buffer.concat([buffer, chunk]);\\n  while (true) {\\n    const headerEnd = buffer.indexOf(\\"\\\\r\\\\n\\\\r\\\\n\\");\\n    if (headerEnd === -1) {\\n      return;\\n    }\\n    const header = buffer.slice(0, headerEnd).toString(\\"utf8\\");\\n    const match = CONTENT_LENGTH_RE.exec(header);\\n    if (!match) {\\n      buffer = Buffer.alloc(0);\\n      return;\\n    }\\n    const length = Number(match[1]);\\n    const frameEnd = headerEnd + 4 + length;\\n    if (buffer.length < frameEnd) {\\n      return;\\n    }\\n    const body = buffer.slice(headerEnd + 4, frameEnd).toString(\\"utf8\\");\\n    buffer = buffer.slice(frameEnd);\\n    handle(JSON.parse(body)).catch((error) => {\\n      send({\\n        jsonrpc: \\"2.0\\",\\n        id: null,\\n        error: {\\n          code: -32_000,\\n          message: error instanceof Error ? error.message : String(error),\\n        },\\n      });\\n    });\\n  }\\n});\\n\\nif (process.argv.includes(\\"--self-test\\")) {\\n  console.log(\\n    JSON.stringify({ tools: tools.map((tool) => tool.name) }, null, 2)\\n  );\\n  process.exit(0);\\n}\\n","skills/fclt-capability-review/SKILL.md":"---\\ndescription: Inspect fclt capability roots, docs, snippets, skills, agents, MCP, and automations.\\ntags: [fclt, capability, review, inventory]\\n---\\n\\n# fclt-capability-review\\n\\n## When To Use\\nUse this skill when Codex needs to understand what capability exists before changing it.\\n\\nUse it for:\\n\\n- checking global and project `.ai` roots\\n- finding relevant skills, snippets, instructions, agents, MCP servers, or automations\\n- deciding whether a change belongs in global or project scope\\n- checking whether managed rendering is enabled or needed\\n- reviewing public/private boundaries before publishing docs or pack assets\\n\\n## Workflow\\n\\n```bash\\nfclt status --json\\nfclt inventory --json\\nfclt list skills\\nfclt list instructions\\nfclt list snippets\\nfclt graph AGENTS.global.md\\n```\\n\\nFor project work:\\n\\n```bash\\nfclt status --project --json\\nfclt inventory --project --json\\n```\\n\\n## Rules\\n\\n- Read existing repo guidance before proposing project capability.\\n- Use project scope for repo-specific commands, tests, architecture, or team workflow.\\n- Use global scope only for broadly reusable behavior.\\n- Keep generated state and review artifacts out of repo-local `.ai`.\\n- Prefer adding or updating the smallest unit: instruction, snippet, skill, agent, MCP config, or automation.\\n\\n## Output\\n\\n- capability roots found\\n- relevant assets\\n- scope recommendation\\n- missing or stale capability\\n- safe next command\\n","skills/fclt-evolution/SKILL.md":"---\\ndescription: Turn repeated fclt writebacks into reviewed capability changes.\\ntags: [fclt, evolution, proposals, capability]\\n---\\n\\n# fclt-evolution\\n\\n## When To Use\\nUse this skill when repeated writebacks, stale canonical assets, or a clearly missing capability should become a concrete proposal.\\n\\nDo not use it for a single weak preference or speculative idea.\\n\\n## Workflow\\n\\n1. Review signal:\\n\\n```bash\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve list\\n```\\n\\n2. Assess proposal readiness before mutating state:\\n\\n```bash\\nfclt ai evolve assess --asset <selector> --json\\n```\\n\\nUse the assessment recommendation as the decision checkpoint:\\n\\n- `no_mutation`: do not change capability state; ask for a target or evidence.\\n- `record_more_writeback`: explain what recurrence would justify evolution and record a new writeback only if there is fresh concrete evidence.\\n- `propose`: ask before running the proposal command, then create the smallest target-specific proposal.\\n- `review_existing_proposal`: inspect or revise the existing proposal instead of creating a duplicate.\\n\\n3. Propose only when evidence is strong enough:\\n\\n```bash\\nfclt ai evolve propose\\n```\\n\\n4. Draft and inspect:\\n\\n```bash\\nfclt ai evolve draft EV-00001\\nfclt ai evolve review EV-00001\\n```\\n\\n5. Accept/apply only when scope, target, and evidence are correct:\\n\\n```bash\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\n## Proposal Kinds\\n\\n- `update_asset`\\n- `create_asset`\\n- `extract_snippet`\\n- `add_skill`\\n- `promote_asset`\\n\\n## Rules\\n\\n- Prefer the smallest valid proposal kind.\\n- Keep project-specific behavior project-scoped until reuse is proven.\\n- Ask for approval before applying global instructions, global skills, plugin behavior, or other broad shared surfaces.\\n- Reject or park proposals that are stale, duplicated, vague, or unsupported.\\n- Use Linear or another task system for executable implementation work that needs owner, priority, or state.\\n- A no-op answer must still be useful: include the evidence grade, missing signal, next writeback target, and exact approval boundary.\\n\\n## Output\\n\\n- proposals reviewed\\n- repeated signal\\n- assessment recommendation\\n- proposal created or updated\\n- approvals needed\\n- apply/reject/no-op rationale\\n","skills/fclt-setup/SKILL.md":"---\\ndescription: Install, update, inspect, and initialize fclt from Codex.\\ntags: [fclt, setup, codex, onboarding]\\n---\\n\\n# fclt-setup\\n\\n## When To Use\\nUse this skill when a user wants Codex to install, update, configure, inspect, or repair fclt.\\n\\nUse it for:\\n\\n- checking whether `fclt` is installed and current\\n- initializing global `~/.ai` or project `<repo>/.ai`\\n- installing or refreshing the built-in operating-model pack\\n- checking setup health with `doctor`\\n- finding canonical, generated, runtime, and review paths\\n\\n## Workflow\\n\\n1. Check current state:\\n\\n```bash\\nfclt --version\\nfclt paths --json\\nfclt doctor --json\\n```\\n\\n2. If global capability is missing, initialize it:\\n\\n```bash\\nfclt templates init operating-model --global\\n```\\n\\n3. If a repo needs local capability, initialize project AI:\\n\\n```bash\\nfclt templates init project-ai\\n```\\n\\n4. Refresh pack defaults non-destructively:\\n\\n```bash\\nfclt templates init operating-model --global --update --dry-run\\nfclt templates init operating-model --global --update\\n```\\n\\n5. Use `--force` only when the user explicitly wants to replace local edits.\\n\\n## Rules\\n\\n- Preserve existing `AGENTS.md`, `CLAUDE.md`, and `AGENTS.global.md` guidance.\\n- First install should seed from existing agent guidance when available.\\n- Treat `doctor --json` issues as setup facts, not user-facing blame.\\n- Prefer temp-root smoke tests for install/update behavior.\\n- Do not enable managed rendering unless the user wants fclt to write tool homes.\\n\\n## Output\\n\\n- current installed version\\n- setup health\\n- paths that matter\\n- commands run\\n- what changed\\n- what still needs approval\\n","skills/fclt-writeback/SKILL.md":"---\\ndescription: Record and review fclt writebacks from real agent work.\\ntags: [fclt, writeback, learning, feedback-loop]\\n---\\n\\n# fclt-writeback\\n\\n## When To Use\\nUse this skill when work reveals durable friction, missing context, weak verification, stale guidance, repeated success, or a capability gap.\\n\\nWriteback is for preserving signal. It is not for every preference or one-off annoyance.\\n\\n## Workflow\\n\\n1. Decide scope:\\n\\n- `project` when the learning depends on a repo, test harness, architecture, or workflow.\\n- `global` when the learning applies across projects or shared tool behavior.\\n\\n2. Choose the smallest target:\\n\\n- instruction\\n- snippet\\n- skill\\n- agent\\n- MCP/tool config\\n- automation\\n\\n3. Record writeback when the target and evidence are clear:\\n\\n```bash\\nfclt ai writeback add --kind missing_context --summary \\"...\\" --asset @project/instructions/TESTING.md\\n```\\n\\n4. Review current signal:\\n\\n```bash\\nfclt ai writeback list\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\n```\\n\\n## Rules\\n\\n- Prefer one high-signal writeback over several weak ones.\\n- Include concrete evidence when possible.\\n- Do not copy private project detail into global writebacks.\\n- Use task tracking for executable product/tooling work; use writeback for reusable operating-layer learning.\\n- If the same signal repeats and the target is clear, hand off to `fclt-evolution`.\\n\\n## Output\\n\\n- writeback id or no-op rationale\\n- scope\\n- target asset\\n- evidence summary\\n- whether this is ready for evolution\\n"}'
+  '{".codex-plugin/plugin.json":"{\\n  \\"name\\": \\"fclt\\",\\n  \\"version\\": \\"0.1.0\\",\\n  \\"description\\": \\"Codex workflows and MCP tools for fclt setup, writeback, evolution, and capability review.\\",\\n  \\"license\\": \\"MIT\\",\\n  \\"keywords\\": [\\n    \\"fclt\\",\\n    \\"facult\\",\\n    \\"codex\\",\\n    \\"skills\\",\\n    \\"mcp\\",\\n    \\"writeback\\",\\n    \\"evolution\\"\\n  ],\\n  \\"skills\\": \\"./skills/\\",\\n  \\"mcpServers\\": \\"./.mcp.json\\",\\n  \\"interface\\": {\\n    \\"displayName\\": \\"fclt\\",\\n    \\"shortDescription\\": \\"Capability loops for Codex\\",\\n    \\"longDescription\\": \\"Install and operate fclt from Codex: initialize AI capability roots, inspect setup health, record writebacks, review evolution proposals, and keep skills, snippets, instructions, automations, and MCP surfaces improving over time.\\",\\n    \\"developerName\\": \\"Hack Dance\\",\\n    \\"category\\": \\"Productivity\\",\\n    \\"capabilities\\": [\\"Read\\", \\"Write\\", \\"MCP\\"],\\n    \\"defaultPrompt\\": [\\n      \\"Use fclt to check this repo\'s AI capability setup.\\",\\n      \\"Record useful fclt writeback from this work.\\",\\n      \\"Review fclt evolution proposals and next actions.\\"\\n    ],\\n    \\"brandColor\\": \\"#166534\\"\\n  }\\n}\\n",".mcp.json":"{\\n  \\"mcpServers\\": {\\n    \\"fclt\\": {\\n      \\"command\\": \\"node\\",\\n      \\"args\\": [\\"./scripts/fclt-mcp.cjs\\"],\\n      \\"env\\": {\\n        \\"FCLT_BIN\\": \\"fclt\\"\\n      },\\n      \\"cwd\\": \\".\\"\\n    }\\n  }\\n}\\n","scripts/fclt-mcp.cjs":"#!/usr/bin/env node\\n\\"use strict\\";\\n\\nconst { spawn } = require(\\"node:child_process\\");\\n\\nconst FCLT_BIN = process.env.FCLT_BIN || \\"fclt\\";\\nconst DEFAULT_TIMEOUT_MS = Number(process.env.FCLT_MCP_TIMEOUT_MS || 60_000);\\nconst CONTENT_LENGTH_RE = /Content-Length:\\\\s*(\\\\d+)/i;\\n\\nconst tools = [\\n  {\\n    name: \\"fclt_status\\",\\n    description:\\n      \\"Return fclt status for the current, global, or project scope.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n  {\\n    name: \\"fclt_doctor\\",\\n    description: \\"Run read-only fclt doctor checks and return JSON output.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n  {\\n    name: \\"fclt_paths\\",\\n    description: \\"Return canonical, generated, review, and runtime fclt paths.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n  {\\n    name: \\"fclt_init_operating_model\\",\\n    description: \\"Install or update the built-in operating-model pack.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n        update: { type: \\"boolean\\" },\\n        dryRun: { type: \\"boolean\\" },\\n        force: { type: \\"boolean\\" },\\n      },\\n      required: [\\"scope\\"],\\n    },\\n  },\\n  {\\n    name: \\"fclt_writeback_add\\",\\n    description: \\"Record a durable fclt writeback with evidence.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n        kind: { type: \\"string\\" },\\n        summary: { type: \\"string\\" },\\n        asset: { type: \\"string\\" },\\n        evidence: { type: \\"string\\" },\\n        confidence: {\\n          type: \\"string\\",\\n          enum: [\\"low\\", \\"medium\\", \\"high\\"],\\n        },\\n      },\\n      required: [\\"kind\\", \\"summary\\"],\\n    },\\n  },\\n  {\\n    name: \\"fclt_writeback_review\\",\\n    description: \\"List, group, or summarize current fclt writebacks.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n        mode: { type: \\"string\\", enum: [\\"list\\", \\"group\\", \\"summarize\\"] },\\n        by: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n  {\\n    name: \\"fclt_evolve\\",\\n    description:\\n      \\"Assess, list, propose, draft, or review fclt evolution proposals.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        scope: { type: \\"string\\", enum: [\\"auto\\", \\"global\\", \\"project\\"] },\\n        cwd: { type: \\"string\\" },\\n        action: {\\n          type: \\"string\\",\\n          enum: [\\"assess\\", \\"list\\", \\"propose\\", \\"draft\\", \\"review\\", \\"show\\"],\\n        },\\n        id: { type: \\"string\\" },\\n        asset: { type: \\"string\\" },\\n      },\\n    },\\n  },\\n];\\n\\nfunction scopeArgs(scope) {\\n  if (scope === \\"global\\") {\\n    return [\\"--global\\"];\\n  }\\n  if (scope === \\"project\\") {\\n    return [\\"--project\\"];\\n  }\\n  return [];\\n}\\n\\nfunction boolFlag(name, value) {\\n  return value ? [name] : [];\\n}\\n\\nfunction stringFlag(name, value) {\\n  return typeof value === \\"string\\" && value.trim() ? [name, value] : [];\\n}\\n\\nfunction commandForTool(name, args = {}) {\\n  switch (name) {\\n    case \\"fclt_status\\":\\n      return [\\"status\\", ...scopeArgs(args.scope), \\"--json\\"];\\n    case \\"fclt_doctor\\":\\n      return [\\"doctor\\", ...scopeArgs(args.scope), \\"--json\\"];\\n    case \\"fclt_paths\\":\\n      return [\\"paths\\", ...scopeArgs(args.scope), \\"--json\\"];\\n    case \\"fclt_init_operating_model\\":\\n      return [\\n        \\"templates\\",\\n        \\"init\\",\\n        \\"operating-model\\",\\n        ...scopeArgs(args.scope),\\n        ...boolFlag(\\"--update\\", args.update),\\n        ...boolFlag(\\"--dry-run\\", args.dryRun),\\n        ...boolFlag(\\"--force\\", args.force),\\n        \\"--json\\",\\n      ];\\n    case \\"fclt_writeback_add\\":\\n      return [\\n        \\"ai\\",\\n        \\"writeback\\",\\n        ...scopeArgs(args.scope),\\n        \\"add\\",\\n        \\"--kind\\",\\n        args.kind,\\n        \\"--summary\\",\\n        args.summary,\\n        ...stringFlag(\\"--asset\\", args.asset),\\n        ...stringFlag(\\"--evidence\\", args.evidence),\\n        ...stringFlag(\\"--confidence\\", args.confidence),\\n      ];\\n    case \\"fclt_writeback_review\\": {\\n      const mode = args.mode || \\"list\\";\\n      return [\\n        \\"ai\\",\\n        \\"writeback\\",\\n        ...scopeArgs(args.scope),\\n        mode,\\n        ...stringFlag(\\"--by\\", args.by),\\n      ];\\n    }\\n    case \\"fclt_evolve\\": {\\n      const action = args.action || \\"list\\";\\n      return [\\n        \\"ai\\",\\n        \\"evolve\\",\\n        ...scopeArgs(args.scope),\\n        action,\\n        ...(action === \\"assess\\" || action === \\"propose\\"\\n          ? stringFlag(\\"--asset\\", args.asset)\\n          : []),\\n        ...(args.id ? [args.id] : []),\\n        ...(action === \\"assess\\" ? [\\"--json\\"] : []),\\n      ];\\n    }\\n    default:\\n      throw new Error(`Unknown tool: ${name}`);\\n  }\\n}\\n\\nfunction runFclt(args, cwd) {\\n  return new Promise((resolve) => {\\n    const child = spawn(FCLT_BIN, args, {\\n      cwd: cwd || process.cwd(),\\n      env: process.env,\\n      stdio: [\\"ignore\\", \\"pipe\\", \\"pipe\\"],\\n    });\\n    let stdout = \\"\\";\\n    let stderr = \\"\\";\\n    const timer = setTimeout(() => {\\n      child.kill(\\"SIGTERM\\");\\n    }, DEFAULT_TIMEOUT_MS);\\n    child.stdout.on(\\"data\\", (chunk) => {\\n      stdout += chunk.toString();\\n    });\\n    child.stderr.on(\\"data\\", (chunk) => {\\n      stderr += chunk.toString();\\n    });\\n    child.on(\\"close\\", (code) => {\\n      clearTimeout(timer);\\n      resolve({\\n        code,\\n        text: [\\n          `$ ${FCLT_BIN} ${args.join(\\" \\")}`,\\n          stdout.trim(),\\n          stderr.trim() ? `stderr:\\\\n${stderr.trim()}` : \\"\\",\\n        ]\\n          .filter(Boolean)\\n          .join(\\"\\\\n\\\\n\\"),\\n      });\\n    });\\n  });\\n}\\n\\nfunction send(message) {\\n  const body = JSON.stringify(message);\\n  process.stdout.write(\\n    `Content-Length: ${Buffer.byteLength(body)}\\\\r\\\\n\\\\r\\\\n${body}`\\n  );\\n}\\n\\nasync function handle(message) {\\n  if (!message || message.id == null) {\\n    return;\\n  }\\n\\n  try {\\n    if (message.method === \\"initialize\\") {\\n      send({\\n        jsonrpc: \\"2.0\\",\\n        id: message.id,\\n        result: {\\n          protocolVersion: \\"2025-06-18\\",\\n          capabilities: { tools: {} },\\n          serverInfo: { name: \\"fclt\\", version: \\"0.1.0\\" },\\n        },\\n      });\\n      return;\\n    }\\n    if (message.method === \\"tools/list\\") {\\n      send({ jsonrpc: \\"2.0\\", id: message.id, result: { tools } });\\n      return;\\n    }\\n    if (message.method === \\"tools/call\\") {\\n      const { name, arguments: args = {} } = message.params || {};\\n      const command = commandForTool(name, args);\\n      const result = await runFclt(command, args.cwd);\\n      send({\\n        jsonrpc: \\"2.0\\",\\n        id: message.id,\\n        result: {\\n          isError: result.code !== 0,\\n          content: [{ type: \\"text\\", text: result.text }],\\n        },\\n      });\\n      return;\\n    }\\n    send({\\n      jsonrpc: \\"2.0\\",\\n      id: message.id,\\n      error: { code: -32_601, message: `Method not found: ${message.method}` },\\n    });\\n  } catch (error) {\\n    send({\\n      jsonrpc: \\"2.0\\",\\n      id: message.id,\\n      error: {\\n        code: -32_000,\\n        message: error instanceof Error ? error.message : String(error),\\n      },\\n    });\\n  }\\n}\\n\\nlet buffer = Buffer.alloc(0);\\n\\nprocess.stdin.on(\\"data\\", (chunk) => {\\n  buffer = Buffer.concat([buffer, chunk]);\\n  while (true) {\\n    const headerEnd = buffer.indexOf(\\"\\\\r\\\\n\\\\r\\\\n\\");\\n    if (headerEnd === -1) {\\n      return;\\n    }\\n    const header = buffer.slice(0, headerEnd).toString(\\"utf8\\");\\n    const match = CONTENT_LENGTH_RE.exec(header);\\n    if (!match) {\\n      buffer = Buffer.alloc(0);\\n      return;\\n    }\\n    const length = Number(match[1]);\\n    const frameEnd = headerEnd + 4 + length;\\n    if (buffer.length < frameEnd) {\\n      return;\\n    }\\n    const body = buffer.slice(headerEnd + 4, frameEnd).toString(\\"utf8\\");\\n    buffer = buffer.slice(frameEnd);\\n    handle(JSON.parse(body)).catch((error) => {\\n      send({\\n        jsonrpc: \\"2.0\\",\\n        id: null,\\n        error: {\\n          code: -32_000,\\n          message: error instanceof Error ? error.message : String(error),\\n        },\\n      });\\n    });\\n  }\\n});\\n\\nif (process.argv.includes(\\"--self-test\\")) {\\n  console.log(\\n    JSON.stringify({ tools: tools.map((tool) => tool.name) }, null, 2)\\n  );\\n  process.exit(0);\\n}\\n","skills/fclt-capability-review/SKILL.md":"---\\ndescription: Inspect fclt capability roots, docs, snippets, skills, agents, MCP, and automations.\\ntags: [fclt, capability, review, inventory]\\n---\\n\\n# fclt-capability-review\\n\\n## When To Use\\nUse this skill when Codex needs to understand what capability exists before changing it.\\n\\nUse it for:\\n\\n- checking global and project `.ai` roots\\n- finding relevant skills, snippets, instructions, agents, MCP servers, or automations\\n- deciding whether a change belongs in global or project scope\\n- checking whether managed rendering is enabled or needed\\n- reviewing public/private boundaries before publishing docs or pack assets\\n\\n## Workflow\\n\\n```bash\\nfclt status --json\\nfclt inventory --json\\nfclt list skills\\nfclt list instructions\\nfclt list snippets\\nfclt graph AGENTS.global.md\\n```\\n\\nFor project work:\\n\\n```bash\\nfclt status --project --json\\nfclt inventory --project --json\\n```\\n\\n## Rules\\n\\n- Read existing repo guidance before proposing project capability.\\n- Use project scope for repo-specific commands, tests, architecture, or team workflow.\\n- Use global scope only for broadly reusable behavior.\\n- Keep generated state and review artifacts out of repo-local `.ai`.\\n- Prefer adding or updating the smallest unit: instruction, snippet, skill, agent, MCP config, or automation.\\n\\n## Output\\n\\n- capability roots found\\n- relevant assets\\n- scope recommendation\\n- missing or stale capability\\n- safe next command\\n","skills/fclt-evolution/SKILL.md":"---\\ndescription: Turn repeated fclt writebacks into reviewed capability changes.\\ntags: [fclt, evolution, proposals, capability]\\n---\\n\\n# fclt-evolution\\n\\n## When To Use\\nUse this skill when repeated writebacks, stale canonical assets, or a clearly missing capability should become a concrete proposal.\\n\\nDo not use it for a single weak preference or speculative idea.\\n\\n## Workflow\\n\\n1. Review signal:\\n\\n```bash\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve list\\n```\\n\\n2. Assess proposal readiness before mutating state:\\n\\n```bash\\nfclt ai evolve assess --asset <selector> --json\\n```\\n\\nUse the assessment recommendation as the decision checkpoint:\\n\\n- `no_mutation`: do not change capability state; ask for a target or evidence.\\n- `record_more_writeback`: explain what recurrence would justify evolution and record a new writeback only if there is fresh concrete evidence.\\n- `propose`: ask before running the proposal command, then create the smallest target-specific proposal.\\n- `review_existing_proposal`: inspect or revise the existing proposal instead of creating a duplicate.\\n\\n3. Propose only when evidence is strong enough:\\n\\n```bash\\nfclt ai evolve propose\\n```\\n\\n4. Draft and inspect:\\n\\n```bash\\nfclt ai evolve draft EV-00001\\nfclt ai evolve review EV-00001\\n```\\n\\n5. Accept/apply only when scope, target, and evidence are correct:\\n\\n```bash\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\n## Proposal Kinds\\n\\n- `update_asset`\\n- `create_asset`\\n- `extract_snippet`\\n- `add_skill`\\n- `promote_asset`\\n\\n## Rules\\n\\n- Prefer the smallest valid proposal kind.\\n- Keep project-specific behavior project-scoped until reuse is proven.\\n- Ask for approval before applying global instructions, global skills, plugin behavior, or other broad shared surfaces.\\n- Reject or park proposals that are stale, duplicated, vague, or unsupported.\\n- Use Linear or another task system for executable implementation work that needs owner, priority, or state.\\n- A no-op answer must still be useful: include the evidence grade, missing signal, next writeback target, and exact approval boundary.\\n\\n## Output\\n\\n- proposals reviewed\\n- repeated signal\\n- assessment recommendation\\n- proposal created or updated\\n- approvals needed\\n- apply/reject/no-op rationale\\n","skills/fclt-setup/SKILL.md":"---\\ndescription: Install, update, inspect, and initialize fclt from Codex.\\ntags: [fclt, setup, codex, onboarding]\\n---\\n\\n# fclt-setup\\n\\n## When To Use\\nUse this skill when a user wants Codex to install, update, configure, inspect, or repair fclt.\\n\\nUse it for:\\n\\n- checking whether `fclt` is installed and current\\n- initializing global `~/.ai` or project `<repo>/.ai`\\n- installing or refreshing the built-in operating-model pack\\n- checking setup health with `doctor`\\n- finding canonical, generated, runtime, and review paths\\n\\n## Workflow\\n\\n1. Check current state:\\n\\n```bash\\nfclt --version\\nfclt paths --json\\nfclt doctor --json\\n```\\n\\n2. If global capability is missing, initialize it:\\n\\n```bash\\nfclt templates init operating-model --global\\n```\\n\\n3. If a repo needs local capability, initialize project AI:\\n\\n```bash\\nfclt templates init project-ai\\n```\\n\\n4. Refresh pack defaults non-destructively:\\n\\n```bash\\nfclt templates init operating-model --global --update --dry-run\\nfclt templates init operating-model --global --update\\n```\\n\\n5. Use `--force` only when the user explicitly wants to replace local edits.\\n\\n## Rules\\n\\n- Preserve existing `AGENTS.md`, `CLAUDE.md`, and `AGENTS.global.md` guidance.\\n- First install should seed from existing agent guidance when available.\\n- Treat `doctor --json` issues as setup facts, not user-facing blame.\\n- Prefer temp-root smoke tests for install/update behavior.\\n- Do not enable managed rendering unless the user wants fclt to write tool homes.\\n\\n## Output\\n\\n- current installed version\\n- setup health\\n- paths that matter\\n- commands run\\n- what changed\\n- what still needs approval\\n","skills/fclt-writeback/SKILL.md":"---\\ndescription: Record and review fclt writebacks from real agent work.\\ntags: [fclt, writeback, learning, feedback-loop]\\n---\\n\\n# fclt-writeback\\n\\n## When To Use\\nUse this skill when work reveals durable friction, missing context, weak verification, stale guidance, repeated success, or a capability gap.\\n\\nWriteback is for preserving signal. It is not for every preference or one-off annoyance.\\n\\n## Workflow\\n\\n1. Decide scope:\\n\\n- `project` when the learning depends on a repo, test harness, architecture, or workflow.\\n- `global` when the learning applies across projects or shared tool behavior.\\n\\n2. Choose the smallest target:\\n\\n- instruction\\n- snippet\\n- skill\\n- agent\\n- MCP/tool config\\n- automation\\n\\n3. Record writeback when the target and evidence are clear:\\n\\n```bash\\nfclt ai writeback add --kind missing_context --summary \\"...\\" --asset @project/instructions/TESTING.md\\n```\\n\\n4. Review current signal:\\n\\n```bash\\nfclt ai writeback list\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\n```\\n\\n## Rules\\n\\n- Prefer one high-signal writeback over several weak ones.\\n- Include concrete evidence when possible.\\n- Do not copy private project detail into global writebacks.\\n- Use task tracking for executable product/tooling work; use writeback for reusable operating-layer learning.\\n- If the same signal repeats and the target is clear, hand off to `fclt-evolution`.\\n\\n## Output\\n\\n- writeback id or no-op rationale\\n- scope\\n- target asset\\n- evidence summary\\n- whether this is ready for evolution\\n"}'
 ) as Record<string, string>;

package/src/doctor.ts

@@ -476,7 +476,12 @@ async function repairCanonicalGlobalDocs(args: {
   home: string;
   rootDir: string;
 }): Promise<{ changed: boolean; backupPath?: string }> {
-  const inspected = await inspectCanonicalGlobalDocs(args.rootDir);
+  if (projectRootFromAiRoot(args.rootDir, args.home)) {
+    return { changed: false };
+  }
+  const inspected = await inspectCanonicalGlobalDocs(args.rootDir, {
+    projectRoot: null,
+  });
   if (!(inspected.exists && !inspected.valid)) {
     return { changed: false };
   }
@@ -494,13 +499,13 @@ async function repairCanonicalGlobalDocs(args: {
   await copyFile(targetPath, backupPath);
   await mkdir(dirname(targetPath), { recursive: true });
   await writeFile(targetPath, await readFile(sourcePath, "utf8"), "utf8");
-  await copyMissingBuiltinOperatingModelSnippets(args.rootDir);
+  await repairBuiltinOperatingModelSnippets(args.rootDir);
   await ensureAiIndexPath({ homeDir: args.home, rootDir: args.rootDir });
   await ensureAiGraphPath({ homeDir: args.home, rootDir: args.rootDir });
   return { changed: true, backupPath };
 }
 
-async function copyMissingBuiltinOperatingModelSnippets(
+async function repairBuiltinOperatingModelSnippets(
   rootDir: string
 ): Promise<void> {
   const relPaths = [
@@ -515,7 +520,10 @@ async function copyMissingBuiltinOperatingModelSnippets(
   for (const relPath of relPaths) {
     const sourcePath = join(sourceRoot, relPath);
     const targetPath = join(rootDir, relPath);
-    if (await pathExists(targetPath)) {
+    const existing = (await pathExists(targetPath))
+      ? await readFile(targetPath, "utf8")
+      : null;
+    if (existing !== null && existing.trim().length > 0) {
       continue;
     }
     await mkdir(dirname(targetPath), { recursive: true });
@@ -601,7 +609,10 @@ const UNRESOLVED_REFS_TEMPLATE_RE = /\$\{refs\.([A-Za-z0-9_.-]+)\}/g;
 const FCLTY_BLOCK_RE =
   /<!--\s*fclty:([^>]+?)\s*-->([\s\S]*?)<!--\s*\/fclty:\1\s*-->/g;
 
-async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
+async function inspectCanonicalGlobalDocs(
+  rootDir: string,
+  opts: { projectRoot?: string | null } = {}
+): Promise<{
   exists: boolean;
   valid: boolean;
   issues: DoctorIssue[];
@@ -613,6 +624,12 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
 
   const text = await readFile(pathValue, "utf8");
   const issues: DoctorIssue[] = [];
+  const refreshCommand = opts.projectRoot
+    ? "fclt templates init project-ai --force"
+    : "fclt templates init operating-model --global --force";
+  const docLabel = opts.projectRoot
+    ? "project AGENTS.global.md"
+    : "AGENTS.global.md";
   const withSnippets = await renderSnippetText({
     text,
     filePath: pathValue,
@@ -623,7 +640,7 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
       severity: "warning",
       code: "canonical-global-docs-render-error",
       message: error,
-      fix: "Review AGENTS.global.md snippet markers or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+      fix: `Review ${docLabel} snippet markers or refresh the selected capability root with \`${refreshCommand}\`.`,
     });
   }
   const rendered = await renderCanonicalText(withSnippets.text, {
@@ -636,9 +653,8 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
     issues.push({
       severity: "warning",
       code: "canonical-global-docs-unresolved-template",
-      message:
-        "Rendered AGENTS.global.md contains unresolved template references.",
-      fix: "Review AGENTS.global.md refs or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+      message: `Rendered ${docLabel} contains unresolved template references.`,
+      fix: `Review ${docLabel} refs or refresh the selected capability root with \`${refreshCommand}\`.`,
     });
   }
 
@@ -654,8 +670,8 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
     issues.push({
       severity: "warning",
       code: "canonical-global-docs-empty-managed-sections",
-      message: `Rendered AGENTS.global.md has empty fclty managed sections: ${emptySections.join(", ")}.`,
-      fix: "Add the missing snippets or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+      message: `Rendered ${docLabel} has empty fclty managed sections: ${emptySections.join(", ")}.`,
+      fix: `Add the missing snippets or refresh the selected capability root with \`${refreshCommand}\`.`,
     });
   }
 
@@ -976,7 +992,7 @@ export async function buildDoctorReport(opts?: {
     pathExists(generatedGraph),
     pathExists(writebackReviewDir),
     pathExists(evolutionReviewDir),
-    inspectCanonicalGlobalDocs(rootDir),
+    inspectCanonicalGlobalDocs(rootDir, { projectRoot }),
     inspectCanonicalTemplateRefs(rootDir),
     planProjectSyncPolicyRepair({ home, rootDir }),
   ]);
@@ -1019,9 +1035,15 @@ export async function buildDoctorReport(opts?: {
   }
   if (canonicalGlobalDocs.exists && !canonicalGlobalDocs.valid) {
     actions.push({
-      id: "refresh-global-operating-model",
-      label: "Refresh global operating model",
-      command: "fclt templates init operating-model --global --force",
+      id: projectRoot
+        ? "refresh-project-operating-model"
+        : "refresh-global-operating-model",
+      label: projectRoot
+        ? "Refresh project operating model"
+        : "Refresh global operating model",
+      command: projectRoot
+        ? "fclt templates init project-ai --force"
+        : "fclt templates init operating-model --global --force",
       risk: "canonical_write",
     });
   }
@@ -1369,7 +1391,9 @@ export async function doctorCommand(argv: string[]) {
         `Project sync is still implicit for managed tools (${projectSyncRepairTools.join(", ")}). Run \`fclt doctor --repair\` to write explicit [project_sync.<tool>] entries.`
       );
     }
-    const canonicalGlobalDocs = await inspectCanonicalGlobalDocs(rootDir);
+    const canonicalGlobalDocs = await inspectCanonicalGlobalDocs(rootDir, {
+      projectRoot: projectRootFromAiRoot(rootDir, home),
+    });
     if (canonicalGlobalDocs.exists && !canonicalGlobalDocs.valid) {
       for (const issue of canonicalGlobalDocs.issues) {
         console.log(`${issue.message} ${issue.fix ?? ""}`.trim());

package/src/global-docs.ts

@@ -6,7 +6,7 @@ import {
   facultBuiltinAgentsGlobalSourcePath,
   facultBuiltinPackRoot,
 } from "./builtin";
-import { projectRootFromAiRoot } from "./paths";
+import { pathIsInsideOrEqual, projectRootFromAiRoot } from "./paths";
 import { projectSyncAllowsToolSurface } from "./project-sync";
 import { renderSnippetText } from "./snippets";
 
@@ -233,7 +233,7 @@ async function renderSourceTarget(args: {
 }): Promise<string> {
   const raw = await Bun.file(args.sourcePath).text();
   const builtinRoot = facultBuiltinPackRoot();
-  const sourceRoot = args.sourcePath.startsWith(`${builtinRoot}/`)
+  const sourceRoot = pathIsInsideOrEqual(args.sourcePath, builtinRoot)
     ? builtinRoot
     : args.rootDir;
   const withSnippets = await renderSnippetText({

package/src/manage.ts

@@ -48,6 +48,7 @@ import {
   facultMachineStateDir,
   facultRootDir,
   legacyFacultStateDirForRoot,
+  pathIsInsideOrEqual,
   projectRootFromAiRoot,
 } from "./paths";
 import { loadProjectToolSyncPolicy } from "./project-sync";
@@ -289,8 +290,8 @@ async function isGeneratedOnlyProjectRoot(args: {
 function renderedSourceKindForPath(
   sourcePath: string
 ): ManagedRenderedTargetState["sourceKind"] {
-  return sourcePath.startsWith(facultBuiltinPackRoot()) ||
-    sourcePath.startsWith(facultBuiltinCodexPluginRoot())
+  return pathIsInsideOrEqual(sourcePath, facultBuiltinPackRoot()) ||
+    pathIsInsideOrEqual(sourcePath, facultBuiltinCodexPluginRoot())
     ? "builtin"
     : "canonical";
 }

package/src/paths.ts

@@ -1,9 +1,19 @@
 import { createHash } from "node:crypto";
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  win32,
+} from "node:path";
 import { parseJsonLenient } from "./util/json";
 
+const WINDOWS_ABSOLUTE_PATH_RE = /^[A-Za-z]:[\\/]/;
+
 export interface FacultConfig {
   /**
    * Override the canonical root directory.
@@ -88,6 +98,41 @@ export function preferredGlobalAiRoot(home: string = defaultHomeDir()): string {
   return join(home, ".ai");
 }
 
+function looksLikeWindowsAbsolutePath(pathValue: string): boolean {
+  return (
+    WINDOWS_ABSOLUTE_PATH_RE.test(pathValue) || pathValue.startsWith("\\\\")
+  );
+}
+
+function relativePathIsInsideOrEqual(args: {
+  rel: string;
+  isAbsolutePath: (pathValue: string) => boolean;
+}): boolean {
+  const { isAbsolutePath, rel } = args;
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolutePath(rel));
+}
+
+export function pathIsInsideOrEqual(
+  pathValue: string,
+  rootDir: string
+): boolean {
+  if (
+    looksLikeWindowsAbsolutePath(pathValue) &&
+    looksLikeWindowsAbsolutePath(rootDir)
+  ) {
+    return relativePathIsInsideOrEqual({
+      isAbsolutePath: win32.isAbsolute,
+      rel: win32.relative(rootDir, pathValue),
+    });
+  }
+
+  const rel = relative(rootDir, pathValue);
+  return relativePathIsInsideOrEqual({
+    isAbsolutePath: isAbsolute,
+    rel,
+  });
+}
+
 export function preferredGlobalFacultStateDir(
   home: string = defaultHomeDir()
 ): string {

package/src/self-update.ts

@@ -195,9 +195,6 @@ async function activeFcltUsesMiseNpmFacult(): Promise<boolean> {
   if (looksLikeMiseNpmFacultExecutable(fcltPath ?? "")) {
     return true;
   }
-  if (await miseHasCurrentFacultTool()) {
-    return true;
-  }
   if (!looksLikeMiseShim(fcltPath)) {
     return false;
   }
@@ -218,20 +215,21 @@ async function activeFcltUsesMiseNpmFacult(): Promise<boolean> {
   return looksLikeMiseNpmFacultExecutable(stdout.trim());
 }
 
-async function miseHasCurrentFacultTool(): Promise<boolean> {
-  const proc = Bun.spawn({
-    cmd: ["mise", "current", `npm:${PACKAGE_NAME}`],
-    stdin: "ignore",
-    stdout: "ignore",
-    stderr: "ignore",
-    env: process.env,
-  });
-  return (await proc.exited) === 0;
+export function buildCommandLookupFallback(
+  command: string,
+  platform: NodeJS.Platform = process.platform
+): string[] {
+  if (platform === "win32") {
+    return ["where.exe", command];
+  }
+  const quoted = `'${command.replaceAll("'", "'\\''")}'`;
+  return ["sh", "-lc", `command -v ${quoted}`];
 }
 
 async function resolveCommandPath(command: string): Promise<string | null> {
+  const cmd = buildCommandLookupFallback(command);
   const proc = Bun.spawn({
-    cmd: ["sh", "-lc", `command -v ${command}`],
+    cmd,
     stdin: "ignore",
     stdout: "pipe",
     stderr: "ignore",
@@ -247,6 +245,17 @@ async function resolveCommandPath(command: string): Promise<string | null> {
   return stdout.trim() || null;
 }
 
+export function looksLikeMiseNpmFacultExecutableForVersion(
+  executablePath: string,
+  version: string
+): boolean {
+  const normalized = executablePath.split("\\").join(sep);
+  return (
+    looksLikeMiseNpmFacultExecutable(normalized) &&
+    normalized.includes(`${sep}npm-facult${sep}${version}${sep}`)
+  );
+}
+
 function resolvePlatformTarget(): {
   platform: string;
   arch: string;
@@ -516,17 +525,38 @@ async function assertActiveFcltVersion(
   expectedVersion: string,
   packageManager: PackageManager
 ): Promise<void> {
-  const cmd =
-    packageManager === "mise"
-      ? [
-          "mise",
-          "exec",
-          `npm:${PACKAGE_NAME}@${expectedVersion}`,
-          "--",
-          "fclt",
-          "--version",
-        ]
-      : ["fclt", "--version"];
+  let cmd = ["fclt", "--version"];
+  if (packageManager === "mise") {
+    const which = Bun.spawn({
+      cmd: ["mise", "which", "fclt"],
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env,
+    });
+    const [whichStdout, whichStderr, whichCode] = await Promise.all([
+      new Response(which.stdout).text(),
+      new Response(which.stderr).text(),
+      which.exited,
+    ]);
+    const resolvedPath = whichStdout.trim();
+    if (whichCode !== 0) {
+      throw new Error(
+        `Updated package, but could not verify active mise fclt path: ${whichStderr.trim()}`
+      );
+    }
+    if (
+      !looksLikeMiseNpmFacultExecutableForVersion(resolvedPath, expectedVersion)
+    ) {
+      throw new Error(
+        [
+          `Updated package to ${expectedVersion}, but mise resolves fclt to ${resolvedPath || "nothing"}.`,
+          "Run `mise which fclt` and `mise current npm:facult` to inspect the active tool selection.",
+        ].join("\n")
+      );
+    }
+    cmd = [resolvedPath, "--version"];
+  }
   const proc = Bun.spawn({
     cmd,
     stdin: "ignore",