facult 2.13.5 → 2.14.0

package/src/doctor.ts

@@ -15,6 +15,7 @@ import {
 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { renderCanonicalText } from "./agents";
 import {
   ensureAiGraphPath,
   ensureAiIndexPath,
@@ -41,6 +42,7 @@ import {
   loadConfiguredProjectSyncTools,
   writeProjectSyncPolicy,
 } from "./project-sync";
+import { renderSnippetText } from "./snippets";
 import { packageVersion } from "./status";
 
 const TOML_FILE_SUFFIX_RE = /\.toml$/;
@@ -104,6 +106,9 @@ export interface DoctorReport {
     evolutionReviewDirExists: boolean;
     canonicalGlobalDocsValid: boolean;
     canonicalGlobalDocsIssueCodes: string[];
+    canonicalTemplateRefsValid: boolean;
+    canonicalTemplateRefsIssueCodes: string[];
+    canonicalTemplateRefsIssuePaths: string[];
     projectSyncRepairNeeded: boolean;
     projectSyncRepairTools: string[];
   };
@@ -446,6 +451,24 @@ async function repairLegacyCodexAuthoringLayout(args: {
   return { changed, conflicts };
 }
 
+interface CanonicalTemplateIssue {
+  path: string;
+  relPath: string;
+  code: string;
+  message: string;
+}
+
+interface CanonicalTemplateRefsInspection {
+  valid: boolean;
+  issues: CanonicalTemplateIssue[];
+}
+
+interface CanonicalTemplateRefsRepair {
+  changed: boolean;
+  repairedPaths: string[];
+  backupPaths: string[];
+}
+
 async function repairCanonicalGlobalDocs(args: {
   home: string;
   rootDir: string;
@@ -468,11 +491,35 @@ 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 ensureAiIndexPath({ homeDir: args.home, rootDir: args.rootDir });
   await ensureAiGraphPath({ homeDir: args.home, rootDir: args.rootDir });
   return { changed: true, backupPath };
 }
 
+async function copyMissingBuiltinOperatingModelSnippets(
+  rootDir: string
+): Promise<void> {
+  const relPaths = [
+    "snippets/global/baseline.md",
+    "snippets/global/core/work-units.md",
+    "snippets/global/core/feedback-loops.md",
+    "snippets/global/core/verification.md",
+    "snippets/global/core/writeback.md",
+  ];
+  const sourceRoot = facultBuiltinPackRoot();
+
+  for (const relPath of relPaths) {
+    const sourcePath = join(sourceRoot, relPath);
+    const targetPath = join(rootDir, relPath);
+    if (await pathExists(targetPath)) {
+      continue;
+    }
+    await mkdir(dirname(targetPath), { recursive: true });
+    await copyFile(sourcePath, targetPath);
+  }
+}
+
 async function listProjectSkillNames(rootDir: string): Promise<string[]> {
   const skillsDir = join(rootDir, "skills");
   const entries = await readdir(skillsDir, { withFileTypes: true }).catch(
@@ -547,6 +594,7 @@ async function hasProjectGlobalDocs(rootDir: string): Promise<boolean> {
 }
 
 const UNRESOLVED_TEMPLATE_REF_RE = /\$\{[^}\n]+\}/g;
+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;
 
@@ -562,19 +610,37 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
 
   const text = await readFile(pathValue, "utf8");
   const issues: DoctorIssue[] = [];
-  const unresolvedRefs = new Set(text.match(UNRESOLVED_TEMPLATE_REF_RE) ?? []);
+  const withSnippets = await renderSnippetText({
+    text,
+    filePath: pathValue,
+    rootDir,
+  });
+  for (const error of withSnippets.errors) {
+    issues.push({
+      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`.",
+    });
+  }
+  const rendered = await renderCanonicalText(withSnippets.text, {
+    rootDir,
+  });
+  const unresolvedRefs = new Set(
+    rendered.match(UNRESOLVED_TEMPLATE_REF_RE) ?? []
+  );
   if (unresolvedRefs.size > 0) {
     issues.push({
       severity: "warning",
       code: "canonical-global-docs-unresolved-template",
       message:
-        "Canonical AGENTS.global.md contains unresolved template references.",
-      fix: "Review the file or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+        "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`.",
     });
   }
 
   const emptySections: string[] = [];
-  for (const match of text.matchAll(FCLTY_BLOCK_RE)) {
+  for (const match of rendered.matchAll(FCLTY_BLOCK_RE)) {
     const key = match[1]?.trim();
     const body = match[2]?.trim();
     if (key && !body) {
@@ -585,8 +651,8 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
     issues.push({
       severity: "warning",
       code: "canonical-global-docs-empty-managed-sections",
-      message: `Canonical AGENTS.global.md has empty fclty managed sections: ${emptySections.join(", ")}.`,
-      fix: "Review the file or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+      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`.",
     });
   }
 
@@ -597,6 +663,125 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
   };
 }
 
+const CANONICAL_TEMPLATE_REF_DIRS = ["instructions"] as const;
+
+function canonicalRefValues(rootDir: string): Record<string, string> {
+  return {
+    evolution: join(rootDir, "instructions", "EVOLUTION.md"),
+    feedback_loops: join(rootDir, "instructions", "FEEDBACK_LOOPS.md"),
+    integration: join(rootDir, "instructions", "INTEGRATION.md"),
+    learning_writeback: join(
+      rootDir,
+      "instructions",
+      "LEARNING_AND_WRITEBACK.md"
+    ),
+    project_capability: join(rootDir, "instructions", "PROJECT_CAPABILITY.md"),
+    verification: join(rootDir, "instructions", "VERIFICATION.md"),
+    work_units: join(rootDir, "instructions", "WORK_UNITS.md"),
+  };
+}
+
+function resolveKnownCanonicalRefs(text: string, rootDir: string): string {
+  const refs = canonicalRefValues(rootDir);
+  return text.replace(UNRESOLVED_REFS_TEMPLATE_RE, (match, key: string) => {
+    return refs[key] ?? match;
+  });
+}
+
+async function listCanonicalMarkdownFiles(rootDir: string): Promise<string[]> {
+  const out: string[] = [];
+
+  async function visit(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(
+      () => [] as import("node:fs").Dirent[]
+    );
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+      const pathValue = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(pathValue);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        out.push(pathValue);
+      }
+    }
+  }
+
+  for (const relDir of CANONICAL_TEMPLATE_REF_DIRS) {
+    await visit(join(rootDir, relDir));
+  }
+  return out.sort((a, b) => a.localeCompare(b));
+}
+
+function relPathFromRoot(rootDir: string, pathValue: string): string {
+  return pathValue.startsWith(`${rootDir}/`)
+    ? pathValue.slice(rootDir.length + 1)
+    : pathValue;
+}
+
+async function inspectCanonicalTemplateRefs(
+  rootDir: string
+): Promise<CanonicalTemplateRefsInspection> {
+  const files = await listCanonicalMarkdownFiles(rootDir);
+  const issues: CanonicalTemplateIssue[] = [];
+
+  for (const pathValue of files) {
+    const text = await readFile(pathValue, "utf8");
+    const refs = new Set(text.match(UNRESOLVED_REFS_TEMPLATE_RE) ?? []);
+    if (refs.size === 0) {
+      continue;
+    }
+    const relPath = relPathFromRoot(rootDir, pathValue);
+    issues.push({
+      path: pathValue,
+      relPath,
+      code: "canonical-source-unresolved-template-ref",
+      message: `${relPath} contains unresolved template refs: ${[...refs].join(", ")}.`,
+    });
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+  };
+}
+
+async function repairCanonicalTemplateRefs(
+  rootDir: string
+): Promise<CanonicalTemplateRefsRepair> {
+  const files = await listCanonicalMarkdownFiles(rootDir);
+  const repairedPaths: string[] = [];
+  const backupPaths: string[] = [];
+
+  for (const pathValue of files) {
+    const before = await readFile(pathValue, "utf8");
+    const after = resolveKnownCanonicalRefs(before, rootDir);
+    if (after === before) {
+      continue;
+    }
+    const relPath = relPathFromRoot(rootDir, pathValue);
+    const backupPath = join(
+      rootDir,
+      ".facult",
+      "backups",
+      "doctor",
+      `${relPath.replaceAll("/", "__")}.${timestampForBackup()}`
+    );
+    await mkdir(dirname(backupPath), { recursive: true });
+    await copyFile(pathValue, backupPath);
+    await writeFile(pathValue, after, "utf8");
+    repairedPaths.push(relPath);
+    backupPaths.push(backupPath);
+  }
+
+  return {
+    changed: repairedPaths.length > 0,
+    repairedPaths,
+    backupPaths,
+  };
+}
+
 async function hasProjectToolRules(
   rootDir: string,
   tool: string
@@ -778,6 +963,7 @@ export async function buildDoctorReport(opts?: {
     writebackReviewDirExists,
     evolutionReviewDirExists,
     canonicalGlobalDocs,
+    canonicalTemplateRefs,
     projectSyncPlan,
   ] = await Promise.all([
     pathExists(rootDir),
@@ -788,6 +974,7 @@ export async function buildDoctorReport(opts?: {
     pathExists(writebackReviewDir),
     pathExists(evolutionReviewDir),
     inspectCanonicalGlobalDocs(rootDir),
+    inspectCanonicalTemplateRefs(rootDir),
     planProjectSyncPolicyRepair({ home, rootDir }),
   ]);
 
@@ -836,6 +1023,23 @@ export async function buildDoctorReport(opts?: {
     });
   }
 
+  for (const issue of canonicalTemplateRefs.issues) {
+    issues.push({
+      severity: "warning",
+      code: issue.code,
+      message: issue.message,
+      fix: "Run fclt doctor --repair to resolve known refs into concrete paths, then review any remaining placeholders.",
+    });
+  }
+  if (!canonicalTemplateRefs.valid) {
+    actions.push({
+      id: "repair-canonical-template-refs",
+      label: "Repair unresolved canonical template refs",
+      command: "fclt doctor --repair",
+      risk: "canonical_write",
+    });
+  }
+
   if (generatedOnlyProjectRoot) {
     issues.push({
       severity: "error",
@@ -927,7 +1131,7 @@ export async function buildDoctorReport(opts?: {
     state = "project_generated_only";
   } else if (!(rootExists && canonicalSourceExists)) {
     state = "uninitialized";
-  } else if (!canonicalGlobalDocs.valid) {
+  } else if (!(canonicalGlobalDocs.valid && canonicalTemplateRefs.valid)) {
     state = "canonical_source_attention";
   } else if (!(writebackReviewDirExists && evolutionReviewDirExists)) {
     state = "partial_global_config";
@@ -971,6 +1175,13 @@ export async function buildDoctorReport(opts?: {
       canonicalGlobalDocsIssueCodes: canonicalGlobalDocs.issues.map(
         (issue) => issue.code
       ),
+      canonicalTemplateRefsValid: canonicalTemplateRefs.valid,
+      canonicalTemplateRefsIssueCodes: canonicalTemplateRefs.issues.map(
+        (issue) => issue.code
+      ),
+      canonicalTemplateRefsIssuePaths: canonicalTemplateRefs.issues.map(
+        (issue) => issue.relPath
+      ),
       projectSyncRepairNeeded: projectSyncPlan.needed,
       projectSyncRepairTools,
     },
@@ -1029,6 +1240,7 @@ export async function doctorCommand(argv: string[]) {
     let codexAuthoringConflicts: string[] = [];
     let canonicalGlobalDocsRepaired = false;
     let canonicalGlobalDocsBackupPath: string | undefined;
+    let canonicalTemplateRefsRepair: CanonicalTemplateRefsRepair | undefined;
     let reviewArtifactsRefreshed:
       | {
           writebackCount: number;
@@ -1061,6 +1273,7 @@ export async function doctorCommand(argv: string[]) {
       });
       canonicalGlobalDocsRepaired = globalDocsRepair.changed;
       canonicalGlobalDocsBackupPath = globalDocsRepair.backupPath;
+      canonicalTemplateRefsRepair = await repairCanonicalTemplateRefs(rootDir);
       const { refreshAiReviewArtifacts } = await import("./ai");
       reviewArtifactsRefreshed = await refreshAiReviewArtifacts({
         homeDir: home,
@@ -1132,6 +1345,12 @@ export async function doctorCommand(argv: string[]) {
         `Repaired canonical AGENTS.global.md from the built-in operating model. Backup: ${canonicalGlobalDocsBackupPath}`
       );
     }
+    if (canonicalTemplateRefsRepair?.changed) {
+      console.log("Resolved canonical template refs in:");
+      for (const repairedPath of canonicalTemplateRefsRepair.repairedPaths) {
+        console.log(`- ${repairedPath}`);
+      }
+    }
     if (reviewArtifactsRefreshed) {
       console.log(
         `Refreshed AI review artifacts: ${reviewArtifactsRefreshed.writebackCount} writebacks in ${reviewArtifactsRefreshed.writebackReviewDir}, ${reviewArtifactsRefreshed.proposalCount} proposals in ${reviewArtifactsRefreshed.evolutionReviewDir}.`
@@ -1157,6 +1376,18 @@ export async function doctorCommand(argv: string[]) {
         return;
       }
     }
+    const canonicalTemplateRefs = await inspectCanonicalTemplateRefs(rootDir);
+    if (!canonicalTemplateRefs.valid) {
+      for (const issue of canonicalTemplateRefs.issues) {
+        console.log(
+          `${issue.message} Run \`fclt doctor --repair\` to resolve known refs into concrete paths, then review any remaining placeholders.`
+        );
+      }
+      if (!repair) {
+        process.exitCode = 1;
+        return;
+      }
+    }
     if (await isGeneratedOnlyProjectRoot({ home, rootDir })) {
       console.log(
         "Project .ai root contains generated state only. Canonical project source is missing, so managed project sync should be treated as unsafe until source is initialized, restored, or management is detached."

package/src/global-docs.ts

@@ -228,18 +228,25 @@ async function renderSourceTarget(args: {
   tool: string;
 }): Promise<string> {
   const raw = await Bun.file(args.sourcePath).text();
+  const builtinRoot = facultBuiltinPackRoot();
+  const sourceRoot = args.sourcePath.startsWith(`${builtinRoot}/`)
+    ? builtinRoot
+    : args.rootDir;
   const withSnippets = await renderSnippetText({
     text: raw,
     filePath: args.sourcePath,
-    rootDir: args.rootDir,
+    rootDir: sourceRoot,
   });
   if (withSnippets.errors.length) {
     throw new Error(withSnippets.errors.join("\n"));
   }
   return await renderCanonicalText(withSnippets.text, {
     homeDir: args.homeDir,
-    rootDir: args.rootDir,
-    projectRoot: projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined,
+    rootDir: sourceRoot,
+    projectRoot:
+      sourceRoot === args.rootDir
+        ? (projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined)
+        : undefined,
     targetTool: args.tool,
     targetPath: args.targetPath,
   });

package/src/remote.ts

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { mkdir, readdir, readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import {
@@ -130,6 +131,7 @@ interface InstallResult {
   sourceTrustLevel: SourceTrustLevel;
   dryRun: boolean;
   changedPaths: string[];
+  skippedPaths?: string[];
 }
 
 interface UpdateCheckResult {
@@ -394,17 +396,12 @@ Ship reliable changes quickly while keeping behavior predictable.
       type: "snippet",
       title: "Snippet Template",
       description:
-        "Reusable snippet block template for coding standards and communication style.",
+        "Reusable snippet block template for a compact quality checklist.",
       version: "1.0.0",
       tags: ["template", "dx", "snippet"],
       snippet: {
-        marker: "team/codingstyle",
-        content: `## Coding Style
-- Prefer explicit, descriptive names over abbreviations.
-- Keep functions focused and side-effect boundaries obvious.
-- Add tests when behavior changes.
-
-## Review Checklist
+        marker: "team/quality-checklist",
+        content: `## Quality Checklist
 - Is behavior correct for edge cases?
 - Are failure modes clear and actionable?
 - Is the change minimal for the goal?
@@ -1303,17 +1300,64 @@ async function listFilesRecursive(rootDir: string): Promise<string[]> {
   return out.sort();
 }
 
+interface BuiltinPackManifest {
+  version: 1;
+  pack: string;
+  updatedAt: string;
+  files: Record<string, { sha256: string }>;
+}
+
+function sha256Text(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function builtinPackManifestPath(rootDir: string): string {
+  return join(rootDir, ".facult", "packs", "facult-operating-model.json");
+}
+
+async function readBuiltinPackManifest(
+  rootDir: string
+): Promise<BuiltinPackManifest | null> {
+  const pathValue = builtinPackManifestPath(rootDir);
+  if (!(await pathExists(pathValue))) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(await Bun.file(pathValue).text());
+    if (
+      parsed?.version === 1 &&
+      parsed.pack === "facult-operating-model" &&
+      isPlainObject(parsed.files)
+    ) {
+      return parsed as BuiltinPackManifest;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function serializeBuiltinPackManifest(manifest: BuiltinPackManifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
 async function scaffoldBuiltinOperatingModelPack(args: {
   rootDir: string;
   homeDir?: string;
   dryRun?: boolean;
   force?: boolean;
+  update?: boolean;
   installedAs?: string;
 }): Promise<InstallResult> {
   const rootDir = resolve(args.rootDir);
   const packRoot = facultBuiltinPackRoot("facult-operating-model");
   const files = await listFilesRecursive(packRoot);
   const changedPaths: string[] = [];
+  const skippedPaths: string[] = [];
+  const existingManifest = await readBuiltinPackManifest(rootDir);
+  const manifestFiles: BuiltinPackManifest["files"] = {
+    ...(existingManifest?.files ?? {}),
+  };
 
   for (const sourcePath of files) {
     const relPath = relative(packRoot, sourcePath);
@@ -1321,23 +1365,90 @@ async function scaffoldBuiltinOperatingModelPack(args: {
       continue;
     }
     const targetPath = join(rootDir, relPath);
+    const sourceText = await Bun.file(sourcePath).text();
+    const sourceHash = sha256Text(sourceText);
     const exists = await pathExists(targetPath);
-    if (exists && !args.force) {
+    let shouldWrite = !exists || Boolean(args.force);
+
+    if (exists && !shouldWrite) {
+      const targetText = await Bun.file(targetPath).text();
+      const targetHash = sha256Text(targetText);
+      if (targetHash === sourceHash) {
+        manifestFiles[relPath] = { sha256: sourceHash };
+      } else if (
+        args.update &&
+        existingManifest?.files[relPath]?.sha256 === targetHash
+      ) {
+        shouldWrite = true;
+      } else if (args.update) {
+        skippedPaths.push(targetPath);
+      }
+    }
+
+    if (!shouldWrite) {
       continue;
     }
     changedPaths.push(targetPath);
+    manifestFiles[relPath] = { sha256: sourceHash };
     if (!args.dryRun) {
       await mkdir(dirname(targetPath), { recursive: true });
-      await Bun.write(targetPath, await Bun.file(sourcePath).text());
+      await Bun.write(targetPath, sourceText);
     }
   }
 
   const configPath = join(rootDir, "config.toml");
-  if (!(await pathExists(configPath)) || args.force) {
+  const configRelPath = "config.toml";
+  const configText = "version = 1\n";
+  const configHash = sha256Text(configText);
+  const configExists = await pathExists(configPath);
+  let shouldWriteConfig = !configExists || Boolean(args.force);
+  if (configExists && !shouldWriteConfig) {
+    const targetText = await Bun.file(configPath).text();
+    const targetHash = sha256Text(targetText);
+    if (targetHash === configHash) {
+      manifestFiles[configRelPath] = { sha256: configHash };
+    } else if (
+      args.update &&
+      existingManifest?.files[configRelPath]?.sha256 === targetHash
+    ) {
+      shouldWriteConfig = true;
+    } else if (args.update) {
+      skippedPaths.push(configPath);
+    }
+  }
+  if (shouldWriteConfig) {
     changedPaths.push(configPath);
+    manifestFiles[configRelPath] = { sha256: configHash };
     if (!args.dryRun) {
       await mkdir(dirname(configPath), { recursive: true });
-      await Bun.write(configPath, "version = 1\n");
+      await Bun.write(configPath, configText);
+    }
+  }
+
+  const manifestPath = builtinPackManifestPath(rootDir);
+  const sortedManifestFiles = Object.fromEntries(
+    Object.entries(manifestFiles).sort(([a], [b]) => a.localeCompare(b))
+  );
+  const stableManifest = serializeBuiltinPackManifest({
+    version: 1,
+    pack: "facult-operating-model",
+    updatedAt: existingManifest?.updatedAt ?? "",
+    files: sortedManifestFiles,
+  });
+  const existingManifestText = (await pathExists(manifestPath))
+    ? await Bun.file(manifestPath).text()
+    : null;
+  if (existingManifestText !== stableManifest) {
+    const nextManifest = serializeBuiltinPackManifest({
+      version: 1,
+      pack: "facult-operating-model",
+      updatedAt: new Date().toISOString(),
+      files: sortedManifestFiles,
+    });
+    changedPaths.push(manifestPath);
+    if (!args.dryRun) {
+      await mkdir(dirname(manifestPath), { recursive: true });
+      await Bun.write(manifestPath, nextManifest);
     }
   }
 
@@ -1357,6 +1468,7 @@ async function scaffoldBuiltinOperatingModelPack(args: {
     sourceTrustLevel: "trusted",
     dryRun: Boolean(args.dryRun),
     changedPaths: uniqueSorted(changedPaths),
+    skippedPaths: uniqueSorted(skippedPaths),
   };
 }
 
@@ -1365,6 +1477,7 @@ async function scaffoldBuiltinProjectAiPack(args: {
   homeDir?: string;
   dryRun?: boolean;
   force?: boolean;
+  update?: boolean;
 }): Promise<InstallResult> {
   const cwd = resolve(args.cwd ?? process.cwd());
   return await scaffoldBuiltinOperatingModelPack({
@@ -1372,6 +1485,7 @@ async function scaffoldBuiltinProjectAiPack(args: {
     homeDir: args.homeDir,
     dryRun: args.dryRun,
     force: args.force,
+    update: args.update,
     installedAs: "project-ai",
   });
 }
@@ -2820,9 +2934,11 @@ function printTemplatesHelp() {
             ),
             renderCode("fclt templates init agents [--force] [--dry-run]"),
             renderCode(
-              "fclt templates init operating-model [--global|--project|--root PATH] [--force] [--dry-run]"
+              "fclt templates init operating-model [--global|--project|--root PATH] [--update] [--force] [--dry-run]"
+            ),
+            renderCode(
+              "fclt templates init project-ai [--update] [--force] [--dry-run]"
             ),
-            renderCode("fclt templates init project-ai [--force] [--dry-run]"),
             renderCode(
               "fclt templates init automation <template-id> [--scope global|project|wide] [--name <name>] [--project-root <path>] [--cwds <path1,path2>] [--rrule <RRULE>] [--status PAUSED|ACTIVE] [--yes] [--dry-run]"
             ),
@@ -3327,6 +3443,7 @@ export async function templatesCommand(
   }
   const dryRun = args.includes("--dry-run");
   const force = args.includes("--force");
+  const update = args.includes("--update");
   const json = args.includes("--json");
   const parsedArgs = parseTemplateInitArgs(args);
   const positional = parsedArgs.positional;
@@ -3338,6 +3455,7 @@ export async function templatesCommand(
         homeDir: ctx.homeDir,
         dryRun,
         force,
+        update,
       });
       if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -3353,6 +3471,14 @@ export async function templatesCommand(
               title: "Changed Paths",
               lines: renderBullets(result.changedPaths),
             },
+            ...(result.skippedPaths?.length
+              ? [
+                  {
+                    title: "Skipped Local Edits",
+                    lines: renderBullets(result.skippedPaths),
+                  },
+                ]
+              : []),
           ],
         })
       );
@@ -3383,6 +3509,7 @@ export async function templatesCommand(
         homeDir: ctx.homeDir,
         dryRun,
         force,
+        update,
       });
       if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -3398,6 +3525,14 @@ export async function templatesCommand(
               title: "Changed Paths",
               lines: renderBullets(result.changedPaths),
             },
+            ...(result.skippedPaths?.length
+              ? [
+                  {
+                    title: "Skipped Local Edits",
+                    lines: renderBullets(result.skippedPaths),
+                  },
+                ]
+              : []),
           ],
         })
       );

package/src/snippets-cli.ts

@@ -20,8 +20,8 @@ Usage:
   fclt snippets sync [--dry-run] [file...]
 
 Notes:
-  - <name> is the snippet marker name (e.g. codingstyle, global/codingstyle, myproject/context)
-  - Unscoped names (e.g. codingstyle) resolve to project snippet first (if in a git repo), then global.
+  - <name> is the snippet marker name (e.g. qualitychecklist, global/qualitychecklist, myproject/context)
+  - Unscoped names (e.g. qualitychecklist) resolve to project snippet first (if in a git repo), then global.
 `);
 }