@rely-ai/caliber 1.35.1 → 1.36.1

package/README.md

@@ -285,9 +285,9 @@ No API key? No problem. Caliber works with your existing AI tool subscription:
 | **Claude Code** (your seat) | `caliber config` → Claude Code | Inherited from Claude Code |
 | **Cursor** (your seat) | `caliber config` → Cursor | Inherited from Cursor |
 | **Anthropic** | `export ANTHROPIC_API_KEY=sk-ant-...` | `claude-sonnet-4-6` |
-| **OpenAI** | `export OPENAI_API_KEY=sk-...` | `gpt-4.1` |
+| **OpenAI** | `export OPENAI_API_KEY=sk-...` | `gpt-5.4-mini` |
 | **Vertex AI** | `export VERTEX_PROJECT_ID=my-project` | `claude-sonnet-4-6` |
-| **Custom endpoint** | `OPENAI_API_KEY` + `OPENAI_BASE_URL` | `gpt-4.1` |
+| **Custom endpoint** | `OPENAI_API_KEY` + `OPENAI_BASE_URL` | `gpt-5.4-mini` |
 
 Override the model for any provider: `export CALIBER_MODEL=<model-name>` or use `caliber config`.
 

package/dist/bin.js

@@ -35,9 +35,9 @@ function getMaxPromptTokens() {
   return Math.max(MIN_PROMPT_TOKENS, Math.min(budget, MAX_PROMPT_TOKENS_CAP));
 }
 function loadConfig() {
-  const envConfig = resolveFromEnv();
-  if (envConfig) return envConfig;
-  return readConfigFile();
+  const fileConfig = readConfigFile();
+  if (fileConfig) return fileConfig;
+  return resolveFromEnv();
 }
 function resolveFromEnv() {
   if (process.env.ANTHROPIC_API_KEY) {
@@ -130,7 +130,7 @@ var init_config = __esm({
     DEFAULT_MODELS = {
       anthropic: "claude-sonnet-4-6",
       vertex: "claude-sonnet-4-6",
-      openai: "gpt-4.1",
+      openai: "gpt-5.4-mini",
       cursor: "sonnet-4.6",
       "claude-cli": "default"
     };
@@ -139,8 +139,7 @@ var init_config = __esm({
       "claude-opus-4-6": 2e5,
       "claude-haiku-4-5-20251001": 2e5,
       "claude-sonnet-4-5-20250514": 2e5,
-      "gpt-4.1": 1e6,
-      "gpt-4.1-mini": 1e6,
+      "gpt-5.4-mini": 1e6,
       "gpt-4o": 128e3,
       "gpt-4o-mini": 128e3,
       "sonnet-4.6": 2e5
@@ -152,7 +151,7 @@ var init_config = __esm({
     DEFAULT_FAST_MODELS = {
       anthropic: "claude-haiku-4-5-20251001",
       vertex: "claude-haiku-4-5-20251001",
-      openai: "gpt-4.1-mini",
+      openai: "gpt-5.4-mini",
       cursor: "gpt-5.3-codex-fast"
     };
   }
@@ -389,7 +388,10 @@ function getCursorSetupRule() {
 function stripManagedBlocks(content) {
   let result = content;
   for (const [start, end] of MANAGED_BLOCK_PAIRS) {
-    const regex = new RegExp(`\\n?${start.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`, "g");
+    const regex = new RegExp(
+      `\\n?${start.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`,
+      "g"
+    );
     result = result.replace(regex, "\n");
   }
   return result.replace(/\n{3,}/g, "\n\n").trim() + "\n";
@@ -401,7 +403,7 @@ var init_pre_commit_block = __esm({
     init_resolve_caliber();
     BLOCK_START = "<!-- caliber:managed:pre-commit -->";
     BLOCK_END = "<!-- /caliber:managed:pre-commit -->";
-    MANAGED_DOC_PATHS = "CLAUDE.md .claude/ .cursor/ .cursorrules .github/copilot-instructions.md .github/instructions/ AGENTS.md CALIBER_LEARNINGS.md";
+    MANAGED_DOC_PATHS = "CLAUDE.md .claude/ .cursor/ .cursorrules .github/copilot-instructions.md .github/instructions/ AGENTS.md CALIBER_LEARNINGS.md .agents/ .opencode/";
     CURSOR_RULE_FILENAME = "caliber-pre-commit.mdc";
     LEARNINGS_BLOCK_START = "<!-- caliber:managed:learnings -->";
     LEARNINGS_BLOCK_END = "<!-- /caliber:managed:learnings -->";
@@ -1100,10 +1102,21 @@ __export(lock_exports, {
 import fs39 from "fs";
 import path32 from "path";
 import os8 from "os";
+import crypto5 from "crypto";
+function buildLockPath() {
+  const cwd = process.cwd();
+  const hash = crypto5.createHash("md5").update(cwd).digest("hex").slice(0, 8);
+  return path32.join(os8.tmpdir(), `.caliber-${hash}.lock`);
+}
+function getLockFile() {
+  if (!_lockPath) _lockPath = buildLockPath();
+  return _lockPath;
+}
 function isCaliberRunning() {
   try {
-    if (!fs39.existsSync(LOCK_FILE)) return false;
-    const raw = fs39.readFileSync(LOCK_FILE, "utf-8").trim();
+    const lockFile = buildLockPath();
+    if (!fs39.existsSync(lockFile)) return false;
+    const raw = fs39.readFileSync(lockFile, "utf-8").trim();
     const { pid, ts } = JSON.parse(raw);
     if (Date.now() - ts > STALE_MS) return false;
     try {
@@ -1118,22 +1131,23 @@ function isCaliberRunning() {
 }
 function acquireLock() {
   try {
-    fs39.writeFileSync(LOCK_FILE, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+    fs39.writeFileSync(getLockFile(), JSON.stringify({ pid: process.pid, ts: Date.now() }));
   } catch {
   }
 }
 function releaseLock() {
   try {
-    if (fs39.existsSync(LOCK_FILE)) fs39.unlinkSync(LOCK_FILE);
+    const lockFile = getLockFile();
+    if (fs39.existsSync(lockFile)) fs39.unlinkSync(lockFile);
   } catch {
   }
 }
-var LOCK_FILE, STALE_MS;
+var STALE_MS, _lockPath;
 var init_lock = __esm({
   "src/lib/lock.ts"() {
     "use strict";
-    LOCK_FILE = path32.join(os8.tmpdir(), ".caliber.lock");
     STALE_MS = 10 * 60 * 1e3;
+    _lockPath = null;
   }
 });
 
@@ -1291,9 +1305,30 @@ var LEARNING_ROI_FILE = "roi-stats.json";
 var PERSONAL_LEARNINGS_FILE = path2.join(AUTH_DIR, "personal-learnings.md");
 var LEARNING_FINALIZE_LOG = "finalize.log";
 var LEARNING_LAST_ERROR_FILE = "last-error.json";
+var REFRESH_LAST_ERROR_FILE = path2.join(CALIBER_DIR, "last-refresh-error.json");
 var MIN_SESSIONS_FOR_COMPARISON = 3;
 
 // src/fingerprint/existing-config.ts
+function readSkillsFromDir(skillsDir) {
+  if (!fs2.existsSync(skillsDir)) return void 0;
+  try {
+    const skills = fs2.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).reduce((acc, entry) => {
+      const skillPath = path3.join(skillsDir, entry.name, "SKILL.md");
+      try {
+        acc.push({
+          name: entry.name,
+          filename: "SKILL.md",
+          content: fs2.readFileSync(skillPath, "utf-8")
+        });
+      } catch {
+      }
+      return acc;
+    }, []);
+    return skills.length > 0 ? skills : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function readExistingConfigs(dir) {
   const configs = {};
   const readmeMdPath = path3.join(dir, "README.md");
@@ -1324,7 +1359,10 @@ function readExistingConfigs(dir) {
         const entryPath = path3.join(skillsDir, entry);
         const skillMdPath = path3.join(entryPath, "SKILL.md");
         if (fs2.statSync(entryPath).isDirectory() && fs2.existsSync(skillMdPath)) {
-          skills.push({ filename: `${entry}/SKILL.md`, content: fs2.readFileSync(skillMdPath, "utf-8") });
+          skills.push({
+            filename: `${entry}/SKILL.md`,
+            content: fs2.readFileSync(skillMdPath, "utf-8")
+          });
         } else if (entry.endsWith(".md")) {
           skills.push({ filename: entry, content: fs2.readFileSync(entryPath, "utf-8") });
         }
@@ -1348,20 +1386,26 @@ function readExistingConfigs(dir) {
     } catch {
     }
   }
-  const cursorSkillsDir = path3.join(dir, ".cursor", "skills");
-  if (fs2.existsSync(cursorSkillsDir)) {
+  configs.cursorSkills = readSkillsFromDir(path3.join(dir, ".cursor", "skills"));
+  const copilotPath = path3.join(dir, ".github", "copilot-instructions.md");
+  if (fs2.existsSync(copilotPath)) {
+    configs.copilotInstructions = fs2.readFileSync(copilotPath, "utf-8");
+  }
+  const copilotInstructionsDir = path3.join(dir, ".github", "instructions");
+  if (fs2.existsSync(copilotInstructionsDir)) {
     try {
-      const slugs = fs2.readdirSync(cursorSkillsDir).filter((f) => {
-        return fs2.statSync(path3.join(cursorSkillsDir, f)).isDirectory();
-      });
-      configs.cursorSkills = slugs.filter((slug) => fs2.existsSync(path3.join(cursorSkillsDir, slug, "SKILL.md"))).map((name) => ({
-        name,
-        filename: "SKILL.md",
-        content: fs2.readFileSync(path3.join(cursorSkillsDir, name, "SKILL.md"), "utf-8")
-      }));
+      const files = fs2.readdirSync(copilotInstructionsDir).filter((f) => f.endsWith(".instructions.md"));
+      if (files.length > 0) {
+        configs.copilotInstructionFiles = files.map((f) => ({
+          filename: f,
+          content: fs2.readFileSync(path3.join(copilotInstructionsDir, f), "utf-8")
+        }));
+      }
     } catch {
     }
   }
+  configs.codexSkills = readSkillsFromDir(path3.join(dir, ".agents", "skills"));
+  configs.opencodeSkills = readSkillsFromDir(path3.join(dir, ".opencode", "skills"));
   const mcpJsonPath = path3.join(dir, ".mcp.json");
   if (fs2.existsSync(mcpJsonPath)) {
     try {
@@ -2791,13 +2835,7 @@ var KNOWN_MODELS = {
     "claude-opus-4-6@20250605",
     "claude-opus-4-1-20250620"
   ],
-  openai: [
-    "gpt-4.1",
-    "gpt-4.1-mini",
-    "gpt-4o",
-    "gpt-4o-mini",
-    "o3-mini"
-  ],
+  openai: ["gpt-5.4-mini", "gpt-4o", "gpt-4o-mini", "o3-mini"],
   cursor: ["auto", "composer-1.5"],
   "claude-cli": []
 };
@@ -2805,7 +2843,8 @@ function isModelNotAvailableError(error) {
   const msg = error.message.toLowerCase();
   const status = error.status;
   if (status === 404 && msg.includes("model")) return true;
-  if (msg.includes("model") && (msg.includes("not found") || msg.includes("not_found"))) return true;
+  if (msg.includes("model") && (msg.includes("not found") || msg.includes("not_found")))
+    return true;
   if (msg.includes("model") && msg.includes("not available")) return true;
   if (msg.includes("model") && msg.includes("does not exist")) return true;
   if (msg.includes("publisher model")) return true;
@@ -2831,12 +2870,18 @@ function filterRelevantModels(models, provider) {
 async function handleModelNotAvailable(failedModel, provider, config) {
   if (!process.stdin.isTTY) {
     console.error(
-      chalk.red(`Model "${failedModel}" is not available. Run \`${resolveCaliber()} config\` to select a different model.`)
+      chalk.red(
+        `Model "${failedModel}" is not available. Run \`${resolveCaliber()} config\` to select a different model.`
+      )
     );
     return null;
   }
-  console.log(chalk.yellow(`
-\u26A0  Model "${failedModel}" is not available on your ${config.provider} deployment.`));
+  console.log(
+    chalk.yellow(
+      `
+\u26A0  Model "${failedModel}" is not available on your ${config.provider} deployment.`
+    )
+  );
   let models = [];
   if (provider.listModels) {
     try {
@@ -2850,7 +2895,11 @@ async function handleModelNotAvailable(failedModel, provider, config) {
   }
   models = models.filter((m) => m !== failedModel);
   if (models.length === 0) {
-    console.log(chalk.red(`  No alternative models found. Run \`${resolveCaliber()} config\` to configure manually.`));
+    console.log(
+      chalk.red(
+        `  No alternative models found. Run \`${resolveCaliber()} config\` to configure manually.`
+      )
+    );
     return null;
   }
   console.log("");
@@ -3325,6 +3374,11 @@ Quality constraints (the output is scored deterministically):
 - ONLY reference file paths that exist in the provided file tree \u2014 do NOT invent paths
 - Preserve the existing structure (headings, bullet style, formatting)
 
+Cross-agent sync:
+- When a code change affects documentation, update ALL provided platform configs together.
+- A renamed command, moved file, or changed convention must be reflected in every config (CLAUDE.md, AGENTS.md, copilot instructions, skills across all platforms).
+- Cross-agent consistency is critical \u2014 all agents working on this repo must have the same, accurate context.
+
 Managed content:
 - Keep managed blocks (<!-- caliber:managed --> ... <!-- /caliber:managed -->) intact
 - Do NOT modify CALIBER_LEARNINGS.md \u2014 it is managed separately
@@ -3338,7 +3392,6 @@ Return a JSON object with this exact shape:
     "readmeMd": "<updated content or null>",
     "cursorrules": "<updated content or null>",
     "cursorRules": [{"filename": "name.mdc", "content": "..."}] or null,
-    "claudeSkills": [{"filename": "name.md", "content": "..."}] or null,
     "copilotInstructions": "<updated content or null>",
     "copilotInstructionFiles": [{"filename": "name.instructions.md", "content": "..."}] or null
   },
@@ -3930,7 +3983,7 @@ var STOP_HOOK_SCRIPT_CONTENT = `#!/bin/sh
 if grep -q "caliber" .git/hooks/pre-commit 2>/dev/null; then
   exit 0
 fi
-FLAG="/tmp/caliber-nudge-$(echo "$PWD" | shasum | cut -c1-8)"
+FLAG="/tmp/caliber-nudge-$(echo "$PWD" | (shasum 2>/dev/null || sha1sum 2>/dev/null || md5sum 2>/dev/null || cksum) | cut -c1-8)"
 find /tmp -maxdepth 1 -name "caliber-nudge-*" -mmin +120 -delete 2>/dev/null
 if [ -f "$FLAG" ]; then
   exit 0
@@ -3961,11 +4014,13 @@ function installStopHook() {
   }
   settings.hooks.Stop.push({
     matcher: "",
-    hooks: [{
-      type: "command",
-      command: STOP_HOOK_SCRIPT_PATH,
-      description: STOP_HOOK_DESCRIPTION
-    }]
+    hooks: [
+      {
+        type: "command",
+        command: STOP_HOOK_SCRIPT_PATH,
+        description: STOP_HOOK_DESCRIPTION
+      }
+    ]
   });
   writeSettings(settings);
   return { installed: true, alreadyInstalled: false };
@@ -3997,16 +4052,20 @@ function getPrecommitBlock() {
   const invoke = npx ? bin : `"${bin}"`;
   return `${PRECOMMIT_START}
 if ${guard}; then
+  mkdir -p .caliber
   echo "\\033[2mcaliber: refreshing docs...\\033[0m"
-  ${invoke} refresh 2>/dev/null || true
-  ${invoke} learn finalize 2>/dev/null || true
-  git diff --name-only -- CLAUDE.md .claude/ .cursor/ AGENTS.md CALIBER_LEARNINGS.md 2>/dev/null | xargs git add 2>/dev/null || true
+  ${invoke} refresh --quiet 2>.caliber/refresh-hook.log || true
+  ${invoke} learn finalize 2>>.caliber/refresh-hook.log || true
+  git diff --name-only -- CLAUDE.md .claude/ .cursor/ AGENTS.md CALIBER_LEARNINGS.md .github/ .agents/ .opencode/ 2>/dev/null | xargs git add 2>/dev/null || true
 fi
 ${PRECOMMIT_END}`;
 }
 function getGitHooksDir() {
   try {
-    const gitDir = execSync8("git rev-parse --git-dir", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const gitDir = execSync8("git rev-parse --git-dir", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
     return path10.join(gitDir, "hooks");
   } catch {
     return null;
@@ -5294,7 +5353,10 @@ import fs14 from "fs";
 import path14 from "path";
 function writeCodexConfig(config) {
   const written = [];
-  fs14.writeFileSync("AGENTS.md", appendLearningsBlock(appendPreCommitBlock(config.agentsMd)));
+  fs14.writeFileSync(
+    "AGENTS.md",
+    appendLearningsBlock(appendPreCommitBlock(config.agentsMd, "codex"))
+  );
   written.push("AGENTS.md");
   if (config.skills?.length) {
     for (const skill of config.skills) {
@@ -5323,7 +5385,10 @@ function writeGithubCopilotConfig(config) {
   const written = [];
   if (config.instructions) {
     fs15.mkdirSync(".github", { recursive: true });
-    fs15.writeFileSync(path15.join(".github", "copilot-instructions.md"), appendLearningsBlock(appendPreCommitBlock(config.instructions)));
+    fs15.writeFileSync(
+      path15.join(".github", "copilot-instructions.md"),
+      appendLearningsBlock(appendPreCommitBlock(config.instructions, "copilot"))
+    );
     written.push(".github/copilot-instructions.md");
   }
   if (config.instructionFiles?.length) {
@@ -5345,7 +5410,10 @@ import path17 from "path";
 function writeOpencodeConfig(config, agentsMdAlreadyWritten = false) {
   const written = [];
   if (!agentsMdAlreadyWritten) {
-    fs17.writeFileSync("AGENTS.md", appendLearningsBlock(appendPreCommitBlock(config.agentsMd)));
+    fs17.writeFileSync(
+      "AGENTS.md",
+      appendLearningsBlock(appendPreCommitBlock(config.agentsMd, "codex"))
+    );
     written.push("AGENTS.md");
   }
   if (config.skills?.length) {
@@ -6224,14 +6292,17 @@ function checkExistence(dir) {
   const opencodeSkills = countFiles(join3(dir, ".opencode", "skills"), /SKILL\.md$/);
   const skillCount = claudeSkills.length + codexSkills.length + opencodeSkills.length;
   const skillBase = skillCount >= 1 ? POINTS_SKILLS_EXIST : 0;
-  const skillBonus = Math.min((skillCount - 1) * POINTS_SKILLS_BONUS_PER_EXTRA, POINTS_SKILLS_BONUS_CAP);
+  const skillBonus = Math.min(
+    (skillCount - 1) * POINTS_SKILLS_BONUS_PER_EXTRA,
+    POINTS_SKILLS_BONUS_CAP
+  );
   const skillPoints = skillCount >= 1 ? skillBase + Math.max(0, skillBonus) : 0;
   const maxSkillPoints = POINTS_SKILLS_EXIST + POINTS_SKILLS_BONUS_CAP;
   checks.push({
     id: "skills_exist",
     name: "Skills configured",
     category: "existence",
-    maxPoints: maxSkillPoints,
+    maxPoints: skillCount >= 1 ? maxSkillPoints : 0,
     earnedPoints: Math.min(skillPoints, maxSkillPoints),
     passed: skillCount >= 1,
     detail: skillCount === 0 ? "No skills found" : `${skillCount} skill${skillCount === 1 ? "" : "s"} found`,
@@ -6264,7 +6335,7 @@ function checkExistence(dir) {
     id: "mcp_servers",
     name: "MCP servers configured",
     category: "existence",
-    maxPoints: POINTS_MCP_SERVERS,
+    maxPoints: mcp.count >= 1 ? POINTS_MCP_SERVERS : 0,
     earnedPoints: mcp.count >= 1 ? POINTS_MCP_SERVERS : 0,
     passed: mcp.count >= 1,
     detail: mcp.count > 0 ? `${mcp.count} server${mcp.count === 1 ? "" : "s"} in ${mcp.sources.join(", ")}` : "No MCP servers configured",
@@ -6799,7 +6870,11 @@ init_resolve_caliber();
 init_pre_commit_block();
 function hasPreCommitHook(dir) {
   try {
-    const gitDir = execSync12("git rev-parse --git-dir", { cwd: dir, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const gitDir = execSync12("git rev-parse --git-dir", {
+      cwd: dir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
     const hookPath = join7(gitDir, "hooks", "pre-commit");
     const content = readFileOrNull(hookPath);
     return content ? content.includes("caliber") : false;
@@ -6890,9 +6965,9 @@ function checkBonus(dir) {
     id: "open_skills_format",
     name: "Skills use OpenSkills format",
     category: "bonus",
-    maxPoints: POINTS_OPEN_SKILLS_FORMAT,
+    maxPoints: totalSkillFiles > 0 ? POINTS_OPEN_SKILLS_FORMAT : 0,
     earnedPoints: allOpenSkills ? POINTS_OPEN_SKILLS_FORMAT : 0,
-    passed: allOpenSkills,
+    passed: allOpenSkills || totalSkillFiles === 0,
     detail: totalSkillFiles === 0 ? "No skills to check" : allOpenSkills ? `All ${totalSkillFiles} skill${totalSkillFiles === 1 ? "" : "s"} use SKILL.md with frontmatter` : `${openSkillsCount}/${totalSkillFiles} use OpenSkills format`,
     suggestion: totalSkillFiles > 0 && !allOpenSkills ? "Migrate skills to .claude/skills/{name}/SKILL.md with YAML frontmatter" : void 0,
     fix: totalSkillFiles > 0 && !allOpenSkills ? {
@@ -9686,27 +9761,47 @@ async function initCommand(options) {
   const bin = resolveCaliber();
   const firstRun = isFirstRun(process.cwd());
   if (firstRun) {
-    console.log(brand.bold(`
+    console.log(
+      brand.bold(`
    \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557     \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557
   \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551     \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557
   \u2588\u2588\u2551     \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551     \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D
   \u2588\u2588\u2551     \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551     \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u255D  \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557
   \u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551  \u2588\u2588\u2551
    \u255A\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D
-  `));
+  `)
+    );
     console.log(chalk14.dim("  Keep your AI agent configs in sync \u2014 automatically."));
     console.log(chalk14.dim("  Works across Claude Code, Cursor, Codex, and GitHub Copilot.\n"));
-    console.log(title.bold("  How it works:\n"));
-    console.log(chalk14.dim("  1. Connect    Auto-detect your LLM provider and agents"));
-    console.log(chalk14.dim("  2. Build      Install sync, scan your project, generate configs"));
-    console.log(chalk14.dim("  3. Done       Review score and start syncing\n"));
+    console.log(title.bold("  What this does:\n"));
+    console.log(
+      chalk14.dim("  Caliber reads your project structure (file tree, package.json, etc.)")
+    );
+    console.log(chalk14.dim("  and generates agent config files (CLAUDE.md, .cursor/rules/, etc.)."));
+    console.log(chalk14.dim("  You review all changes before anything is written to disk.\n"));
+    console.log(title.bold("  Steps:\n"));
+    console.log(
+      chalk14.dim("  1. Connect    Pick your LLM provider (or use your existing subscription)")
+    );
+    console.log(
+      chalk14.dim("  2. Build      Scan project, generate configs, install pre-commit sync")
+    );
+    console.log(
+      chalk14.dim("  3. Review     See exactly what changed \u2014 accept, refine, or decline\n")
+    );
   } else {
     console.log(brand.bold("\n  CALIBER") + chalk14.dim("  \u2014 setting up continuous sync\n"));
   }
   const platforms = detectPlatforms();
   if (!platforms.claude && !platforms.cursor && !platforms.codex && !platforms.opencode) {
-    console.log(chalk14.yellow("  \u26A0 No supported AI platforms detected (Claude, Cursor, Codex, OpenCode)."));
-    console.log(chalk14.yellow("    Caliber will still generate config files, but they won't be auto-installed.\n"));
+    console.log(
+      chalk14.yellow("  \u26A0 No supported AI platforms detected (Claude, Cursor, Codex, OpenCode).")
+    );
+    console.log(
+      chalk14.yellow(
+        "    Caliber will still generate config files, but they won't be auto-installed.\n"
+      )
+    );
   }
   const report = options.debugReport ? new DebugReport() : null;
   console.log(title.bold("  Step 1/3 \u2014 Connect\n"));
@@ -9761,9 +9856,12 @@ async function initCommand(options) {
   console.log(chalk14.dim(modelLine + "\n"));
   if (report) {
     report.markStep("Provider connection");
-    report.addSection("LLM Provider", `- **Provider**: ${config.provider}
+    report.addSection(
+      "LLM Provider",
+      `- **Provider**: ${config.provider}
 - **Model**: ${displayModel}
-- **Fast model**: ${fastModel || "none"}`);
+- **Fast model**: ${fastModel || "none"}`
+    );
   }
   await validateModel({ fast: true });
   let targetAgent;
@@ -9799,9 +9897,12 @@ async function initCommand(options) {
   console.log(`  ${chalk14.green("\u2713")} Onboarding hook \u2014 nudges new team members to set up`);
   const { ensureBuiltinSkills: ensureBuiltinSkills2 } = await Promise.resolve().then(() => (init_builtin_skills(), builtin_skills_exports));
   for (const agent of targetAgent) {
-    if (agent === "claude" && !fs34.existsSync(".claude")) fs34.mkdirSync(".claude", { recursive: true });
-    if (agent === "cursor" && !fs34.existsSync(".cursor")) fs34.mkdirSync(".cursor", { recursive: true });
-    if (agent === "codex" && !fs34.existsSync(".agents")) fs34.mkdirSync(".agents", { recursive: true });
+    if (agent === "claude" && !fs34.existsSync(".claude"))
+      fs34.mkdirSync(".claude", { recursive: true });
+    if (agent === "cursor" && !fs34.existsSync(".cursor"))
+      fs34.mkdirSync(".cursor", { recursive: true });
+    if (agent === "codex" && !fs34.existsSync(".agents"))
+      fs34.mkdirSync(".agents", { recursive: true });
   }
   const skillsWritten = ensureBuiltinSkills2();
   if (skillsWritten.length > 0) {
@@ -9819,11 +9920,16 @@ async function initCommand(options) {
   log(options.verbose, `Baseline score: ${baselineScore.score}/100`);
   if (report) {
     report.markStep("Baseline scoring");
-    report.addSection("Scoring: Baseline", `**Score**: ${baselineScore.score}/100
+    report.addSection(
+      "Scoring: Baseline",
+      `**Score**: ${baselineScore.score}/100
 
 | Check | Passed | Points | Max |
 |-------|--------|--------|-----|
-` + baselineScore.checks.map((c) => `| ${c.name} | ${c.passed ? "Yes" : "No"} | ${c.earnedPoints} | ${c.maxPoints} |`).join("\n"));
+` + baselineScore.checks.map(
+        (c) => `| ${c.name} | ${c.passed ? "Yes" : "No"} | ${c.earnedPoints} | ${c.maxPoints} |`
+      ).join("\n")
+    );
     report.addSection("Generation: Target Agents", targetAgent.join(", "));
   }
   const hasExistingConfig = !!(baselineScore.checks.some((c) => c.id === "claude_md_exists" && c.passed) || baselineScore.checks.some((c) => c.id === "cursorrules_exists" && c.passed));
@@ -9842,8 +9948,19 @@ async function initCommand(options) {
   if (hasExistingConfig && baselineScore.score === 100 && !options.force) {
     skipGeneration = true;
   } else if (hasExistingConfig && !options.force && !options.autoApprove) {
-    console.log(chalk14.dim(`  Config score: ${baselineScore.score}/100 \u2014 Caliber can improve this.
+    const topGains = baselineScore.checks.filter((c) => !c.passed && c.maxPoints > 0).sort((a, b) => b.maxPoints - b.earnedPoints - (a.maxPoints - a.earnedPoints)).slice(0, 3);
+    console.log(chalk14.dim(`  Config score: ${baselineScore.score}/100
 `));
+    if (topGains.length > 0) {
+      console.log(chalk14.dim("  Top improvements Caliber can make:"));
+      for (const c of topGains) {
+        const pts = c.maxPoints - c.earnedPoints;
+        console.log(
+          chalk14.dim(`    +${pts} pts`) + chalk14.white(` ${c.name}`) + (c.suggestion ? chalk14.gray(` \u2014 ${c.suggestion}`) : "")
+        );
+      }
+      console.log("");
+    }
     const improveAnswer = await confirm2({ message: "Improve your existing configs?" });
     skipGeneration = !improveAnswer;
   }
@@ -9873,7 +9990,12 @@ async function initCommand(options) {
     if (targetAgent.includes("cursor")) {
       const rulesDir = path28.join(".cursor", "rules");
       if (!fs34.existsSync(rulesDir)) fs34.mkdirSync(rulesDir, { recursive: true });
-      for (const rule of [getCursorPreCommitRule2(), getCursorLearningsRule2(), getCursorSyncRule2(), getCursorSetupRule2()]) {
+      for (const rule of [
+        getCursorPreCommitRule2(),
+        getCursorLearningsRule2(),
+        getCursorSyncRule2(),
+        getCursorSetupRule2()
+      ]) {
         fs34.writeFileSync(path28.join(rulesDir, rule.filename), rule.content);
       }
       console.log(`  ${chalk14.green("\u2713")} Cursor rules \u2014 added Caliber sync rules`);
@@ -9905,7 +10027,9 @@ async function initCommand(options) {
     trackInitCompleted("sync-only", baselineScore.score);
     console.log(chalk14.bold.green("\n  Caliber sync is set up!\n"));
     console.log(chalk14.dim("  Your agent configs will sync automatically on every commit."));
-    console.log(chalk14.dim("  Run ") + title(`${bin} init --force`) + chalk14.dim(" anytime to generate or improve configs.\n"));
+    console.log(
+      chalk14.dim("  Run ") + title(`${bin} init --force`) + chalk14.dim(" anytime to generate or improve configs.\n")
+    );
     return;
   }
   const genModelInfo = fastModel ? `  Using ${displayModel} for docs, ${fastModel} for skills` : `  Using ${displayModel}`;
@@ -9923,8 +10047,14 @@ async function initCommand(options) {
   const TASK_STACK = display.add("Detecting project stack", { pipelineLabel: "Scan" });
   const TASK_CONFIG = display.add("Generating configs", { depth: 1, pipelineLabel: "Generate" });
   const TASK_SKILLS_GEN = display.add("Generating skills", { depth: 2, pipelineLabel: "Skills" });
-  const TASK_SKILLS_SEARCH = display.add("Searching community skills", { depth: 1, pipelineLabel: "Search", pipelineRow: 1 });
-  const TASK_SCORE_REFINE = display.add("Validating & refining config", { pipelineLabel: "Validate" });
+  const TASK_SKILLS_SEARCH = display.add("Searching community skills", {
+    depth: 1,
+    pipelineLabel: "Search",
+    pipelineRow: 1
+  });
+  const TASK_SCORE_REFINE = display.add("Validating & refining config", {
+    pipelineLabel: "Validate"
+  });
   display.start();
   display.enableWaitingContent();
   try {
@@ -9934,21 +10064,39 @@ async function initCommand(options) {
     const stackSummary = stackParts.join(", ") || "no languages";
     const largeRepoNote = fingerprint.fileTree.length > 5e3 ? ` (${fingerprint.fileTree.length.toLocaleString()} files, smart sampling active)` : "";
     display.update(TASK_STACK, "done", stackSummary + largeRepoNote);
-    trackInitProjectDiscovered(fingerprint.languages.length, fingerprint.frameworks.length, fingerprint.fileTree.length);
-    log(options.verbose, `Fingerprint: ${fingerprint.languages.length} languages, ${fingerprint.frameworks.length} frameworks, ${fingerprint.fileTree.length} files`);
+    trackInitProjectDiscovered(
+      fingerprint.languages.length,
+      fingerprint.frameworks.length,
+      fingerprint.fileTree.length
+    );
+    log(
+      options.verbose,
+      `Fingerprint: ${fingerprint.languages.length} languages, ${fingerprint.frameworks.length} frameworks, ${fingerprint.fileTree.length} files`
+    );
     const cliSources = options.source || [];
     const workspaces = getDetectedWorkspaces(process.cwd());
     const sources2 = resolveAllSources(process.cwd(), cliSources, workspaces);
     if (sources2.length > 0) {
       fingerprint.sources = sources2;
-      log(options.verbose, `Sources: ${sources2.length} resolved (${sources2.map((s) => s.name).join(", ")})`);
+      log(
+        options.verbose,
+        `Sources: ${sources2.length} resolved (${sources2.map((s) => s.name).join(", ")})`
+      );
     }
     if (report) {
-      report.addJson("Fingerprint: Git", { remote: fingerprint.gitRemoteUrl, packageName: fingerprint.packageName });
+      report.addJson("Fingerprint: Git", {
+        remote: fingerprint.gitRemoteUrl,
+        packageName: fingerprint.packageName
+      });
       report.addCodeBlock("Fingerprint: File Tree", fingerprint.fileTree.join("\n"));
-      report.addJson("Fingerprint: Detected Stack", { languages: fingerprint.languages, frameworks: fingerprint.frameworks, tools: fingerprint.tools });
+      report.addJson("Fingerprint: Detected Stack", {
+        languages: fingerprint.languages,
+        frameworks: fingerprint.frameworks,
+        tools: fingerprint.tools
+      });
       report.addJson("Fingerprint: Existing Configs", fingerprint.existingConfigs);
-      if (fingerprint.codeAnalysis) report.addJson("Fingerprint: Code Analysis", fingerprint.codeAnalysis);
+      if (fingerprint.codeAnalysis)
+        report.addJson("Fingerprint: Code Analysis", fingerprint.codeAnalysis);
     }
     const isEmpty = fingerprint.fileTree.length < 3;
     if (isEmpty) {
@@ -9979,13 +10127,26 @@ async function initCommand(options) {
       let passingChecks;
       let currentScore;
       if (hasExistingConfig && localBaseline.score >= 95 && !options.force) {
-        const currentLlmFixable = localBaseline.checks.filter((c) => !c.passed && c.maxPoints > 0 && !NON_LLM_CHECKS.has(c.id));
-        failingChecks = currentLlmFixable.map((c) => ({ name: c.name, suggestion: c.suggestion, fix: c.fix }));
+        const currentLlmFixable = localBaseline.checks.filter(
+          (c) => !c.passed && c.maxPoints > 0 && !NON_LLM_CHECKS.has(c.id)
+        );
+        failingChecks = currentLlmFixable.map((c) => ({
+          name: c.name,
+          suggestion: c.suggestion,
+          fix: c.fix
+        }));
         passingChecks = localBaseline.checks.filter((c) => c.passed).map((c) => ({ name: c.name }));
         currentScore = localBaseline.score;
       }
       if (report) {
-        const fullPrompt = buildGeneratePrompt(fingerprint, targetAgent, fingerprint.description, failingChecks, currentScore, passingChecks);
+        const fullPrompt = buildGeneratePrompt(
+          fingerprint,
+          targetAgent,
+          fingerprint.description,
+          failingChecks,
+          currentScore,
+          passingChecks
+        );
         report.addCodeBlock("Generation: Full LLM Prompt", fullPrompt);
       }
       const result = await generateSetup(
@@ -10105,7 +10266,10 @@ async function initCommand(options) {
     if (rawOutput) report.addCodeBlock("Generation: Raw LLM Response", rawOutput);
     report.addJson("Generation: Parsed Config", generatedSetup);
   }
-  log(options.verbose, `Generation completed: ${elapsedMs}ms, stopReason: ${genStopReason || "end_turn"}`);
+  log(
+    options.verbose,
+    `Generation completed: ${elapsedMs}ms, stopReason: ${genStopReason || "end_turn"}`
+  );
   console.log(title.bold("  Step 3/3 \u2014 Done\n"));
   const setupFiles = collectSetupFiles(generatedSetup, targetAgent);
   const staged = stageFiles(setupFiles, process.cwd());
@@ -10117,10 +10281,18 @@ async function initCommand(options) {
     }
     console.log("");
   }
-  console.log(chalk14.dim(`  ${chalk14.green(`${staged.newFiles} new`)} / ${chalk14.yellow(`${staged.modifiedFiles} modified`)} file${totalChanges !== 1 ? "s" : ""}`));
+  console.log(
+    chalk14.dim(
+      `  ${chalk14.green(`${staged.newFiles} new`)} / ${chalk14.yellow(`${staged.modifiedFiles} modified`)} file${totalChanges !== 1 ? "s" : ""}`
+    )
+  );
   if (skillSearchResult.results.length > 0) {
-    console.log(chalk14.dim(`  ${chalk14.cyan(`${skillSearchResult.results.length}`)} community skills available to install
-`));
+    console.log(
+      chalk14.dim(
+        `  ${chalk14.cyan(`${skillSearchResult.results.length}`)} community skills available to install
+`
+      )
+    );
   } else {
     console.log("");
   }
@@ -10156,8 +10328,12 @@ async function initCommand(options) {
     }
     const updatedFiles = collectSetupFiles(generatedSetup, targetAgent);
     const restaged = stageFiles(updatedFiles, process.cwd());
-    console.log(chalk14.dim(`  ${chalk14.green(`${restaged.newFiles} new`)} / ${chalk14.yellow(`${restaged.modifiedFiles} modified`)} file${restaged.newFiles + restaged.modifiedFiles !== 1 ? "s" : ""}
-`));
+    console.log(
+      chalk14.dim(
+        `  ${chalk14.green(`${restaged.newFiles} new`)} / ${chalk14.yellow(`${restaged.modifiedFiles} modified`)} file${restaged.newFiles + restaged.modifiedFiles !== 1 ? "s" : ""}
+`
+      )
+    );
     printSetupSummary(generatedSetup);
     const { openReview: openRev } = await Promise.resolve().then(() => (init_review(), review_exports));
     await openRev("terminal", restaged.stagedFiles);
@@ -10183,7 +10359,8 @@ async function initCommand(options) {
       const agentRefs = [];
       if (claude) agentRefs.push("See `CLAUDE.md` for Claude Code configuration.");
       if (cursor) agentRefs.push("See `.cursor/rules/` for Cursor rules.");
-      if (agentRefs.length === 0) agentRefs.push("See CLAUDE.md and .cursor/rules/ for agent configurations.");
+      if (agentRefs.length === 0)
+        agentRefs.push("See CLAUDE.md and .cursor/rules/ for agent configurations.");
       const stubContent = `# AGENTS.md
 
 This project uses AI coding agents configured by [Caliber](https://github.com/caliber-ai-org/ai-setup).
@@ -10230,24 +10407,39 @@ ${agentRefs.join(" ")}
   if (afterScore.score < baselineScore.score) {
     trackInitScoreRegression(baselineScore.score, afterScore.score);
     console.log("");
-    console.log(chalk14.yellow(`  Score would drop from ${baselineScore.score} to ${afterScore.score} \u2014 reverting changes.`));
+    console.log(
+      chalk14.yellow(
+        `  Score would drop from ${baselineScore.score} to ${afterScore.score} \u2014 reverting changes.`
+      )
+    );
     try {
       const { restored, removed } = undoSetup();
       if (restored.length > 0 || removed.length > 0) {
-        console.log(chalk14.dim(`  Reverted ${restored.length + removed.length} file${restored.length + removed.length === 1 ? "" : "s"} from backup.`));
+        console.log(
+          chalk14.dim(
+            `  Reverted ${restored.length + removed.length} file${restored.length + removed.length === 1 ? "" : "s"} from backup.`
+          )
+        );
       }
     } catch {
     }
-    console.log(chalk14.dim("  Run ") + chalk14.hex("#83D1EB")(`${bin} init --force`) + chalk14.dim(" to override.\n"));
+    console.log(
+      chalk14.dim("  Run ") + chalk14.hex("#83D1EB")(`${bin} init --force`) + chalk14.dim(" to override.\n")
+    );
     return;
   }
   if (report) {
     report.markStep("Post-write scoring");
-    report.addSection("Scoring: Post-Write", `**Score**: ${afterScore.score}/100 (delta: ${afterScore.score - baselineScore.score >= 0 ? "+" : ""}${afterScore.score - baselineScore.score})
+    report.addSection(
+      "Scoring: Post-Write",
+      `**Score**: ${afterScore.score}/100 (delta: ${afterScore.score - baselineScore.score >= 0 ? "+" : ""}${afterScore.score - baselineScore.score})
 
 | Check | Passed | Points | Max |
 |-------|--------|--------|-----|
-` + afterScore.checks.map((c) => `| ${c.name} | ${c.passed ? "Yes" : "No"} | ${c.earnedPoints} | ${c.maxPoints} |`).join("\n"));
+` + afterScore.checks.map(
+        (c) => `| ${c.name} | ${c.passed ? "Yes" : "No"} | ${c.earnedPoints} | ${c.maxPoints} |`
+      ).join("\n")
+    );
   }
   recordScore(afterScore, "init");
   trackInitCompleted("full-generation", afterScore.score);
@@ -10255,7 +10447,10 @@ ${agentRefs.join(" ")}
   if (options.verbose) {
     log(options.verbose, `Final score: ${afterScore.score}/100`);
     for (const c of afterScore.checks.filter((ch) => !ch.passed)) {
-      log(options.verbose, `  Still failing: ${c.name} (${c.earnedPoints}/${c.maxPoints})${c.suggestion ? ` \u2014 ${c.suggestion}` : ""}`);
+      log(
+        options.verbose,
+        `  Still failing: ${c.name} (${c.earnedPoints}/${c.maxPoints})${c.suggestion ? ` \u2014 ${c.suggestion}` : ""}`
+      );
     }
   }
   let communitySkillsInstalled = 0;
@@ -10272,14 +10467,20 @@ ${agentRefs.join(" ")}
   const done = chalk14.green("\u2713");
   console.log(chalk14.bold.green("\n  Caliber is set up!\n"));
   console.log(chalk14.bold("  What's configured:\n"));
-  console.log(`    ${done}  Continuous sync     ${chalk14.dim("pre-commit hook keeps all agent configs in sync")}`);
+  console.log(
+    `    ${done}  Continuous sync     ${chalk14.dim("pre-commit hook keeps all agent configs in sync")}`
+  );
   console.log(`    ${done}  Config generated    ${chalk14.dim(`score: ${afterScore.score}/100`)}`);
-  console.log(`    ${done}  Agent skills        ${chalk14.dim("/setup-caliber for new team members")}`);
+  console.log(
+    `    ${done}  Agent skills        ${chalk14.dim("/setup-caliber for new team members")}`
+  );
   if (hasLearnableAgent) {
     console.log(`    ${done}  Session learning    ${chalk14.dim("learns from your corrections")}`);
   }
   if (communitySkillsInstalled > 0) {
-    console.log(`    ${done}  Community skills    ${chalk14.dim(`${communitySkillsInstalled} installed for your stack`)}`);
+    console.log(
+      `    ${done}  Community skills    ${chalk14.dim(`${communitySkillsInstalled} installed for your stack`)}`
+    );
   }
   console.log(chalk14.bold("\n  What happens next:\n"));
   console.log(chalk14.dim("    Every commit syncs your agent configs automatically."));
@@ -10296,8 +10497,10 @@ ${agentRefs.join(" ")}
     report.markStep("Finished");
     const reportPath = path28.join(process.cwd(), ".caliber", "debug-report.md");
     report.write(reportPath);
-    console.log(chalk14.dim(`  Debug report written to ${path28.relative(process.cwd(), reportPath)}
-`));
+    console.log(
+      chalk14.dim(`  Debug report written to ${path28.relative(process.cwd(), reportPath)}
+`)
+    );
   }
 }
 
@@ -10633,18 +10836,27 @@ async function scoreCommand(options) {
   const separator = chalk18.gray("  " + "\u2500".repeat(53));
   console.log(separator);
   const bin = resolveCaliber();
-  if (result.score < 40) {
+  const failing = result.checks.filter((c) => !c.passed && c.maxPoints > 0).sort((a, b) => b.maxPoints - b.earnedPoints - (a.maxPoints - a.earnedPoints));
+  if (result.score < 70 && failing.length > 0) {
+    const topFix = failing[0];
+    const pts = topFix.maxPoints - topFix.earnedPoints;
     console.log(
-      chalk18.gray("  Run ") + chalk18.hex("#83D1EB")(`${bin} init`) + chalk18.gray(" to generate a complete, optimized config.")
+      chalk18.gray("  Biggest gain: ") + chalk18.yellow(`+${pts} pts`) + chalk18.gray(` from "${topFix.name}"`) + (topFix.suggestion ? chalk18.gray(` \u2014 ${topFix.suggestion}`) : "")
     );
-  } else if (result.score < 70) {
     console.log(
-      chalk18.gray("  Run ") + chalk18.hex("#83D1EB")(`${bin} init`) + chalk18.gray(" to improve your config.")
+      chalk18.gray("  Run ") + chalk18.hex("#83D1EB")(`${bin} init`) + chalk18.gray(" to auto-fix these.")
     );
-  } else {
+  } else if (failing.length > 0) {
     console.log(
-      chalk18.green("  Looking good!") + chalk18.gray(" Run ") + chalk18.hex("#83D1EB")(`${bin} regenerate`) + chalk18.gray(" to rebuild from scratch.")
+      chalk18.green("  Looking good!") + chalk18.gray(
+        ` ${failing.length} check${failing.length === 1 ? "" : "s"} can still be improved.`
+      )
     );
+    console.log(
+      chalk18.gray("  Run ") + chalk18.hex("#83D1EB")(`${bin} init`) + chalk18.gray(" to improve, or ") + chalk18.hex("#83D1EB")(`${bin} regenerate`) + chalk18.gray(" to rebuild from scratch.")
+    );
+  } else {
+    console.log(chalk18.green("  Perfect score! Your agent configs are fully optimized."));
   }
   console.log("");
 }
@@ -10660,12 +10872,23 @@ import { execSync as execSync15 } from "child_process";
 var MAX_DIFF_BYTES = 1e5;
 var DOC_PATTERNS = [
   "CLAUDE.md",
+  "AGENTS.md",
   "README.md",
   ".cursorrules",
   ".cursor/rules/",
+  ".cursor/skills/",
   ".claude/skills/",
+  ".agents/skills/",
+  ".opencode/skills/",
+  ".github/copilot-instructions.md",
+  ".github/instructions/",
   "CALIBER_LEARNINGS.md"
 ];
+function truncateAtLineEnd(text, maxBytes) {
+  if (text.length <= maxBytes) return text;
+  const lastNewline = text.lastIndexOf("\n", maxBytes);
+  return lastNewline === -1 ? text.slice(0, maxBytes) : text.slice(0, lastNewline);
+}
 function excludeArgs() {
   return DOC_PATTERNS.flatMap((p) => ["--", `:!${p}`]);
 }
@@ -10714,9 +10937,9 @@ function collectDiff(lastSha) {
   const totalSize = committedDiff.length + stagedDiff.length + unstagedDiff.length;
   if (totalSize > MAX_DIFF_BYTES) {
     const ratio = MAX_DIFF_BYTES / totalSize;
-    committedDiff = committedDiff.slice(0, Math.floor(committedDiff.length * ratio));
-    stagedDiff = stagedDiff.slice(0, Math.floor(stagedDiff.length * ratio));
-    unstagedDiff = unstagedDiff.slice(0, Math.floor(unstagedDiff.length * ratio));
+    committedDiff = truncateAtLineEnd(committedDiff, Math.floor(committedDiff.length * ratio));
+    stagedDiff = truncateAtLineEnd(stagedDiff, Math.floor(stagedDiff.length * ratio));
+    unstagedDiff = truncateAtLineEnd(unstagedDiff, Math.floor(unstagedDiff.length * ratio));
   }
   const hasChanges = !!(committedDiff || stagedDiff || unstagedDiff || changedFiles.length);
   const parts = [];
@@ -10735,11 +10958,11 @@ import path30 from "path";
 function writeRefreshDocs(docs) {
   const written = [];
   if (docs.agentsMd) {
-    fs37.writeFileSync("AGENTS.md", appendLearningsBlock(appendPreCommitBlock(docs.agentsMd)));
+    fs37.writeFileSync("AGENTS.md", appendManagedBlocks(docs.agentsMd, "codex"));
     written.push("AGENTS.md");
   }
   if (docs.claudeMd) {
-    fs37.writeFileSync("CLAUDE.md", appendLearningsBlock(appendPreCommitBlock(docs.claudeMd)));
+    fs37.writeFileSync("CLAUDE.md", appendManagedBlocks(docs.claudeMd));
     written.push("CLAUDE.md");
   }
   if (docs.readmeMd) {
@@ -10758,17 +10981,12 @@ function writeRefreshDocs(docs) {
       written.push(`.cursor/rules/${rule.filename}`);
     }
   }
-  if (docs.claudeSkills) {
-    const skillsDir = path30.join(".claude", "skills");
-    if (!fs37.existsSync(skillsDir)) fs37.mkdirSync(skillsDir, { recursive: true });
-    for (const skill of docs.claudeSkills) {
-      fs37.writeFileSync(path30.join(skillsDir, skill.filename), skill.content);
-      written.push(`.claude/skills/${skill.filename}`);
-    }
-  }
   if (docs.copilotInstructions) {
     fs37.mkdirSync(".github", { recursive: true });
-    fs37.writeFileSync(path30.join(".github", "copilot-instructions.md"), appendLearningsBlock(appendPreCommitBlock(docs.copilotInstructions)));
+    fs37.writeFileSync(
+      path30.join(".github", "copilot-instructions.md"),
+      appendManagedBlocks(docs.copilotInstructions, "copilot")
+    );
     written.push(".github/copilot-instructions.md");
   }
   if (docs.copilotInstructionFiles) {
@@ -10784,6 +11002,7 @@ function writeRefreshDocs(docs) {
 
 // src/ai/refresh.ts
 init_config();
+init_pre_commit_block();
 async function refreshDocs(diff, existingDocs, projectContext, learnedSection, sources2) {
   const prompt = buildRefreshPrompt(diff, existingDocs, projectContext, learnedSection, sources2);
   const fastModel = getFastModel();
@@ -10799,13 +11018,17 @@ function buildRefreshPrompt(diff, existingDocs, projectContext, learnedSection,
   const parts = [];
   parts.push("Update documentation based on the following code changes.\n");
   if (projectContext.packageName) parts.push(`Project: ${projectContext.packageName}`);
-  if (projectContext.languages?.length) parts.push(`Languages: ${projectContext.languages.join(", ")}`);
-  if (projectContext.frameworks?.length) parts.push(`Frameworks: ${projectContext.frameworks.join(", ")}`);
+  if (projectContext.languages?.length)
+    parts.push(`Languages: ${projectContext.languages.join(", ")}`);
+  if (projectContext.frameworks?.length)
+    parts.push(`Frameworks: ${projectContext.frameworks.join(", ")}`);
   if (projectContext.fileTree?.length) {
     const tree = projectContext.fileTree.slice(0, 200);
-    parts.push(`
+    parts.push(
+      `
 File tree (${tree.length}/${projectContext.fileTree.length} \u2014 only reference paths from this list):
-${tree.join("\n")}`);
+${tree.join("\n")}`
+    );
   }
   parts.push(`
 Changed files: ${diff.changedFiles.join(", ")}`);
@@ -10825,11 +11048,11 @@ Changed files: ${diff.changedFiles.join(", ")}`);
   parts.push("\n--- Current Documentation ---");
   if (existingDocs.agentsMd) {
     parts.push("\n[AGENTS.md]");
-    parts.push(existingDocs.agentsMd);
+    parts.push(stripManagedBlocks(existingDocs.agentsMd));
   }
   if (existingDocs.claudeMd) {
     parts.push("\n[CLAUDE.md]");
-    parts.push(existingDocs.claudeMd);
+    parts.push(stripManagedBlocks(existingDocs.claudeMd));
   }
   if (existingDocs.readmeMd) {
     parts.push("\n[README.md]");
@@ -10839,20 +11062,25 @@ Changed files: ${diff.changedFiles.join(", ")}`);
     parts.push("\n[.cursorrules]");
     parts.push(existingDocs.cursorrules);
   }
-  if (existingDocs.claudeSkills?.length) {
-    for (const skill of existingDocs.claudeSkills) {
-      parts.push(`
-[.claude/skills/${skill.filename}]`);
-      parts.push(skill.content);
-    }
-  }
   if (existingDocs.cursorRules?.length) {
     for (const rule of existingDocs.cursorRules) {
+      if (rule.filename.startsWith("caliber-")) continue;
       parts.push(`
 [.cursor/rules/${rule.filename}]`);
       parts.push(rule.content);
     }
   }
+  if (existingDocs.copilotInstructions) {
+    parts.push("\n[.github/copilot-instructions.md]");
+    parts.push(stripManagedBlocks(existingDocs.copilotInstructions));
+  }
+  if (existingDocs.copilotInstructionFiles?.length) {
+    for (const file of existingDocs.copilotInstructionFiles) {
+      parts.push(`
+[.github/instructions/${file.filename}]`);
+      parts.push(file.content);
+    }
+  }
   if (learnedSection) {
     parts.push("\n--- Learned Patterns (from session learning) ---");
     parts.push("Consider these accumulated learnings when deciding what to update:");
@@ -11062,6 +11290,40 @@ function migrateInlineLearnings() {
 init_config();
 init_resolve_caliber();
 init_builtin_skills();
+function writeRefreshError(error) {
+  try {
+    if (!fs40.existsSync(CALIBER_DIR)) fs40.mkdirSync(CALIBER_DIR, { recursive: true });
+    fs40.writeFileSync(
+      REFRESH_LAST_ERROR_FILE,
+      JSON.stringify(
+        {
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          error: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : void 0,
+          cwd: process.cwd(),
+          nodeVersion: process.version
+        },
+        null,
+        2
+      )
+    );
+  } catch {
+  }
+}
+function readRefreshError() {
+  try {
+    if (!fs40.existsSync(REFRESH_LAST_ERROR_FILE)) return null;
+    return JSON.parse(fs40.readFileSync(REFRESH_LAST_ERROR_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function clearRefreshError() {
+  try {
+    if (fs40.existsSync(REFRESH_LAST_ERROR_FILE)) fs40.unlinkSync(REFRESH_LAST_ERROR_FILE);
+  } catch {
+  }
+}
 function log2(quiet, ...args) {
   if (!quiet) console.log(...args);
 }
@@ -11080,21 +11342,41 @@ function discoverGitRepos(parentDir) {
   }
   return repos.sort();
 }
+function collectFilesToWrite(updatedDocs) {
+  const files = [];
+  if (updatedDocs.agentsMd) files.push("AGENTS.md");
+  if (updatedDocs.claudeMd) files.push("CLAUDE.md");
+  if (updatedDocs.readmeMd) files.push("README.md");
+  if (updatedDocs.cursorrules) files.push(".cursorrules");
+  if (Array.isArray(updatedDocs.cursorRules)) {
+    for (const r of updatedDocs.cursorRules)
+      files.push(`.cursor/rules/${r.filename}`);
+  }
+  if (updatedDocs.copilotInstructions) files.push(".github/copilot-instructions.md");
+  if (Array.isArray(updatedDocs.copilotInstructionFiles)) {
+    for (const f of updatedDocs.copilotInstructionFiles)
+      files.push(`.github/instructions/${f.filename}`);
+  }
+  return files;
+}
 var REFRESH_COOLDOWN_MS = 3e4;
 async function refreshSingleRepo(repoDir, options) {
   const quiet = !!options.quiet;
   const prefix = options.label ? `${chalk19.bold(options.label)} ` : "";
   const state = readState();
   const lastSha = state?.lastRefreshSha ?? null;
-  if (state?.lastRefreshTimestamp) {
+  const currentSha = getCurrentHeadSha();
+  if (state?.lastRefreshTimestamp && lastSha && currentSha === lastSha) {
     const elapsed = Date.now() - new Date(state.lastRefreshTimestamp).getTime();
     if (elapsed < REFRESH_COOLDOWN_MS && elapsed > 0) {
-      log2(quiet, chalk19.dim(`${prefix}Skipped \u2014 last refresh was ${Math.round(elapsed / 1e3)}s ago.`));
+      log2(
+        quiet,
+        chalk19.dim(`${prefix}Skipped \u2014 last refresh was ${Math.round(elapsed / 1e3)}s ago.`)
+      );
       return;
     }
   }
   const diff = collectDiff(lastSha);
-  const currentSha = getCurrentHeadSha();
   if (!diff.hasChanges) {
     if (currentSha) {
       writeState({ lastRefreshSha: currentSha, lastRefreshTimestamp: (/* @__PURE__ */ new Date()).toISOString() });
@@ -11103,9 +11385,9 @@ async function refreshSingleRepo(repoDir, options) {
     return;
   }
   const spinner = quiet ? null : ora6(`${prefix}Analyzing changes...`).start();
-  const existingDocs = readExistingConfigs(repoDir);
   const learnedSection = readLearnedSection();
   const fingerprint = await collectFingerprint(repoDir);
+  const existingDocs = fingerprint.existingConfigs;
   const projectContext = {
     languages: fingerprint.languages,
     frameworks: fingerprint.frameworks,
@@ -11124,12 +11406,24 @@ async function refreshSingleRepo(repoDir, options) {
   const sourcesPayload = sources2.length > 0 ? sources2 : void 0;
   let response;
   try {
-    response = await refreshDocs(diffPayload, existingDocs, projectContext, learnedSection, sourcesPayload);
+    response = await refreshDocs(
+      diffPayload,
+      existingDocs,
+      projectContext,
+      learnedSection,
+      sourcesPayload
+    );
   } catch (firstErr) {
     const isTransient = firstErr instanceof Error && TRANSIENT_ERRORS.some((e) => firstErr.message.toLowerCase().includes(e.toLowerCase()));
     if (!isTransient) throw firstErr;
     try {
-      response = await refreshDocs(diffPayload, existingDocs, projectContext, learnedSection, sourcesPayload);
+      response = await refreshDocs(
+        diffPayload,
+        existingDocs,
+        projectContext,
+        learnedSection,
+        sourcesPayload
+      );
     } catch {
       spinner?.fail(`${prefix}Refresh failed after retry`);
       throw firstErr;
@@ -11155,9 +11449,9 @@ async function refreshSingleRepo(repoDir, options) {
   }
   const targetAgent = state?.targetAgent ?? detectTargetAgent(repoDir);
   const preScore = computeLocalScore(repoDir, targetAgent);
-  const filesToWrite = response.docsUpdated || [];
+  const allFilesToWrite = collectFilesToWrite(response.updatedDocs);
   const preRefreshContents = /* @__PURE__ */ new Map();
-  for (const filePath of filesToWrite) {
+  for (const filePath of allFilesToWrite) {
     const fullPath = path33.resolve(repoDir, filePath);
     try {
       preRefreshContents.set(filePath, fs40.readFileSync(fullPath, "utf-8"));
@@ -11181,7 +11475,9 @@ async function refreshSingleRepo(repoDir, options) {
         fs40.writeFileSync(fullPath, content);
       }
     }
-    spinner?.warn(`${prefix}Refresh reverted \u2014 score would drop from ${preScore.score} to ${postScore.score}`);
+    spinner?.warn(
+      `${prefix}Refresh reverted \u2014 score would drop from ${preScore.score} to ${postScore.score}`
+    );
     log2(quiet, chalk19.dim(`  Config quality gate prevented a regression. No files were changed.`));
     if (currentSha) {
       writeState({ lastRefreshSha: currentSha, lastRefreshTimestamp: (/* @__PURE__ */ new Date()).toISOString() });
@@ -11201,6 +11497,7 @@ async function refreshSingleRepo(repoDir, options) {
   for (const file of builtinWritten) {
     log2(quiet, `  ${chalk19.green("\u2713")} ${file} ${chalk19.dim("(built-in)")}`);
   }
+  clearRefreshError();
   if (currentSha) {
     writeState({ lastRefreshSha: currentSha, lastRefreshTimestamp: (/* @__PURE__ */ new Date()).toISOString() });
   }
@@ -11211,11 +11508,28 @@ async function refreshCommand(options) {
     const { isCaliberRunning: isCaliberRunning2 } = await Promise.resolve().then(() => (init_lock(), lock_exports));
     if (isCaliberRunning2()) return;
   }
+  if (!quiet) {
+    const lastError = readRefreshError();
+    if (lastError) {
+      console.log(chalk19.yellow(`
+  \u26A0  Last refresh failed (${lastError.timestamp}):`));
+      console.log(chalk19.dim(`     ${lastError.error}`));
+      console.log(
+        chalk19.dim(
+          `     Run with --debug for full details, or report at https://github.com/caliber-ai-org/ai-setup/issues
+`
+        )
+      );
+      clearRefreshError();
+    }
+  }
   try {
     const config = loadConfig();
     if (!config) {
       if (quiet) return;
-      console.log(chalk19.red("No LLM provider configured. Run ") + chalk19.hex("#83D1EB")(`${resolveCaliber()} config`) + chalk19.red(" (e.g. choose Cursor) or set an API key."));
+      console.log(
+        chalk19.red("No LLM provider configured. Run ") + chalk19.hex("#83D1EB")(`${resolveCaliber()} config`) + chalk19.red(" (e.g. choose Cursor) or set an API key.")
+      );
       throw new Error("__exit__");
     }
     await validateModel({ fast: true });
@@ -11226,7 +11540,9 @@ async function refreshCommand(options) {
     const repos = discoverGitRepos(process.cwd());
     if (repos.length === 0) {
       if (quiet) return;
-      console.log(chalk19.red("Not inside a git repository and no git repos found in child directories."));
+      console.log(
+        chalk19.red("Not inside a git repository and no git repos found in child directories.")
+      );
       throw new Error("__exit__");
     }
     log2(quiet, chalk19.dim(`Found ${repos.length} git repo${repos.length === 1 ? "" : "s"}
@@ -11239,12 +11555,19 @@ async function refreshCommand(options) {
         await refreshSingleRepo(repo, { ...options, label: repoName });
       } catch (err) {
         if (err instanceof Error && err.message === "__exit__") continue;
-        log2(quiet, chalk19.yellow(`${repoName}: refresh failed \u2014 ${err instanceof Error ? err.message : "unknown error"}`));
+        writeRefreshError(err);
+        log2(
+          quiet,
+          chalk19.yellow(
+            `${repoName}: refresh failed \u2014 ${err instanceof Error ? err.message : "unknown error"}`
+          )
+        );
       }
     }
     process.chdir(originalDir);
   } catch (err) {
     if (err instanceof Error && err.message === "__exit__") throw err;
+    writeRefreshError(err);
     if (quiet) return;
     const msg = err instanceof Error ? err.message : "Unknown error";
     console.log(chalk19.red(`Refresh failed: ${msg}`));
@@ -11589,10 +11912,10 @@ function writeState2(state) {
 function resetState() {
   writeState2({ ...DEFAULT_STATE });
 }
-var LOCK_FILE2 = "finalize.lock";
+var LOCK_FILE = "finalize.lock";
 var LOCK_STALE_MS = 5 * 60 * 1e3;
 function lockFilePath() {
-  return path34.join(getLearningDir(), LOCK_FILE2);
+  return path34.join(getLearningDir(), LOCK_FILE);
 }
 function acquireFinalizeLock() {
   ensureLearningDir();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rely-ai/caliber",
-  "version": "1.35.1",
+  "version": "1.36.1",
   "description": "AI context infrastructure for coding agents — keeps CLAUDE.md, Cursor rules, and skills in sync as your codebase evolves",
   "type": "module",
   "bin": {