@rely-ai/caliber 1.29.7 → 1.30.0-dev.1774285227

package/dist/bin.js

@@ -495,13 +495,13 @@ __export(lock_exports, {
   isCaliberRunning: () => isCaliberRunning,
   releaseLock: () => releaseLock
 });
-import fs36 from "fs";
-import path28 from "path";
+import fs37 from "fs";
+import path29 from "path";
 import os8 from "os";
 function isCaliberRunning() {
   try {
-    if (!fs36.existsSync(LOCK_FILE)) return false;
-    const raw = fs36.readFileSync(LOCK_FILE, "utf-8").trim();
+    if (!fs37.existsSync(LOCK_FILE)) return false;
+    const raw = fs37.readFileSync(LOCK_FILE, "utf-8").trim();
     const { pid, ts } = JSON.parse(raw);
     if (Date.now() - ts > STALE_MS) return false;
     try {
@@ -516,13 +516,13 @@ function isCaliberRunning() {
 }
 function acquireLock() {
   try {
-    fs36.writeFileSync(LOCK_FILE, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+    fs37.writeFileSync(LOCK_FILE, JSON.stringify({ pid: process.pid, ts: Date.now() }));
   } catch {
   }
 }
 function releaseLock() {
   try {
-    if (fs36.existsSync(LOCK_FILE)) fs36.unlinkSync(LOCK_FILE);
+    if (fs37.existsSync(LOCK_FILE)) fs37.unlinkSync(LOCK_FILE);
   } catch {
   }
 }
@@ -530,21 +530,21 @@ var LOCK_FILE, STALE_MS;
 var init_lock = __esm({
   "src/lib/lock.ts"() {
     "use strict";
-    LOCK_FILE = path28.join(os8.tmpdir(), ".caliber.lock");
+    LOCK_FILE = path29.join(os8.tmpdir(), ".caliber.lock");
     STALE_MS = 10 * 60 * 1e3;
   }
 });
 
 // src/cli.ts
 import { Command } from "commander";
-import fs46 from "fs";
-import path37 from "path";
+import fs47 from "fs";
+import path38 from "path";
 import { fileURLToPath } from "url";
 
 // src/commands/init.ts
-import path24 from "path";
+import path25 from "path";
 import chalk14 from "chalk";
-import fs31 from "fs";
+import fs32 from "fs";
 
 // src/fingerprint/index.ts
 import fs7 from "fs";
@@ -2307,7 +2307,7 @@ init_config();
 var ROLE_AND_CONTEXT = `You are an expert auditor for coding agent configurations (Claude Code, Cursor, Codex, and GitHub Copilot).
 
 Your job depends on context:
-- If no existing configs exist \u2192 generate an initial setup from scratch.
+- If no existing configs exist \u2192 generate an initial configuration from scratch.
 - If existing configs are provided \u2192 audit them and suggest targeted improvements. Preserve accurate content \u2014 don't rewrite what's already correct.`;
 var CONFIG_FILE_TYPES = `You understand these config files:
 - CLAUDE.md: Project context for Claude Code \u2014 build/test commands, architecture, conventions.
@@ -2320,6 +2320,12 @@ var CONFIG_FILE_TYPES = `You understand these config files:
 - .github/copilot-instructions.md: Always-on repository-wide instructions for GitHub Copilot \u2014 same purpose as CLAUDE.md but for Copilot. Plain markdown, no frontmatter.
 - .github/instructions/*.instructions.md: Path-specific instruction files for GitHub Copilot with YAML frontmatter containing an \`applyTo\` glob pattern (e.g. \`applyTo: "**/*.ts,**/*.tsx"\`). Only loaded when Copilot is working on matching files.`;
 var EXCLUSIONS = `Do NOT generate .claude/settings.json, .claude/settings.local.json, or mcpServers \u2014 those are managed separately.`;
+var AUDIT_CHECKLIST = `Audit checklist (when existing configs are provided):
+1. CLAUDE.md / README accuracy \u2014 do documented commands, paths, and architecture match the actual codebase?
+2. Missing skills \u2014 are there detected tools/frameworks that should have dedicated skills?
+3. Duplicate or overlapping skills \u2014 can any be merged or removed?
+4. Undocumented conventions \u2014 are there code patterns (commit style, async patterns, error handling) not captured in docs?
+5. Stale references \u2014 do docs mention removed files, renamed commands, or outdated patterns?`;
 var OUTPUT_FORMAT = `Your output MUST follow this exact format (no markdown fences):
 
 1. Exactly 6 short status lines (one per line, prefixed with "STATUS: "). Each should be a creative, specific description of what you're analyzing for THIS project \u2014 reference the project's actual languages, frameworks, or tools.
@@ -2383,7 +2389,10 @@ Accuracy (15 pts) \u2014 CRITICAL:
 
 Safety: Never include API keys, tokens, or credentials in config files.
 
-Note: Permissions, hooks, freshness tracking, and OpenSkills frontmatter are scored automatically by caliber \u2014 do not optimize for them.`;
+PRIORITY WHEN CONSTRAINTS CONFLICT: Grounding and reference density matter more than raw token count. A 2500-token config that references 50%+ of the project's directories scores higher than a 1500-token config that only mentions 3 paths. Pack references densely using the inline path style shown in OUTPUT SIZE CONSTRAINTS.
+
+Note: Permissions, hooks, freshness tracking, and OpenSkills frontmatter are scored automatically by caliber \u2014 do not optimize for them.
+README.md is provided for context only \u2014 do NOT include a readmeMd field in your output.`;
 var OUTPUT_SIZE_CONSTRAINTS = `OUTPUT SIZE CONSTRAINTS \u2014 these are critical:
 - CLAUDE.md / AGENTS.md: MUST be under 150 lines for maximum score. Aim for 100-140 lines. Be concise \u2014 commands, architecture overview, and key conventions. Use bullet points and tables, not prose.
 
@@ -2399,12 +2408,7 @@ var GENERATION_SYSTEM_PROMPT = `${ROLE_AND_CONTEXT}
 
 ${CONFIG_FILE_TYPES}
 
-Audit checklist (when existing configs are provided):
-1. CLAUDE.md / README accuracy \u2014 do documented commands, paths, and architecture match the actual codebase?
-2. Missing skills \u2014 are there detected tools/frameworks that should have dedicated skills?
-3. Duplicate or overlapping skills \u2014 can any be merged or removed?
-4. Undocumented conventions \u2014 are there code patterns (commit style, async patterns, error handling) not captured in docs?
-5. Stale references \u2014 do docs mention removed files, renamed commands, or outdated patterns?
+${AUDIT_CHECKLIST}
 
 ${EXCLUSIONS}
 
@@ -2449,6 +2453,8 @@ var CORE_GENERATION_PROMPT = `${ROLE_AND_CONTEXT}
 
 ${CONFIG_FILE_TYPES}
 
+${AUDIT_CHECKLIST}
+
 ${EXCLUSIONS}
 
 ${OUTPUT_FORMAT}
@@ -2468,10 +2474,10 @@ CoreSetup schema:
   },
   "codex": {
     "agentsMd": "string (markdown content for AGENTS.md)",
-    "skillTopics": [{ "name": "string (kebab-case)", "description": "string" }]
+    "skillTopics": [{ "name": "string (kebab-case)", "description": "string (what this skill does and WHEN to use it \u2014 include trigger phrases)" }]
   },
   "cursor": {
-    "skillTopics": [{ "name": "string (kebab-case)", "description": "string" }],
+    "skillTopics": [{ "name": "string (kebab-case)", "description": "string (what this skill does and WHEN to use it \u2014 include trigger phrases)" }],
     "rules": [{ "filename": "string.mdc", "content": "string (with frontmatter)" }]
   },
   "copilot": {
@@ -2523,6 +2529,7 @@ Rules:
 - Reference actual commands, paths, and packages from the project context provided.
 - Do NOT include YAML frontmatter \u2014 it will be generated separately.
 - Be specific to THIS project \u2014 avoid generic advice. The skill should produce code that looks identical to what's already in the codebase.
+- If the project context does not contain enough code examples for this skill topic, generate the skill based on the detected frameworks and conventions rather than inventing patterns. Prefer fewer, grounded instructions over many speculative ones.
 
 Description field formula: [What it does] + [When to use it with trigger phrases] + [Key capabilities]. Include negative triggers ("Do NOT use for X") to prevent over-triggering.
 
@@ -2569,32 +2576,40 @@ Rules:
 - Update the "fileDescriptions" to reflect any changes you make.
 
 Quality constraints \u2014 your changes are scored, so do not break these:
-- CLAUDE.md / AGENTS.md: MUST stay under 150 lines. If adding content, remove less important lines to stay within budget.
+- CLAUDE.md / AGENTS.md: MUST stay under 150 lines. If adding content, remove less important lines to stay within budget. Do not refuse the user's request \u2014 make the change and trim elsewhere.
 - Avoid vague instructions ("follow best practices", "write clean code", "ensure quality").
 - Do NOT add directory tree listings in code blocks.
+- Do NOT remove existing code blocks \u2014 they contribute to the executable content score.
 - Use backticks for every file path, command, and identifier.
 - Keep skill content under 150 lines, focused on actionable instructions.
 - Only reference file paths that actually exist in the project.`;
-var REFRESH_SYSTEM_PROMPT = `You are an expert at maintaining coding project documentation. Your job is to update existing documentation files based on code changes (git diffs).
+var REFRESH_SYSTEM_PROMPT = `You are an expert at maintaining coding project documentation. Your job is to apply minimal, surgical updates to existing documentation files based on code changes (git diffs).
 
 You will receive:
 1. Git diffs showing what code changed
-2. Current contents of documentation files (CLAUDE.md, README.md, skills, cursor rules)
-3. Project context (languages, frameworks)
-
-Rules:
-- Only update docs where the diffs clearly warrant a change
-- Preserve existing style, tone, structure, and formatting
-- Be conservative \u2014 don't rewrite sections that aren't affected by the changes
-- Don't add speculative or aspirational content
+2. Current contents of documentation files (CLAUDE.md, README.md, skills, cursor rules, copilot instructions)
+3. Project context (languages, frameworks, file tree)
+
+CONSERVATIVE UPDATE means:
+- Touch ONLY the specific lines/sections affected by the diff
+- If a command was renamed in the diff, update that command in the docs \u2014 don't rewrite the surrounding section
+- If a file was added/removed/renamed, update the architecture section \u2014 don't restructure it
+- If nothing in the diff affects a doc file, return null for it
+- NEVER add new sections, new prose, or new explanations that weren't in the original
+- NEVER remove code blocks, backtick references, or architecture paths unless the diff deleted them
+- NEVER replace specific paths/commands with generic prose
+
+Quality constraints (the output is scored deterministically):
+- CLAUDE.md / AGENTS.md: MUST stay under 150 lines. If the diff adds content, trim the least important lines elsewhere.
+- Keep 3+ code blocks with executable commands \u2014 do not remove code blocks
+- Every file path, command, and identifier must be in backticks
+- ONLY reference file paths that exist in the provided file tree \u2014 do NOT invent paths
+- Preserve the existing structure (headings, bullet style, formatting)
+
+Managed content:
 - Keep managed blocks (<!-- caliber:managed --> ... <!-- /caliber:managed -->) intact
-- Do NOT modify CALIBER_LEARNINGS.md \u2014 it is managed separately by the learning system
+- Do NOT modify CALIBER_LEARNINGS.md \u2014 it is managed separately
 - Preserve any references to CALIBER_LEARNINGS.md in CLAUDE.md
-- If a doc doesn't need updating, return null for it
-- For CLAUDE.md: update commands, architecture notes, conventions, key files if the diffs affect them. Keep under 150 lines.
-- For README.md: update setup instructions, API docs, or feature descriptions if affected
-- Only reference file paths that exist in the project
-- Use backticks for all file paths, commands, and identifiers
 
 Return a JSON object with this exact shape:
 {
@@ -2618,15 +2633,8 @@ You receive a chronological sequence of events from a Claude Code session. Most
 
 Your job is to find OPERATIONAL patterns \u2014 things that went wrong and how they were fixed, commands that required specific flags or configuration, APIs that needed a particular approach to work. Focus on the WORKFLOW, not the code logic.
 
-Look for:
-
-1. **Failure \u2192 Recovery sequences**: A tool call failed, then a different approach succeeded. Document what works and what doesn't. Example: an API call failed with one config but succeeded with different headers or parameters.
-2. **Environment gotchas**: Commands that need specific env vars, flags, or preconditions to work in this project.
-3. **Retry patterns**: When something had to be called multiple times with different arguments before succeeding.
-4. **Project-specific commands**: The correct way to build, test, lint, deploy \u2014 especially if it differs from defaults.
-5. **File/path traps**: Paths that are misleading, files that shouldn't be edited, directories with unexpected structure.
-6. **Configuration quirks**: Settings, flags, or arguments that are required but non-obvious.
-7. **User corrections**: The user explicitly told the AI what's wrong, what to use instead, or what to avoid. Look for phrases like "no, use X instead of Y", "don't touch/edit/modify X", "that's wrong, you need to...", "always/never do X in this project", "stop, that file is...". These are the HIGHEST VALUE signals \u2014 they represent direct human feedback about project-specific requirements. If a user correction contradicts a pattern you'd otherwise extract, the correction wins.
+CRITICAL FILTER \u2014 apply this to every potential learning before including it:
+The litmus test: "Would a different developer, working on a DIFFERENT task in this same repo next week, benefit from knowing this?" If the answer is no \u2014 if it only matters for the exact problem being debugged today \u2014 do NOT include it.
 
 DO NOT extract:
 - Descriptions of what the code does or how features work (e.g. "compression removes comments" or "skeleton extraction creates outlines")
@@ -2637,7 +2645,15 @@ DO NOT extract:
 - **Session-specific file paths, worktree locations, or branch names** \u2014 these are ephemeral and won't apply to future sessions
 - **Implementation details of a feature being built** \u2014 the learning should be about HOW to work in this project, not WHAT was built
 
-The litmus test for every learning: "Would a different developer, working on a DIFFERENT task in this same repo next week, benefit from knowing this?" If the answer is no \u2014 if it only matters for the exact problem being debugged today \u2014 do NOT include it.
+Look for:
+
+1. **Failure \u2192 Recovery sequences**: A tool call failed, then a different approach succeeded. Document what works and what doesn't. Example: an API call failed with one config but succeeded with different headers or parameters.
+2. **Environment gotchas**: Commands that need specific env vars, flags, or preconditions to work in this project.
+3. **Retry patterns**: When something had to be called multiple times with different arguments before succeeding.
+4. **Project-specific commands**: The correct way to build, test, lint, deploy \u2014 especially if it differs from defaults.
+5. **File/path traps**: Paths that are misleading, files that shouldn't be edited, directories with unexpected structure.
+6. **Configuration quirks**: Settings, flags, or arguments that are required but non-obvious.
+7. **User corrections**: The user explicitly told the AI what's wrong, what to use instead, or what to avoid. Look for phrases like "no, use X instead of Y", "don't touch/edit/modify X", "that's wrong, you need to...", "always/never do X in this project", "stop, that file is...". These are the HIGHEST VALUE signals \u2014 they represent direct human feedback about project-specific requirements. If a user correction contradicts a pattern you'd otherwise extract, the correction wins.
 
 From these observations, produce:
 
@@ -2716,6 +2732,10 @@ Be thorough \u2014 reason from:
 - File extensions and their frequency distribution
 - Directory structure and naming conventions
 - Configuration files (e.g. next.config.js implies Next.js, .tf files imply Terraform + cloud providers)
+- Package manager lockfiles (pnpm-lock.yaml \u2192 pnpm, yarn.lock \u2192 yarn, bun.lockb \u2192 bun, package-lock.json \u2192 npm)
+- Database/ORM files (schema.prisma \u2192 Prisma, drizzle.config.ts \u2192 Drizzle, knexfile \u2192 Knex, .sql files)
+- Test framework configs (vitest.config.ts \u2192 Vitest, jest.config.js \u2192 Jest, .mocharc \u2192 Mocha, cypress.config \u2192 Cypress)
+- Monorepo tools (nx.json \u2192 Nx, turbo.json \u2192 Turborepo, lerna.json \u2192 Lerna)
 - Infrastructure-as-code files (Terraform, CloudFormation, Pulumi, Dockerfiles, k8s manifests)
 - CI/CD configs (.github/workflows, .gitlab-ci.yml, Jenkinsfile)
 
@@ -3616,15 +3636,15 @@ init_config();
 // src/utils/dependencies.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { join as join2 } from "path";
-function readFileOrNull2(path39) {
+function readFileOrNull2(path40) {
   try {
-    return readFileSync2(path39, "utf-8");
+    return readFileSync2(path40, "utf-8");
   } catch {
     return null;
   }
 }
-function readJsonOrNull(path39) {
-  const content = readFileOrNull2(path39);
+function readJsonOrNull(path40) {
+  const content = readFileOrNull2(path40);
   if (!content) return null;
   try {
     return JSON.parse(content);
@@ -6181,7 +6201,7 @@ var AGENT_DISPLAY_NAMES = {
   codex: "Codex"
 };
 var CATEGORY_LABELS = {
-  existence: { icon: "\u{1F4C1}", label: "FILES & SETUP" },
+  existence: { icon: "\u{1F4C1}", label: "FILES & CONFIG" },
   quality: { icon: "\u26A1", label: "QUALITY" },
   grounding: { icon: "\u{1F3AF}", label: "GROUNDING" },
   accuracy: { icon: "\u{1F50D}", label: "ACCURACY" },
@@ -7440,11 +7460,11 @@ function countIssuePoints(issues) {
 }
 async function scoreAndRefine(setup, dir, sessionHistory, callbacks) {
   const existsCache = /* @__PURE__ */ new Map();
-  const cachedExists = (path39) => {
-    const cached = existsCache.get(path39);
+  const cachedExists = (path40) => {
+    const cached = existsCache.get(path40);
     if (cached !== void 0) return cached;
-    const result = existsSync9(path39);
-    existsCache.set(path39, result);
+    const result = existsSync9(path40);
+    existsCache.set(path40, result);
     return result;
   };
   const projectStructure = collectProjectStructure(dir);
@@ -7459,7 +7479,7 @@ async function scoreAndRefine(setup, dir, sessionHistory, callbacks) {
       bestLostPoints = lostPoints;
     }
     if (lostPoints === 0) {
-      if (callbacks?.onStatus) callbacks.onStatus("Setup passes all scoring checks");
+      if (callbacks?.onStatus) callbacks.onStatus("Config passes all scoring checks");
       return bestSetup;
     }
     const pointIssues = issues.filter((i) => i.pointsLost > 0);
@@ -7469,7 +7489,7 @@ async function scoreAndRefine(setup, dir, sessionHistory, callbacks) {
     }
     const refined = await applyTargetedFixes(currentSetup, issues);
     if (!refined) {
-      if (callbacks?.onStatus) callbacks.onStatus("Refinement failed, keeping current setup");
+      if (callbacks?.onStatus) callbacks.onStatus("Refinement failed, keeping current config");
       return bestSetup;
     }
     sessionHistory.push({
@@ -7562,7 +7582,7 @@ Return ONLY the fixed content as a JSON object with keys ${targets.map((t) => `"
   }
 }
 async function runScoreRefineWithSpinner(setup, dir, sessionHistory) {
-  const spinner = ora2("Validating setup against scoring criteria...").start();
+  const spinner = ora2("Validating config against scoring criteria...").start();
   try {
     const refined = await scoreAndRefine(setup, dir, sessionHistory, {
       onStatus: (msg) => {
@@ -7570,9 +7590,9 @@ async function runScoreRefineWithSpinner(setup, dir, sessionHistory) {
       }
     });
     if (refined !== setup) {
-      spinner.succeed("Setup refined based on scoring feedback");
+      spinner.succeed("Config refined based on scoring feedback");
     } else {
-      spinner.succeed("Setup passes scoring validation");
+      spinner.succeed("Config passes scoring validation");
     }
     return refined;
   } catch (err) {
@@ -8127,7 +8147,7 @@ var REFINE_MESSAGES = [
   "Rebalancing permissions and tool settings...",
   "Refining skills and workflows...",
   "Updating rules to match your preferences...",
-  "Finalizing the revised setup..."
+  "Finalizing the revised config..."
 ];
 var SpinnerMessages = class {
   spinner;
@@ -8297,10 +8317,10 @@ async function refineLoop(currentSetup, sessionHistory, summarizeSetup2, printSu
     if (!isValid) {
       console.log(chalk11.dim("  This doesn't look like a config change request."));
       console.log(chalk11.dim("  Describe what to add, remove, or modify in your configs."));
-      console.log(chalk11.dim('  Type "done" to accept the current setup.\n'));
+      console.log(chalk11.dim('  Type "done" to accept the current config.\n'));
       continue;
     }
-    const refineSpinner = ora3("Refining setup...").start();
+    const refineSpinner = ora3("Refining config...").start();
     const refineMessages = new SpinnerMessages(refineSpinner, REFINE_MESSAGES);
     refineMessages.start();
     const refined = await refineSetup(setup, message, sessionHistory);
@@ -8312,12 +8332,12 @@ async function refineLoop(currentSetup, sessionHistory, summarizeSetup2, printSu
         role: "assistant",
         content: summarizeSetup2("Applied changes", refined)
       });
-      refineSpinner.succeed("Setup updated");
+      refineSpinner.succeed("Config updated");
       printSummary(refined);
       console.log(chalk11.dim('Type "done" to accept, or describe more changes.'));
     } else {
       refineSpinner.fail("Refinement failed \u2014 could not parse AI response.");
-      console.log(chalk11.dim('Try rephrasing your request, or type "done" to keep the current setup.'));
+      console.log(chalk11.dim('Try rephrasing your request, or type "done" to keep the current config.'));
     }
   }
 }
@@ -8366,7 +8386,7 @@ function printSetupSummary(setup) {
   const fileDescriptions = setup.fileDescriptions;
   const deletions = setup.deletions;
   console.log("");
-  console.log(chalk12.bold("  Your tailored setup:\n"));
+  console.log(chalk12.bold("  Your tailored config:\n"));
   const getDescription = (filePath) => {
     return fileDescriptions?.[filePath];
   };
@@ -8595,6 +8615,7 @@ Only dismiss checks that truly don't apply. Examples:
 - "Build/test/lint commands" for a GitOps/Helm/Terraform/config repo with no build system
 - "Build/test/lint commands" for a repo with only YAML, HCL, or config files and no package.json/Makefile
 - "Dependency coverage" for a repo with no package manager
+- "Skills configured" for a documentation-only or data-science notebook repo with no repeating code patterns
 
 Do NOT dismiss checks that could reasonably apply even if the project doesn't use them yet.
 
@@ -8607,7 +8628,7 @@ Top files: ${topFiles}
 
 Failing checks:
 ${JSON.stringify(checkList, null, 2)}`,
-      maxTokens: 300,
+      maxTokens: 500,
       ...fastModel ? { model: fastModel } : {}
     });
     if (!Array.isArray(result.dismissed)) return [];
@@ -8617,6 +8638,68 @@ ${JSON.stringify(checkList, null, 2)}`,
   }
 }
 
+// src/scoring/history.ts
+import fs31 from "fs";
+import path24 from "path";
+var HISTORY_FILE = "score-history.jsonl";
+var MAX_ENTRIES = 500;
+var TRIM_THRESHOLD = MAX_ENTRIES + 50;
+function historyFilePath() {
+  return path24.join(CALIBER_DIR, HISTORY_FILE);
+}
+function recordScore(result, trigger) {
+  const entry = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    score: result.score,
+    grade: result.grade,
+    targetAgent: [...result.targetAgent],
+    trigger
+  };
+  try {
+    fs31.mkdirSync(CALIBER_DIR, { recursive: true });
+    const filePath = historyFilePath();
+    fs31.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+    const stat = fs31.statSync(filePath);
+    if (stat.size > TRIM_THRESHOLD * 120) {
+      const lines = fs31.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
+      if (lines.length > MAX_ENTRIES) {
+        fs31.writeFileSync(filePath, lines.slice(-MAX_ENTRIES).join("\n") + "\n");
+      }
+    }
+  } catch {
+  }
+}
+function readScoreHistory() {
+  const filePath = historyFilePath();
+  try {
+    const content = fs31.readFileSync(filePath, "utf-8");
+    const entries = [];
+    for (const line of content.split("\n")) {
+      if (!line) continue;
+      try {
+        entries.push(JSON.parse(line));
+      } catch {
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+function getScoreTrend(entries) {
+  if (entries.length < 2) return null;
+  const first = entries[0];
+  const last = entries[entries.length - 1];
+  const delta = last.score - first.score;
+  return {
+    direction: delta > 0 ? "up" : delta < 0 ? "down" : "stable",
+    delta,
+    entries: entries.length,
+    firstScore: first.score,
+    lastScore: last.score
+  };
+}
+
 // src/commands/init.ts
 function log(verbose, ...args) {
   if (verbose) console.log(chalk14.dim(`  [verbose] ${args.map(String).join(" ")}`));
@@ -8637,7 +8720,7 @@ async function initCommand(options) {
     console.log(chalk14.dim("  Scan your project and generate tailored config files for"));
     console.log(chalk14.dim("  Claude Code, Cursor, Codex, and GitHub Copilot.\n"));
     console.log(title.bold("  How it works:\n"));
-    console.log(chalk14.dim("  1. Setup      Connect your LLM provider and select your agents"));
+    console.log(chalk14.dim("  1. Connect    Link your LLM provider and select your agents"));
     console.log(chalk14.dim("  2. Engine     Detect stack, generate configs & skills in parallel"));
     console.log(chalk14.dim("  3. Review     See all changes \u2014 accept, refine, or decline"));
     console.log(chalk14.dim("  4. Finalize   Score check and auto-sync hooks\n"));
@@ -8650,7 +8733,7 @@ async function initCommand(options) {
     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/4 \u2014 Setup\n"));
+  console.log(title.bold("  Step 1/4 \u2014 Connect\n"));
   let config = loadConfig();
   if (!config) {
     console.log(chalk14.dim("  No LLM provider configured yet.\n"));
@@ -8659,7 +8742,7 @@ async function initCommand(options) {
     });
     config = loadConfig();
     if (!config) {
-      console.log(chalk14.red("  Setup was cancelled or failed.\n"));
+      console.log(chalk14.red("  Configuration cancelled or failed.\n"));
       throw new Error("__exit__");
     }
     console.log(chalk14.green("  \u2713 Provider saved\n"));
@@ -8670,7 +8753,7 @@ async function initCommand(options) {
   const modelLine = fastModel ? `  Provider: ${config.provider} | Model: ${displayModel} | Scan: ${fastModel}` : `  Provider: ${config.provider} | Model: ${displayModel}`;
   console.log(chalk14.dim(modelLine + "\n"));
   if (report) {
-    report.markStep("Provider setup");
+    report.markStep("Provider connection");
     report.addSection("LLM Provider", `- **Provider**: ${config.provider}
 - **Model**: ${displayModel}
 - **Fast model**: ${fastModel || "none"}`);
@@ -8691,7 +8774,7 @@ async function initCommand(options) {
 `));
   trackInitAgentSelected(targetAgent, agentAutoDetected);
   let baselineScore = computeLocalScore(process.cwd(), targetAgent);
-  console.log(chalk14.dim("\n  Current setup score:"));
+  console.log(chalk14.dim("\n  Current config score:"));
   displayScoreSummary(baselineScore);
   if (options.verbose) {
     for (const c of baselineScore.checks) {
@@ -8720,7 +8803,7 @@ async function initCommand(options) {
   const failingCount = baselineScore.checks.filter((c) => !c.passed).length;
   if (hasExistingConfig && baselineScore.score === 100) {
     trackInitScoreComputed(baselineScore.score, passingCount, failingCount, true);
-    console.log(chalk14.bold.green("  Your setup is already optimal \u2014 nothing to change.\n"));
+    console.log(chalk14.bold.green("  Your config is already optimal \u2014 nothing to change.\n"));
     console.log(chalk14.dim("  Run ") + chalk14.hex("#83D1EB")("caliber init --force") + chalk14.dim(" to regenerate anyway.\n"));
     if (!options.force) return;
   }
@@ -8757,7 +8840,7 @@ async function initCommand(options) {
   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 setup", { pipelineLabel: "Validate" });
+  const TASK_SCORE_REFINE = display.add("Validating & refining config", { pipelineLabel: "Validate" });
   display.start();
   display.enableWaitingContent();
   try {
@@ -8905,7 +8988,7 @@ async function initCommand(options) {
         display.update(TASK_SCORE_REFINE, "done", "Skipped");
       }
     } else {
-      display.update(TASK_SCORE_REFINE, "failed", "No setup to validate");
+      display.update(TASK_SCORE_REFINE, "failed", "No config to validate");
     }
   } catch (err) {
     display.stop();
@@ -8926,7 +9009,7 @@ async function initCommand(options) {
   Done in ${timeStr}
 `));
   if (!generatedSetup) {
-    console.log(chalk14.red("  Failed to generate setup."));
+    console.log(chalk14.red("  Failed to generate config."));
     writeErrorLog(config, rawOutput, void 0, genStopReason);
     if (rawOutput) {
       console.log(chalk14.dim("\nRaw LLM output (JSON parse failed):"));
@@ -8936,7 +9019,7 @@ async function initCommand(options) {
   }
   if (report) {
     if (rawOutput) report.addCodeBlock("Generation: Raw LLM Response", rawOutput);
-    report.addJson("Generation: Parsed Setup", generatedSetup);
+    report.addJson("Generation: Parsed Config", generatedSetup);
   }
   log(options.verbose, `Generation completed: ${elapsedMs}ms, stopReason: ${genStopReason || "end_turn"}`);
   console.log(title.bold("  Step 3/4 \u2014 Review\n"));
@@ -8999,7 +9082,7 @@ async function initCommand(options) {
   }
   cleanupStaging();
   if (action === "decline") {
-    console.log(chalk14.dim("Setup declined. No files were modified."));
+    console.log(chalk14.dim("Declined. No files were modified."));
     return;
   }
   console.log(title.bold("\n  Step 4/4 \u2014 Finalize\n"));
@@ -9011,7 +9094,7 @@ async function initCommand(options) {
   const { default: ora9 } = await import("ora");
   const writeSpinner = ora9("Writing config files...").start();
   try {
-    if (targetAgent.includes("codex") && !fs31.existsSync("AGENTS.md") && !generatedSetup.codex) {
+    if (targetAgent.includes("codex") && !fs32.existsSync("AGENTS.md") && !generatedSetup.codex) {
       const claude = generatedSetup.claude;
       const cursor = generatedSetup.cursor;
       const agentRefs = [];
@@ -9083,6 +9166,7 @@ ${agentRefs.join(" ")}
 |-------|--------|--------|-----|
 ` + afterScore.checks.map((c) => `| ${c.name} | ${c.passed ? "Yes" : "No"} | ${c.earnedPoints} | ${c.maxPoints} |`).join("\n"));
   }
+  recordScore(afterScore, "init");
   displayScoreDelta(baselineScore, afterScore);
   if (options.verbose) {
     log(options.verbose, `Final score: ${afterScore.score}/100`);
@@ -9130,12 +9214,12 @@ ${agentRefs.join(" ")}
       if (targetAgent.includes("cursor")) installCursorLearningHooks();
     }
   }
-  console.log(chalk14.bold.green("\n  Setup complete!"));
+  console.log(chalk14.bold.green("\n  Configuration complete!"));
   console.log(chalk14.dim("  Your AI agents now understand your project's architecture, build commands,"));
   console.log(chalk14.dim("  testing patterns, and conventions. All changes are backed up automatically.\n"));
   const done = chalk14.green("\u2713");
   const skip = chalk14.dim("\u2013");
-  console.log(chalk14.bold("  What was set up:\n"));
+  console.log(chalk14.bold("  What was configured:\n"));
   console.log(`    ${done}  Config generated          ${title("caliber score")} ${chalk14.dim("for full breakdown")}`);
   console.log(`    ${done}  Docs auto-refresh        ${chalk14.dim("agents run caliber refresh before commits")}`);
   if (hasLearnableAgent) {
@@ -9160,9 +9244,9 @@ ${agentRefs.join(" ")}
   }
   if (report) {
     report.markStep("Finished");
-    const reportPath = path24.join(process.cwd(), ".caliber", "debug-report.md");
+    const reportPath = path25.join(process.cwd(), ".caliber", "debug-report.md");
     report.write(reportPath);
-    console.log(chalk14.dim(`  Debug report written to ${path24.relative(process.cwd(), reportPath)}
+    console.log(chalk14.dim(`  Debug report written to ${path25.relative(process.cwd(), reportPath)}
 `));
   }
 }
@@ -9171,7 +9255,7 @@ ${agentRefs.join(" ")}
 import chalk15 from "chalk";
 import ora4 from "ora";
 function undoCommand() {
-  const spinner = ora4("Reverting setup...").start();
+  const spinner = ora4("Reverting config changes...").start();
   try {
     const { restored, removed } = undoSetup();
     if (restored.length === 0 && removed.length === 0) {
@@ -9179,7 +9263,7 @@ function undoCommand() {
       return;
     }
     trackUndoExecuted();
-    spinner.succeed("Setup reverted successfully.\n");
+    spinner.succeed("Config reverted successfully.\n");
     if (restored.length > 0) {
       console.log(chalk15.cyan("  Restored from backup:"));
       for (const file of restored) {
@@ -9201,7 +9285,7 @@ function undoCommand() {
 
 // src/commands/status.ts
 import chalk16 from "chalk";
-import fs32 from "fs";
+import fs33 from "fs";
 init_config();
 async function statusCommand(options) {
   const config = loadConfig();
@@ -9222,13 +9306,13 @@ async function statusCommand(options) {
     console.log(`  LLM: ${chalk16.yellow("Not configured")} \u2014 run ${chalk16.hex("#83D1EB")("caliber config")}`);
   }
   if (!manifest) {
-    console.log(`  Setup: ${chalk16.dim("No setup applied")}`);
+    console.log(`  Config: ${chalk16.dim("No config applied")}`);
     console.log(chalk16.dim("\n  Run ") + chalk16.hex("#83D1EB")("caliber init") + chalk16.dim(" to get started.\n"));
     return;
   }
   console.log(`  Files managed: ${chalk16.cyan(manifest.entries.length.toString())}`);
   for (const entry of manifest.entries) {
-    const exists = fs32.existsSync(entry.path);
+    const exists = fs33.existsSync(entry.path);
     const icon = exists ? chalk16.green("\u2713") : chalk16.red("\u2717");
     console.log(`    ${icon} ${entry.path} (${entry.action})`);
   }
@@ -9249,7 +9333,7 @@ async function regenerateCommand(options) {
   }
   const manifest = readManifest();
   if (!manifest) {
-    console.log(chalk17.yellow("No existing setup found. Run ") + chalk17.hex("#83D1EB")("caliber init") + chalk17.yellow(" first."));
+    console.log(chalk17.yellow("No existing config found. Run ") + chalk17.hex("#83D1EB")("caliber init") + chalk17.yellow(" first."));
     throw new Error("__exit__");
   }
   const targetAgent = readState()?.targetAgent ?? ["claude", "cursor"];
@@ -9260,10 +9344,10 @@ async function regenerateCommand(options) {
   const baselineScore = computeLocalScore(process.cwd(), targetAgent);
   displayScoreSummary(baselineScore);
   if (baselineScore.score === 100) {
-    console.log(chalk17.green("  Your setup is already at 100/100 \u2014 nothing to regenerate.\n"));
+    console.log(chalk17.green("  Your config is already at 100/100 \u2014 nothing to regenerate.\n"));
     return;
   }
-  const genSpinner = ora5("Regenerating setup...").start();
+  const genSpinner = ora5("Regenerating config...").start();
   const genMessages = new SpinnerMessages(genSpinner, GENERATION_MESSAGES, { showElapsedTime: true });
   genMessages.start();
   let generatedSetup = null;
@@ -9294,10 +9378,10 @@ async function regenerateCommand(options) {
   }
   genMessages.stop();
   if (!generatedSetup) {
-    genSpinner.fail("Failed to regenerate setup.");
+    genSpinner.fail("Failed to regenerate config.");
     throw new Error("__exit__");
   }
-  genSpinner.succeed("Setup regenerated");
+  genSpinner.succeed("Config regenerated");
   generatedSetup = await runScoreRefineWithSpinner(generatedSetup, process.cwd(), []);
   const setupFiles = collectSetupFiles(generatedSetup, targetAgent);
   const staged = stageFiles(setupFiles, process.cwd());
@@ -9324,7 +9408,7 @@ async function regenerateCommand(options) {
     await openReview(reviewMethod, staged.stagedFiles);
   }
   const action = await select6({
-    message: "Apply regenerated setup?",
+    message: "Apply regenerated config?",
     choices: [
       { name: "Accept and apply", value: "accept" },
       { name: "Decline", value: "decline" }
@@ -9383,21 +9467,21 @@ async function regenerateCommand(options) {
 }
 
 // src/commands/score.ts
-import fs33 from "fs";
+import fs34 from "fs";
 import os7 from "os";
-import path25 from "path";
+import path26 from "path";
 import { execFileSync as execFileSync2 } from "child_process";
 import chalk18 from "chalk";
 var CONFIG_FILES = ["CLAUDE.md", "AGENTS.md", ".cursorrules", "CALIBER_LEARNINGS.md"];
 var CONFIG_DIRS = [".claude", ".cursor"];
 function scoreBaseRef(ref, target) {
   if (!/^[\w.\-\/~^@{}]+$/.test(ref)) return null;
-  const tmpDir = fs33.mkdtempSync(path25.join(os7.tmpdir(), "caliber-compare-"));
+  const tmpDir = fs34.mkdtempSync(path26.join(os7.tmpdir(), "caliber-compare-"));
   try {
     for (const file of CONFIG_FILES) {
       try {
         const content = execFileSync2("git", ["show", `${ref}:${file}`], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
-        fs33.writeFileSync(path25.join(tmpDir, file), content);
+        fs34.writeFileSync(path26.join(tmpDir, file), content);
       } catch {
       }
     }
@@ -9405,10 +9489,10 @@ function scoreBaseRef(ref, target) {
       try {
         const files = execFileSync2("git", ["ls-tree", "-r", "--name-only", ref, `${dir}/`], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim().split("\n").filter(Boolean);
         for (const file of files) {
-          const filePath = path25.join(tmpDir, file);
-          fs33.mkdirSync(path25.dirname(filePath), { recursive: true });
+          const filePath = path26.join(tmpDir, file);
+          fs34.mkdirSync(path26.dirname(filePath), { recursive: true });
           const content = execFileSync2("git", ["show", `${ref}:${file}`], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
-          fs33.writeFileSync(filePath, content);
+          fs34.writeFileSync(filePath, content);
         }
       } catch {
       }
@@ -9418,7 +9502,7 @@ function scoreBaseRef(ref, target) {
   } catch {
     return null;
   } finally {
-    fs33.rmSync(tmpDir, { recursive: true, force: true });
+    fs34.rmSync(tmpDir, { recursive: true, force: true });
   }
 }
 async function scoreCommand(options) {
@@ -9426,6 +9510,7 @@ async function scoreCommand(options) {
   const target = options.agent ?? readState()?.targetAgent;
   const result = computeLocalScore(dir, target);
   trackScoreComputed(result.score, target);
+  recordScore(result, "score");
   if (options.compare) {
     const baseResult = scoreBaseRef(options.compare, target);
     if (!baseResult) {
@@ -9468,9 +9553,9 @@ async function scoreCommand(options) {
   const separator = chalk18.gray("  " + "\u2500".repeat(53));
   console.log(separator);
   if (result.score < 40) {
-    console.log(chalk18.gray("  Run ") + chalk18.hex("#83D1EB")("caliber init") + chalk18.gray(" to generate a complete, optimized setup."));
+    console.log(chalk18.gray("  Run ") + chalk18.hex("#83D1EB")("caliber init") + chalk18.gray(" to generate a complete, optimized config."));
   } else if (result.score < 70) {
-    console.log(chalk18.gray("  Run ") + chalk18.hex("#83D1EB")("caliber init") + chalk18.gray(" to improve your setup."));
+    console.log(chalk18.gray("  Run ") + chalk18.hex("#83D1EB")("caliber init") + chalk18.gray(" to improve your config."));
   } else {
     console.log(chalk18.green("  Looking good!") + chalk18.gray(" Run ") + chalk18.hex("#83D1EB")("caliber regenerate") + chalk18.gray(" to rebuild from scratch."));
   }
@@ -9478,8 +9563,8 @@ async function scoreCommand(options) {
 }
 
 // src/commands/refresh.ts
-import fs37 from "fs";
-import path29 from "path";
+import fs38 from "fs";
+import path30 from "path";
 import chalk19 from "chalk";
 import ora6 from "ora";
 
@@ -9557,48 +9642,48 @@ function collectDiff(lastSha) {
 }
 
 // src/writers/refresh.ts
-import fs34 from "fs";
-import path26 from "path";
+import fs35 from "fs";
+import path27 from "path";
 function writeRefreshDocs(docs) {
   const written = [];
   if (docs.claudeMd) {
-    fs34.writeFileSync("CLAUDE.md", appendLearningsBlock(appendPreCommitBlock(docs.claudeMd)));
+    fs35.writeFileSync("CLAUDE.md", appendLearningsBlock(appendPreCommitBlock(docs.claudeMd)));
     written.push("CLAUDE.md");
   }
   if (docs.readmeMd) {
-    fs34.writeFileSync("README.md", docs.readmeMd);
+    fs35.writeFileSync("README.md", docs.readmeMd);
     written.push("README.md");
   }
   if (docs.cursorrules) {
-    fs34.writeFileSync(".cursorrules", docs.cursorrules);
+    fs35.writeFileSync(".cursorrules", docs.cursorrules);
     written.push(".cursorrules");
   }
   if (docs.cursorRules) {
-    const rulesDir = path26.join(".cursor", "rules");
-    if (!fs34.existsSync(rulesDir)) fs34.mkdirSync(rulesDir, { recursive: true });
+    const rulesDir = path27.join(".cursor", "rules");
+    if (!fs35.existsSync(rulesDir)) fs35.mkdirSync(rulesDir, { recursive: true });
     for (const rule of docs.cursorRules) {
-      fs34.writeFileSync(path26.join(rulesDir, rule.filename), rule.content);
+      fs35.writeFileSync(path27.join(rulesDir, rule.filename), rule.content);
       written.push(`.cursor/rules/${rule.filename}`);
     }
   }
   if (docs.claudeSkills) {
-    const skillsDir = path26.join(".claude", "skills");
-    if (!fs34.existsSync(skillsDir)) fs34.mkdirSync(skillsDir, { recursive: true });
+    const skillsDir = path27.join(".claude", "skills");
+    if (!fs35.existsSync(skillsDir)) fs35.mkdirSync(skillsDir, { recursive: true });
     for (const skill of docs.claudeSkills) {
-      fs34.writeFileSync(path26.join(skillsDir, skill.filename), skill.content);
+      fs35.writeFileSync(path27.join(skillsDir, skill.filename), skill.content);
       written.push(`.claude/skills/${skill.filename}`);
     }
   }
   if (docs.copilotInstructions) {
-    fs34.mkdirSync(".github", { recursive: true });
-    fs34.writeFileSync(path26.join(".github", "copilot-instructions.md"), appendLearningsBlock(appendPreCommitBlock(docs.copilotInstructions)));
+    fs35.mkdirSync(".github", { recursive: true });
+    fs35.writeFileSync(path27.join(".github", "copilot-instructions.md"), appendLearningsBlock(appendPreCommitBlock(docs.copilotInstructions)));
     written.push(".github/copilot-instructions.md");
   }
   if (docs.copilotInstructionFiles) {
-    const instructionsDir = path26.join(".github", "instructions");
-    fs34.mkdirSync(instructionsDir, { recursive: true });
+    const instructionsDir = path27.join(".github", "instructions");
+    fs35.mkdirSync(instructionsDir, { recursive: true });
     for (const file of docs.copilotInstructionFiles) {
-      fs34.writeFileSync(path26.join(instructionsDir, file.filename), file.content);
+      fs35.writeFileSync(path27.join(instructionsDir, file.filename), file.content);
       written.push(`.github/instructions/${file.filename}`);
     }
   }
@@ -9624,6 +9709,12 @@ function buildRefreshPrompt(diff, existingDocs, projectContext, learnedSection,
   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.fileTree?.length) {
+    const tree = projectContext.fileTree.slice(0, 200);
+    parts.push(`
+File tree (${tree.length}/${projectContext.fileTree.length} \u2014 only reference paths from this list):
+${tree.join("\n")}`);
+  }
   parts.push(`
 Changed files: ${diff.changedFiles.join(", ")}`);
   parts.push(`Summary: ${diff.summary}`);
@@ -9678,8 +9769,8 @@ Changed files: ${diff.changedFiles.join(", ")}`);
 }
 
 // src/learner/writer.ts
-import fs35 from "fs";
-import path27 from "path";
+import fs36 from "fs";
+import path28 from "path";
 
 // src/learner/utils.ts
 var TYPE_PREFIX_RE = /^\*\*\[[^\]]+\]\*\*\s*/;
@@ -9796,20 +9887,20 @@ function deduplicateLearnedItems(existing, incoming) {
 }
 function writeLearnedSectionTo(filePath, header, existing, incoming, mode) {
   const { merged, newCount, newItems } = deduplicateLearnedItems(existing, incoming);
-  fs35.writeFileSync(filePath, header + merged + "\n");
-  if (mode) fs35.chmodSync(filePath, mode);
+  fs36.writeFileSync(filePath, header + merged + "\n");
+  if (mode) fs36.chmodSync(filePath, mode);
   return { newCount, newItems };
 }
 function writeLearnedSection(content) {
   return writeLearnedSectionTo(LEARNINGS_FILE, LEARNINGS_HEADER, readLearnedSection(), content);
 }
 function writeLearnedSkill(skill) {
-  const skillDir = path27.join(".claude", "skills", skill.name);
-  if (!fs35.existsSync(skillDir)) fs35.mkdirSync(skillDir, { recursive: true });
-  const skillPath = path27.join(skillDir, "SKILL.md");
-  if (!skill.isNew && fs35.existsSync(skillPath)) {
-    const existing = fs35.readFileSync(skillPath, "utf-8");
-    fs35.writeFileSync(skillPath, existing.trimEnd() + "\n\n" + skill.content);
+  const skillDir = path28.join(".claude", "skills", skill.name);
+  if (!fs36.existsSync(skillDir)) fs36.mkdirSync(skillDir, { recursive: true });
+  const skillPath = path28.join(skillDir, "SKILL.md");
+  if (!skill.isNew && fs36.existsSync(skillPath)) {
+    const existing = fs36.readFileSync(skillPath, "utf-8");
+    fs36.writeFileSync(skillPath, existing.trimEnd() + "\n\n" + skill.content);
   } else {
     const frontmatter = [
       "---",
@@ -9818,12 +9909,12 @@ function writeLearnedSkill(skill) {
       "---",
       ""
     ].join("\n");
-    fs35.writeFileSync(skillPath, frontmatter + skill.content);
+    fs36.writeFileSync(skillPath, frontmatter + skill.content);
   }
   return skillPath;
 }
 function writePersonalLearnedSection(content) {
-  if (!fs35.existsSync(AUTH_DIR)) fs35.mkdirSync(AUTH_DIR, { recursive: true });
+  if (!fs36.existsSync(AUTH_DIR)) fs36.mkdirSync(AUTH_DIR, { recursive: true });
   return writeLearnedSectionTo(PERSONAL_LEARNINGS_FILE, PERSONAL_LEARNINGS_HEADER, readPersonalLearnings(), content, 384);
 }
 function addLearning(bullet, scope = "project") {
@@ -9836,38 +9927,38 @@ function addLearning(bullet, scope = "project") {
   return { file: LEARNINGS_FILE, added: result.newCount > 0 };
 }
 function readPersonalLearnings() {
-  if (!fs35.existsSync(PERSONAL_LEARNINGS_FILE)) return null;
-  const content = fs35.readFileSync(PERSONAL_LEARNINGS_FILE, "utf-8");
+  if (!fs36.existsSync(PERSONAL_LEARNINGS_FILE)) return null;
+  const content = fs36.readFileSync(PERSONAL_LEARNINGS_FILE, "utf-8");
   const bullets = content.split("\n").filter((l) => l.startsWith("- ")).join("\n");
   return bullets || null;
 }
 function readLearnedSection() {
-  if (fs35.existsSync(LEARNINGS_FILE)) {
-    const content2 = fs35.readFileSync(LEARNINGS_FILE, "utf-8");
+  if (fs36.existsSync(LEARNINGS_FILE)) {
+    const content2 = fs36.readFileSync(LEARNINGS_FILE, "utf-8");
     const bullets = content2.split("\n").filter((l) => l.startsWith("- ")).join("\n");
     return bullets || null;
   }
   const claudeMdPath = "CLAUDE.md";
-  if (!fs35.existsSync(claudeMdPath)) return null;
-  const content = fs35.readFileSync(claudeMdPath, "utf-8");
+  if (!fs36.existsSync(claudeMdPath)) return null;
+  const content = fs36.readFileSync(claudeMdPath, "utf-8");
   const startIdx = content.indexOf(LEARNED_START);
   const endIdx = content.indexOf(LEARNED_END);
   if (startIdx === -1 || endIdx === -1) return null;
   return content.slice(startIdx + LEARNED_START.length, endIdx).trim() || null;
 }
 function migrateInlineLearnings() {
-  if (fs35.existsSync(LEARNINGS_FILE)) return false;
+  if (fs36.existsSync(LEARNINGS_FILE)) return false;
   const claudeMdPath = "CLAUDE.md";
-  if (!fs35.existsSync(claudeMdPath)) return false;
-  const content = fs35.readFileSync(claudeMdPath, "utf-8");
+  if (!fs36.existsSync(claudeMdPath)) return false;
+  const content = fs36.readFileSync(claudeMdPath, "utf-8");
   const startIdx = content.indexOf(LEARNED_START);
   const endIdx = content.indexOf(LEARNED_END);
   if (startIdx === -1 || endIdx === -1) return false;
   const section = content.slice(startIdx + LEARNED_START.length, endIdx).trim();
   if (!section) return false;
-  fs35.writeFileSync(LEARNINGS_FILE, LEARNINGS_HEADER + section + "\n");
+  fs36.writeFileSync(LEARNINGS_FILE, LEARNINGS_HEADER + section + "\n");
   const cleaned = content.slice(0, startIdx) + content.slice(endIdx + LEARNED_END.length);
-  fs35.writeFileSync(claudeMdPath, cleaned.replace(/\n{3,}/g, "\n\n").trim() + "\n");
+  fs36.writeFileSync(claudeMdPath, cleaned.replace(/\n{3,}/g, "\n\n").trim() + "\n");
   return true;
 }
 
@@ -9879,11 +9970,11 @@ function log2(quiet, ...args) {
 function discoverGitRepos(parentDir) {
   const repos = [];
   try {
-    const entries = fs37.readdirSync(parentDir, { withFileTypes: true });
+    const entries = fs38.readdirSync(parentDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-      const childPath = path29.join(parentDir, entry.name);
-      if (fs37.existsSync(path29.join(childPath, ".git"))) {
+      const childPath = path30.join(parentDir, entry.name);
+      if (fs38.existsSync(path30.join(childPath, ".git"))) {
         repos.push(childPath);
       }
     }
@@ -9891,11 +9982,19 @@ function discoverGitRepos(parentDir) {
   }
   return repos.sort();
 }
+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 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.`));
+      return;
+    }
+  }
   const diff = collectDiff(lastSha);
   const currentSha = getCurrentHeadSha();
   if (!diff.hasChanges) {
@@ -9912,23 +10011,32 @@ async function refreshSingleRepo(repoDir, options) {
   const projectContext = {
     languages: fingerprint.languages,
     frameworks: fingerprint.frameworks,
-    packageName: fingerprint.packageName
+    packageName: fingerprint.packageName,
+    fileTree: fingerprint.fileTree
   };
   const workspaces = getDetectedWorkspaces(repoDir);
   const sources2 = resolveAllSources(repoDir, [], workspaces);
-  const response = await refreshDocs(
-    {
-      committed: diff.committedDiff,
-      staged: diff.stagedDiff,
-      unstaged: diff.unstagedDiff,
-      changedFiles: diff.changedFiles,
-      summary: diff.summary
-    },
-    existingDocs,
-    projectContext,
-    learnedSection,
-    sources2.length > 0 ? sources2 : void 0
-  );
+  const diffPayload = {
+    committed: diff.committedDiff,
+    staged: diff.stagedDiff,
+    unstaged: diff.unstagedDiff,
+    changedFiles: diff.changedFiles,
+    summary: diff.summary
+  };
+  const sourcesPayload = sources2.length > 0 ? sources2 : void 0;
+  let response;
+  try {
+    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);
+    } catch {
+      spinner?.fail(`${prefix}Refresh failed after retry`);
+      throw firstErr;
+    }
+  }
   if (!response.docsUpdated || response.docsUpdated.length === 0) {
     spinner?.succeed(`${prefix}No doc updates needed`);
     if (currentSha) {
@@ -9947,8 +10055,41 @@ async function refreshSingleRepo(repoDir, options) {
     }
     return;
   }
+  const targetAgent = state?.targetAgent ?? detectTargetAgent(repoDir);
+  const preScore = computeLocalScore(repoDir, targetAgent);
+  const filesToWrite = response.docsUpdated || [];
+  const preRefreshContents = /* @__PURE__ */ new Map();
+  for (const filePath of filesToWrite) {
+    const fullPath = path30.resolve(repoDir, filePath);
+    try {
+      preRefreshContents.set(filePath, fs38.readFileSync(fullPath, "utf-8"));
+    } catch {
+      preRefreshContents.set(filePath, null);
+    }
+  }
   const written = writeRefreshDocs(response.updatedDocs);
   trackRefreshCompleted(written.length, Date.now());
+  const postScore = computeLocalScore(repoDir, targetAgent);
+  if (postScore.score < preScore.score) {
+    for (const [filePath, content] of preRefreshContents) {
+      const fullPath = path30.resolve(repoDir, filePath);
+      if (content === null) {
+        try {
+          fs38.unlinkSync(fullPath);
+        } catch {
+        }
+      } else {
+        fs38.writeFileSync(fullPath, content);
+      }
+    }
+    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() });
+    }
+    return;
+  }
+  recordScore(postScore, "refresh");
   spinner?.succeed(`${prefix}Updated ${written.length} doc${written.length === 1 ? "" : "s"}`);
   for (const file of written) {
     log2(quiet, `  ${chalk19.green("\u2713")} ${file}`);
@@ -9993,7 +10134,7 @@ async function refreshCommand(options) {
 `));
     const originalDir = process.cwd();
     for (const repo of repos) {
-      const repoName = path29.basename(repo);
+      const repoName = path30.basename(repo);
       try {
         process.chdir(repo);
         await refreshSingleRepo(repo, { ...options, label: repoName });
@@ -10014,31 +10155,31 @@ async function refreshCommand(options) {
 
 // src/commands/hooks.ts
 import chalk20 from "chalk";
-import fs39 from "fs";
+import fs40 from "fs";
 
 // src/lib/hooks.ts
 init_resolve_caliber();
-import fs38 from "fs";
-import path30 from "path";
+import fs39 from "fs";
+import path31 from "path";
 import { execSync as execSync15 } from "child_process";
-var SETTINGS_PATH2 = path30.join(".claude", "settings.json");
+var SETTINGS_PATH2 = path31.join(".claude", "settings.json");
 var REFRESH_TAIL = "refresh --quiet";
 var HOOK_DESCRIPTION = "Caliber: auto-refreshing docs based on code changes";
 function getHookCommand() {
   return `${resolveCaliber()} ${REFRESH_TAIL}`;
 }
 function readSettings2() {
-  if (!fs38.existsSync(SETTINGS_PATH2)) return {};
+  if (!fs39.existsSync(SETTINGS_PATH2)) return {};
   try {
-    return JSON.parse(fs38.readFileSync(SETTINGS_PATH2, "utf-8"));
+    return JSON.parse(fs39.readFileSync(SETTINGS_PATH2, "utf-8"));
   } catch {
     return {};
   }
 }
 function writeSettings2(settings) {
-  const dir = path30.dirname(SETTINGS_PATH2);
-  if (!fs38.existsSync(dir)) fs38.mkdirSync(dir, { recursive: true });
-  fs38.writeFileSync(SETTINGS_PATH2, JSON.stringify(settings, null, 2));
+  const dir = path31.dirname(SETTINGS_PATH2);
+  if (!fs39.existsSync(dir)) fs39.mkdirSync(dir, { recursive: true });
+  fs39.writeFileSync(SETTINGS_PATH2, JSON.stringify(settings, null, 2));
 }
 function findHookIndex(sessionEnd) {
   return sessionEnd.findIndex(
@@ -10101,19 +10242,19 @@ ${PRECOMMIT_END}`;
 function getGitHooksDir() {
   try {
     const gitDir = execSync15("git rev-parse --git-dir", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-    return path30.join(gitDir, "hooks");
+    return path31.join(gitDir, "hooks");
   } catch {
     return null;
   }
 }
 function getPreCommitPath() {
   const hooksDir = getGitHooksDir();
-  return hooksDir ? path30.join(hooksDir, "pre-commit") : null;
+  return hooksDir ? path31.join(hooksDir, "pre-commit") : null;
 }
 function isPreCommitHookInstalled() {
   const hookPath = getPreCommitPath();
-  if (!hookPath || !fs38.existsSync(hookPath)) return false;
-  const content = fs38.readFileSync(hookPath, "utf-8");
+  if (!hookPath || !fs39.existsSync(hookPath)) return false;
+  const content = fs39.readFileSync(hookPath, "utf-8");
   return content.includes(PRECOMMIT_START);
 }
 function installPreCommitHook() {
@@ -10122,35 +10263,35 @@ function installPreCommitHook() {
   }
   const hookPath = getPreCommitPath();
   if (!hookPath) return { installed: false, alreadyInstalled: false };
-  const hooksDir = path30.dirname(hookPath);
-  if (!fs38.existsSync(hooksDir)) fs38.mkdirSync(hooksDir, { recursive: true });
+  const hooksDir = path31.dirname(hookPath);
+  if (!fs39.existsSync(hooksDir)) fs39.mkdirSync(hooksDir, { recursive: true });
   let content = "";
-  if (fs38.existsSync(hookPath)) {
-    content = fs38.readFileSync(hookPath, "utf-8");
+  if (fs39.existsSync(hookPath)) {
+    content = fs39.readFileSync(hookPath, "utf-8");
     if (!content.endsWith("\n")) content += "\n";
     content += "\n" + getPrecommitBlock() + "\n";
   } else {
     content = "#!/bin/sh\n\n" + getPrecommitBlock() + "\n";
   }
-  fs38.writeFileSync(hookPath, content);
-  fs38.chmodSync(hookPath, 493);
+  fs39.writeFileSync(hookPath, content);
+  fs39.chmodSync(hookPath, 493);
   return { installed: true, alreadyInstalled: false };
 }
 function removePreCommitHook() {
   const hookPath = getPreCommitPath();
-  if (!hookPath || !fs38.existsSync(hookPath)) {
+  if (!hookPath || !fs39.existsSync(hookPath)) {
     return { removed: false, notFound: true };
   }
-  let content = fs38.readFileSync(hookPath, "utf-8");
+  let content = fs39.readFileSync(hookPath, "utf-8");
   if (!content.includes(PRECOMMIT_START)) {
     return { removed: false, notFound: true };
   }
   const regex = new RegExp(`\\n?${PRECOMMIT_START}[\\s\\S]*?${PRECOMMIT_END}\\n?`);
   content = content.replace(regex, "\n");
   if (content.trim() === "#!/bin/sh" || content.trim() === "") {
-    fs38.unlinkSync(hookPath);
+    fs39.unlinkSync(hookPath);
   } else {
-    fs38.writeFileSync(hookPath, content);
+    fs39.writeFileSync(hookPath, content);
   }
   return { removed: true, notFound: false };
 }
@@ -10199,11 +10340,11 @@ async function hooksCommand(options) {
         console.log(chalk20.green("  \u2713") + ` ${hook.label} enabled`);
       }
     }
-    if (fs39.existsSync(".claude")) {
+    if (fs40.existsSync(".claude")) {
       const r = installLearningHooks();
       if (r.installed) console.log(chalk20.green("  \u2713") + " Claude Code learning hooks enabled");
     }
-    if (fs39.existsSync(".cursor")) {
+    if (fs40.existsSync(".cursor")) {
       const r = installCursorLearningHooks();
       if (r.installed) console.log(chalk20.green("  \u2713") + " Cursor learning hooks enabled");
     }
@@ -10371,8 +10512,8 @@ async function configCommand() {
 }
 
 // src/commands/learn.ts
-import fs43 from "fs";
-import path34 from "path";
+import fs44 from "fs";
+import path35 from "path";
 import chalk23 from "chalk";
 
 // src/learner/stdin.ts
@@ -10403,8 +10544,8 @@ function readStdin() {
 }
 
 // src/learner/storage.ts
-import fs40 from "fs";
-import path31 from "path";
+import fs41 from "fs";
+import path32 from "path";
 var MAX_RESPONSE_LENGTH = 2e3;
 var DEFAULT_STATE = {
   sessionId: null,
@@ -10413,15 +10554,15 @@ var DEFAULT_STATE = {
   lastAnalysisEventCount: 0
 };
 function ensureLearningDir() {
-  if (!fs40.existsSync(getLearningDir())) {
-    fs40.mkdirSync(getLearningDir(), { recursive: true });
+  if (!fs41.existsSync(getLearningDir())) {
+    fs41.mkdirSync(getLearningDir(), { recursive: true });
   }
 }
 function sessionFilePath() {
-  return path31.join(getLearningDir(), LEARNING_SESSION_FILE);
+  return path32.join(getLearningDir(), LEARNING_SESSION_FILE);
 }
 function stateFilePath() {
-  return path31.join(getLearningDir(), LEARNING_STATE_FILE);
+  return path32.join(getLearningDir(), LEARNING_STATE_FILE);
 }
 function truncateResponse(response) {
   const str = JSON.stringify(response);
@@ -10431,10 +10572,10 @@ function truncateResponse(response) {
 function trimSessionFileIfNeeded(filePath) {
   const state = readState2();
   if (state.eventCount + 1 > LEARNING_MAX_EVENTS) {
-    const lines = fs40.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
+    const lines = fs41.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
     if (lines.length > LEARNING_MAX_EVENTS) {
       const kept = lines.slice(lines.length - LEARNING_MAX_EVENTS);
-      fs40.writeFileSync(filePath, kept.join("\n") + "\n");
+      fs41.writeFileSync(filePath, kept.join("\n") + "\n");
     }
   }
 }
@@ -10442,19 +10583,19 @@ function appendEvent(event) {
   ensureLearningDir();
   const truncated = { ...event, tool_response: truncateResponse(event.tool_response) };
   const filePath = sessionFilePath();
-  fs40.appendFileSync(filePath, JSON.stringify(truncated) + "\n");
+  fs41.appendFileSync(filePath, JSON.stringify(truncated) + "\n");
   trimSessionFileIfNeeded(filePath);
 }
 function appendPromptEvent(event) {
   ensureLearningDir();
   const filePath = sessionFilePath();
-  fs40.appendFileSync(filePath, JSON.stringify(event) + "\n");
+  fs41.appendFileSync(filePath, JSON.stringify(event) + "\n");
   trimSessionFileIfNeeded(filePath);
 }
 function readAllEvents() {
   const filePath = sessionFilePath();
-  if (!fs40.existsSync(filePath)) return [];
-  const lines = fs40.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
+  if (!fs41.existsSync(filePath)) return [];
+  const lines = fs41.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
   const events = [];
   for (const line of lines) {
     try {
@@ -10466,26 +10607,26 @@ function readAllEvents() {
 }
 function getEventCount() {
   const filePath = sessionFilePath();
-  if (!fs40.existsSync(filePath)) return 0;
-  const content = fs40.readFileSync(filePath, "utf-8");
+  if (!fs41.existsSync(filePath)) return 0;
+  const content = fs41.readFileSync(filePath, "utf-8");
   return content.split("\n").filter(Boolean).length;
 }
 function clearSession() {
   const filePath = sessionFilePath();
-  if (fs40.existsSync(filePath)) fs40.unlinkSync(filePath);
+  if (fs41.existsSync(filePath)) fs41.unlinkSync(filePath);
 }
 function readState2() {
   const filePath = stateFilePath();
-  if (!fs40.existsSync(filePath)) return { ...DEFAULT_STATE };
+  if (!fs41.existsSync(filePath)) return { ...DEFAULT_STATE };
   try {
-    return JSON.parse(fs40.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs41.readFileSync(filePath, "utf-8"));
   } catch {
     return { ...DEFAULT_STATE };
   }
 }
 function writeState2(state) {
   ensureLearningDir();
-  fs40.writeFileSync(stateFilePath(), JSON.stringify(state, null, 2));
+  fs41.writeFileSync(stateFilePath(), JSON.stringify(state, null, 2));
 }
 function resetState() {
   writeState2({ ...DEFAULT_STATE });
@@ -10493,16 +10634,16 @@ function resetState() {
 var LOCK_FILE2 = "finalize.lock";
 var LOCK_STALE_MS = 5 * 60 * 1e3;
 function lockFilePath() {
-  return path31.join(getLearningDir(), LOCK_FILE2);
+  return path32.join(getLearningDir(), LOCK_FILE2);
 }
 function acquireFinalizeLock() {
   ensureLearningDir();
   const lockPath = lockFilePath();
-  if (fs40.existsSync(lockPath)) {
+  if (fs41.existsSync(lockPath)) {
     try {
-      const stat = fs40.statSync(lockPath);
+      const stat = fs41.statSync(lockPath);
       if (Date.now() - stat.mtimeMs < LOCK_STALE_MS) {
-        const pid = parseInt(fs40.readFileSync(lockPath, "utf-8").trim(), 10);
+        const pid = parseInt(fs41.readFileSync(lockPath, "utf-8").trim(), 10);
         if (!isNaN(pid) && isProcessAlive(pid)) {
           return false;
         }
@@ -10510,12 +10651,12 @@ function acquireFinalizeLock() {
     } catch {
     }
     try {
-      fs40.unlinkSync(lockPath);
+      fs41.unlinkSync(lockPath);
     } catch {
     }
   }
   try {
-    fs40.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+    fs41.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
     return true;
   } catch {
     return false;
@@ -10532,7 +10673,7 @@ function isProcessAlive(pid) {
 function releaseFinalizeLock() {
   const lockPath = lockFilePath();
   try {
-    if (fs40.existsSync(lockPath)) fs40.unlinkSync(lockPath);
+    if (fs41.existsSync(lockPath)) fs41.unlinkSync(lockPath);
   } catch {
   }
 }
@@ -10577,24 +10718,24 @@ function sanitizeSecrets(text) {
 }
 
 // src/lib/notifications.ts
-import fs41 from "fs";
-import path32 from "path";
+import fs42 from "fs";
+import path33 from "path";
 import chalk22 from "chalk";
 function notificationFilePath() {
-  return path32.join(getLearningDir(), "last-finalize-summary.json");
+  return path33.join(getLearningDir(), "last-finalize-summary.json");
 }
 function writeFinalizeSummary(summary) {
   try {
     ensureLearningDir();
-    fs41.writeFileSync(notificationFilePath(), JSON.stringify(summary, null, 2));
+    fs42.writeFileSync(notificationFilePath(), JSON.stringify(summary, null, 2));
   } catch {
   }
 }
 function checkPendingNotifications() {
   try {
-    if (!fs41.existsSync(notificationFilePath())) return;
-    const raw = fs41.readFileSync(notificationFilePath(), "utf-8");
-    fs41.unlinkSync(notificationFilePath());
+    if (!fs42.existsSync(notificationFilePath())) return;
+    const raw = fs42.readFileSync(notificationFilePath(), "utf-8");
+    fs42.unlinkSync(notificationFilePath());
     const summary = JSON.parse(raw);
     if (!summary.newItemCount || summary.newItemCount === 0) return;
     const wasteLabel = summary.wasteTokens > 0 ? ` (~${summary.wasteTokens.toLocaleString()} wasted tokens captured)` : "";
@@ -10610,7 +10751,7 @@ function checkPendingNotifications() {
     console.log("");
   } catch {
     try {
-      fs41.unlinkSync(notificationFilePath());
+      fs42.unlinkSync(notificationFilePath());
     } catch {
     }
   }
@@ -10762,8 +10903,8 @@ function calculateSessionWaste(events) {
 init_config();
 
 // src/learner/roi.ts
-import fs42 from "fs";
-import path33 from "path";
+import fs43 from "fs";
+import path34 from "path";
 var DEFAULT_TOTALS = {
   totalWasteTokens: 0,
   totalWasteSeconds: 0,
@@ -10777,19 +10918,19 @@ var DEFAULT_TOTALS = {
   lastSessionTimestamp: ""
 };
 function roiFilePath() {
-  return path33.join(getLearningDir(), LEARNING_ROI_FILE);
+  return path34.join(getLearningDir(), LEARNING_ROI_FILE);
 }
 function readROIStats() {
   const filePath = roiFilePath();
-  if (!fs42.existsSync(filePath)) {
+  if (!fs43.existsSync(filePath)) {
     return { learnings: [], sessions: [], totals: { ...DEFAULT_TOTALS } };
   }
   try {
-    return JSON.parse(fs42.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs43.readFileSync(filePath, "utf-8"));
   } catch {
     try {
       const corruptPath = filePath + ".corrupt";
-      fs42.renameSync(filePath, corruptPath);
+      fs43.renameSync(filePath, corruptPath);
       console.error(`caliber: roi-stats.json was corrupt \u2014 renamed to ${corruptPath}`);
     } catch {
     }
@@ -10798,7 +10939,7 @@ function readROIStats() {
 }
 function writeROIStats(stats) {
   ensureLearningDir();
-  fs42.writeFileSync(roiFilePath(), JSON.stringify(stats, null, 2));
+  fs43.writeFileSync(roiFilePath(), JSON.stringify(stats, null, 2));
 }
 function recalculateTotals(stats) {
   const totals = stats.totals;
@@ -11004,9 +11145,9 @@ var AUTO_SETTLE_MS = 200;
 var INCREMENTAL_INTERVAL = 50;
 function writeFinalizeError(message) {
   try {
-    const errorPath = path34.join(getLearningDir(), LEARNING_LAST_ERROR_FILE);
-    if (!fs43.existsSync(getLearningDir())) fs43.mkdirSync(getLearningDir(), { recursive: true });
-    fs43.writeFileSync(errorPath, JSON.stringify({
+    const errorPath = path35.join(getLearningDir(), LEARNING_LAST_ERROR_FILE);
+    if (!fs44.existsSync(getLearningDir())) fs44.mkdirSync(getLearningDir(), { recursive: true });
+    fs44.writeFileSync(errorPath, JSON.stringify({
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error: message,
       pid: process.pid
@@ -11016,9 +11157,9 @@ function writeFinalizeError(message) {
 }
 function readFinalizeError() {
   try {
-    const errorPath = path34.join(getLearningDir(), LEARNING_LAST_ERROR_FILE);
-    if (!fs43.existsSync(errorPath)) return null;
-    return JSON.parse(fs43.readFileSync(errorPath, "utf-8"));
+    const errorPath = path35.join(getLearningDir(), LEARNING_LAST_ERROR_FILE);
+    if (!fs44.existsSync(errorPath)) return null;
+    return JSON.parse(fs44.readFileSync(errorPath, "utf-8"));
   } catch {
     return null;
   }
@@ -11065,14 +11206,14 @@ async function learnObserveCommand(options) {
         const { resolveCaliber: resolveCaliber2 } = await Promise.resolve().then(() => (init_resolve_caliber(), resolve_caliber_exports));
         const bin = resolveCaliber2();
         const { spawn: spawn4 } = await import("child_process");
-        const logPath = path34.join(getLearningDir(), LEARNING_FINALIZE_LOG);
-        if (!fs43.existsSync(getLearningDir())) fs43.mkdirSync(getLearningDir(), { recursive: true });
-        const logFd = fs43.openSync(logPath, "a");
+        const logPath = path35.join(getLearningDir(), LEARNING_FINALIZE_LOG);
+        if (!fs44.existsSync(getLearningDir())) fs44.mkdirSync(getLearningDir(), { recursive: true });
+        const logFd = fs44.openSync(logPath, "a");
         spawn4(bin, ["learn", "finalize", "--auto", "--incremental"], {
           detached: true,
           stdio: ["ignore", logFd, logFd]
         }).unref();
-        fs43.closeSync(logFd);
+        fs44.closeSync(logFd);
       } catch {
       }
     }
@@ -11279,7 +11420,7 @@ async function learnFinalizeCommand(options) {
 }
 async function learnInstallCommand() {
   let anyInstalled = false;
-  if (fs43.existsSync(".claude")) {
+  if (fs44.existsSync(".claude")) {
     const r = installLearningHooks();
     if (r.installed) {
       console.log(chalk23.green("\u2713") + " Claude Code learning hooks installed");
@@ -11288,7 +11429,7 @@ async function learnInstallCommand() {
       console.log(chalk23.dim("  Claude Code hooks already installed"));
     }
   }
-  if (fs43.existsSync(".cursor")) {
+  if (fs44.existsSync(".cursor")) {
     const r = installCursorLearningHooks();
     if (r.installed) {
       console.log(chalk23.green("\u2713") + " Cursor learning hooks installed");
@@ -11297,7 +11438,7 @@ async function learnInstallCommand() {
       console.log(chalk23.dim("  Cursor hooks already installed"));
     }
   }
-  if (!fs43.existsSync(".claude") && !fs43.existsSync(".cursor")) {
+  if (!fs44.existsSync(".claude") && !fs44.existsSync(".cursor")) {
     console.log(chalk23.yellow("No .claude/ or .cursor/ directory found."));
     console.log(chalk23.dim("  Run `caliber init` first, or create the directory manually."));
     return;
@@ -11355,8 +11496,8 @@ async function learnStatusCommand() {
   if (lastError) {
     console.log(`Last error: ${chalk23.red(lastError.error)}`);
     console.log(chalk23.dim(`  at ${lastError.timestamp}`));
-    const logPath = path34.join(getLearningDir(), LEARNING_FINALIZE_LOG);
-    if (fs43.existsSync(logPath)) {
+    const logPath = path35.join(getLearningDir(), LEARNING_FINALIZE_LOG);
+    if (fs44.existsSync(logPath)) {
       console.log(chalk23.dim(`  Full log: ${logPath}`));
     }
   }
@@ -11436,11 +11577,11 @@ async function learnDeleteCommand(indexStr) {
   }
   const item = items[targetIdx];
   const filePath = item.source === "personal" ? PERSONAL_LEARNINGS_FILE : "CALIBER_LEARNINGS.md";
-  if (!fs43.existsSync(filePath)) {
+  if (!fs44.existsSync(filePath)) {
     console.log(chalk23.red("Learnings file not found."));
     return;
   }
-  const content = fs43.readFileSync(filePath, "utf-8");
+  const content = fs44.readFileSync(filePath, "utf-8");
   const lines = content.split("\n");
   const bulletsOfSource = items.filter((i) => i.source === item.source);
   const posInFile = bulletsOfSource.indexOf(item);
@@ -11461,9 +11602,9 @@ async function learnDeleteCommand(indexStr) {
   }
   const bulletToRemove = lines[lineToRemove];
   const newLines = lines.filter((_, i) => i !== lineToRemove);
-  fs43.writeFileSync(filePath, newLines.join("\n"));
+  fs44.writeFileSync(filePath, newLines.join("\n"));
   if (item.source === "personal") {
-    fs43.chmodSync(filePath, 384);
+    fs44.chmodSync(filePath, 384);
   }
   const roiStats = readROIStats();
   const cleanText = bulletToRemove.replace(/^- /, "").replace(/^\*\*\[[^\]]+\]\*\*\s*/, "").trim();
@@ -11532,11 +11673,14 @@ function displayColdStart(score) {
   console.log(chalk24.bold("\n  Agent Insights\n"));
   const hooksInstalled = areLearningHooksInstalled() || areCursorLearningHooksInstalled();
   if (!hooksInstalled) {
-    console.log(chalk24.yellow("  No learning hooks installed."));
-    console.log(chalk24.dim("  Run ") + chalk24.cyan("caliber learn install") + chalk24.dim(" to start tracking agent performance."));
+    console.log(chalk24.yellow("  Learning hooks not installed."));
+    console.log(chalk24.dim("  Session learning captures patterns from your AI coding sessions \u2014 what"));
+    console.log(chalk24.dim("  fails, what works, corrections you make \u2014 so your agents improve over time.\n"));
+    console.log(chalk24.dim("  Run ") + chalk24.cyan("caliber learn install") + chalk24.dim(" to enable."));
   } else {
-    console.log(chalk24.dim("  No session data yet. Use your AI agent and insights will appear here."));
-    console.log(chalk24.dim("  Learnings are extracted automatically at the end of each session."));
+    console.log(chalk24.dim("  Learning hooks are active. Use your AI agent and insights"));
+    console.log(chalk24.dim("  will appear automatically after each session.\n"));
+    console.log(chalk24.dim(`  Progress: 0/${MIN_SESSIONS_FULL} sessions \u2014 full insights unlock at ${MIN_SESSIONS_FULL}`));
   }
   console.log(chalk24.dim(`
   Config score: ${score.score}/100 (${score.grade})`));
@@ -11544,7 +11688,9 @@ function displayColdStart(score) {
 }
 function displayEarlyData(data, score) {
   console.log(chalk24.bold("\n  Agent Insights") + chalk24.yellow(" (early data)\n"));
-  console.log(chalk24.dim("  Still collecting data. Insights become more reliable after 20+ sessions.\n"));
+  const remaining = MIN_SESSIONS_FULL - data.totalSessions;
+  console.log(chalk24.dim(`  ${data.totalSessions}/${MIN_SESSIONS_FULL} sessions tracked \u2014 ${remaining} more for full insights.
+`));
   console.log(`  Sessions tracked:       ${chalk24.cyan(String(data.totalSessions))}`);
   console.log(`  Learnings accumulated:  ${chalk24.cyan(String(data.learningCount))}`);
   if (data.totalWasteTokens > 0) {
@@ -11596,6 +11742,14 @@ function displayFullInsights(data, score) {
   }
   console.log(chalk24.bold("\n  Config Quality"));
   console.log(`    Score:                ${chalk24.cyan(`${score.score}/100`)} (${score.grade})`);
+  const history = readScoreHistory();
+  const trend = getScoreTrend(history);
+  if (trend) {
+    const trendColor = trend.direction === "up" ? chalk24.green : trend.direction === "down" ? chalk24.red : chalk24.gray;
+    const arrow = trend.direction === "up" ? "\u2191" : trend.direction === "down" ? "\u2193" : "\u2192";
+    const sign = trend.delta > 0 ? "+" : "";
+    console.log(`    Trend:                ${trendColor(`${arrow} ${sign}${trend.delta} pts`)} ${chalk24.dim(`over ${trend.entries} checks`)}`);
+  }
   console.log("");
 }
 async function insightsCommand(options) {
@@ -11622,8 +11776,8 @@ async function insightsCommand(options) {
 }
 
 // src/commands/sources.ts
-import fs44 from "fs";
-import path35 from "path";
+import fs45 from "fs";
+import path36 from "path";
 import chalk25 from "chalk";
 async function sourcesListCommand() {
   const dir = process.cwd();
@@ -11639,9 +11793,9 @@ async function sourcesListCommand() {
   if (configSources.length > 0) {
     for (const source of configSources) {
       const sourcePath = source.path || source.url || "";
-      const exists = source.path ? fs44.existsSync(path35.resolve(dir, source.path)) : false;
+      const exists = source.path ? fs45.existsSync(path36.resolve(dir, source.path)) : false;
       const status = exists ? chalk25.green("reachable") : chalk25.red("not found");
-      const hasSummary = source.path && fs44.existsSync(path35.join(path35.resolve(dir, source.path), ".caliber", "summary.json"));
+      const hasSummary = source.path && fs45.existsSync(path36.join(path36.resolve(dir, source.path), ".caliber", "summary.json"));
       console.log(`  ${chalk25.bold(source.role || source.type)}  ${chalk25.dim(sourcePath)}`);
       console.log(`    Type: ${source.type}  Status: ${status}${hasSummary ? "  " + chalk25.cyan("has summary.json") : ""}`);
       if (source.description) console.log(`    ${chalk25.dim(source.description)}`);
@@ -11651,7 +11805,7 @@ async function sourcesListCommand() {
   if (workspaces.length > 0) {
     console.log(chalk25.dim("  Auto-detected workspaces:"));
     for (const ws of workspaces) {
-      const exists = fs44.existsSync(path35.resolve(dir, ws));
+      const exists = fs45.existsSync(path36.resolve(dir, ws));
       console.log(`    ${exists ? chalk25.green("\u25CF") : chalk25.red("\u25CF")} ${ws}`);
     }
     console.log("");
@@ -11659,8 +11813,8 @@ async function sourcesListCommand() {
 }
 async function sourcesAddCommand(sourcePath) {
   const dir = process.cwd();
-  const absPath = path35.resolve(dir, sourcePath);
-  if (!fs44.existsSync(absPath)) {
+  const absPath = path36.resolve(dir, sourcePath);
+  if (!fs45.existsSync(absPath)) {
     console.log(chalk25.red(`
   Path not found: ${sourcePath}
 `));
@@ -11675,7 +11829,7 @@ async function sourcesAddCommand(sourcePath) {
   }
   const existing = loadSourcesConfig(dir);
   const alreadyConfigured = existing.some(
-    (s) => s.path && path35.resolve(dir, s.path) === absPath
+    (s) => s.path && path36.resolve(dir, s.path) === absPath
   );
   if (alreadyConfigured) {
     console.log(chalk25.yellow(`
@@ -11723,8 +11877,8 @@ async function sourcesRemoveCommand(name) {
 }
 
 // src/commands/publish.ts
-import fs45 from "fs";
-import path36 from "path";
+import fs46 from "fs";
+import path37 from "path";
 import chalk26 from "chalk";
 import ora7 from "ora";
 init_config();
@@ -11738,10 +11892,10 @@ async function publishCommand() {
   const spinner = ora7("Generating project summary...").start();
   try {
     const fingerprint = await collectFingerprint(dir);
-    const claudeMd = readFileOrNull(path36.join(dir, "CLAUDE.md"));
+    const claudeMd = readFileOrNull(path37.join(dir, "CLAUDE.md"));
     const topLevelDirs = fingerprint.fileTree.filter((f) => f.endsWith("/") && !f.includes("/")).map((f) => f.replace(/\/$/, ""));
     const summary = {
-      name: fingerprint.packageName || path36.basename(dir),
+      name: fingerprint.packageName || path37.basename(dir),
       version: "1.0.0",
       description: fingerprint.description || "",
       languages: fingerprint.languages,
@@ -11753,7 +11907,7 @@ async function publishCommand() {
       summary.conventions = claudeMd.slice(0, 2e3);
     }
     try {
-      const pkgContent = readFileOrNull(path36.join(dir, "package.json"));
+      const pkgContent = readFileOrNull(path37.join(dir, "package.json"));
       if (pkgContent) {
         const pkg3 = JSON.parse(pkgContent);
         if (pkg3.scripts) {
@@ -11766,14 +11920,14 @@ async function publishCommand() {
       }
     } catch {
     }
-    const outputDir = path36.join(dir, ".caliber");
-    if (!fs45.existsSync(outputDir)) {
-      fs45.mkdirSync(outputDir, { recursive: true });
+    const outputDir = path37.join(dir, ".caliber");
+    if (!fs46.existsSync(outputDir)) {
+      fs46.mkdirSync(outputDir, { recursive: true });
     }
-    const outputPath = path36.join(outputDir, "summary.json");
-    fs45.writeFileSync(outputPath, JSON.stringify(summary, null, 2) + "\n", "utf-8");
+    const outputPath = path37.join(outputDir, "summary.json");
+    fs46.writeFileSync(outputPath, JSON.stringify(summary, null, 2) + "\n", "utf-8");
     spinner.succeed("Project summary published");
-    console.log(`  ${chalk26.green("\u2713")} ${path36.relative(dir, outputPath)}`);
+    console.log(`  ${chalk26.green("\u2713")} ${path37.relative(dir, outputPath)}`);
     console.log(chalk26.dim("\n  Other projects can now reference this repo as a source."));
     console.log(chalk26.dim("  When they run `caliber init`, they'll read this summary automatically.\n"));
   } catch (err) {
@@ -11785,13 +11939,13 @@ async function publishCommand() {
 }
 
 // src/cli.ts
-var __dirname = path37.dirname(fileURLToPath(import.meta.url));
+var __dirname = path38.dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(
-  fs46.readFileSync(path37.resolve(__dirname, "..", "package.json"), "utf-8")
+  fs47.readFileSync(path38.resolve(__dirname, "..", "package.json"), "utf-8")
 );
 var program = new Command();
 var displayVersion = process.env.CALIBER_LOCAL ? `${pkg.version}-local` : pkg.version;
-program.name(process.env.CALIBER_LOCAL ? "caloc" : "caliber").description("Configure your coding agent environment").version(displayVersion).option("--no-traces", "Disable anonymous telemetry for this run");
+program.name(process.env.CALIBER_LOCAL ? "caloc" : "caliber").description("AI context infrastructure for coding agents").version(displayVersion).option("--no-traces", "Disable anonymous telemetry for this run");
 function tracked(commandName, handler) {
   const wrapper = async (...args) => {
     const start = Date.now();
@@ -11848,13 +12002,13 @@ function parseAgentOption(value) {
   }
   return agents;
 }
-program.command("init").description("Initialize your project for AI-assisted development").option("--agent <type>", "Target agents (comma-separated): claude, cursor, codex, github-copilot", parseAgentOption).option("--source <paths...>", "Related source paths to include as context").option("--dry-run", "Preview changes without writing files").option("--force", "Overwrite existing setup without prompting").option("--debug-report", void 0, false).option("--show-tokens", "Show token usage summary at the end").option("--auto-approve", "Run without interactive prompts (auto-accept all)").option("--verbose", "Show detailed logs of each step").action(tracked("init", initCommand));
+program.command("init").description("Initialize your project for AI-assisted development").option("--agent <type>", "Target agents (comma-separated): claude, cursor, codex, github-copilot", parseAgentOption).option("--source <paths...>", "Related source paths to include as context").option("--dry-run", "Preview changes without writing files").option("--force", "Overwrite existing config without prompting").option("--debug-report", void 0, false).option("--show-tokens", "Show token usage summary at the end").option("--auto-approve", "Run without interactive prompts (auto-accept all)").option("--verbose", "Show detailed logs of each step").action(tracked("init", initCommand));
 program.command("undo").description("Revert all config changes made by Caliber").action(tracked("undo", undoCommand));
-program.command("status").description("Show current Caliber setup status").option("--json", "Output as JSON").action(tracked("status", statusCommand));
-program.command("regenerate").alias("regen").alias("re").description("Re-analyze project and regenerate setup").option("--dry-run", "Preview changes without writing files").action(tracked("regenerate", regenerateCommand));
+program.command("status").description("Show current Caliber config status").option("--json", "Output as JSON").action(tracked("status", statusCommand));
+program.command("regenerate").alias("regen").alias("re").description("Re-analyze project and regenerate config").option("--dry-run", "Preview changes without writing files").action(tracked("regenerate", regenerateCommand));
 program.command("config").description("Configure LLM provider, API key, and model").action(tracked("config", configCommand));
 program.command("skills").description("Discover and install community skills for your project").option("--query <terms>", 'Search for skills by topic (e.g. "react frontend")').option("--install <slugs>", "Install specific skills by slug (comma-separated)").action(tracked("skills", recommendCommand));
-program.command("score").description("Score your current agent config setup (deterministic, no network)").option("--json", "Output as JSON").option("--quiet", "One-line output for scripts/hooks").option("--agent <type>", "Target agents (comma-separated): claude, cursor, codex, github-copilot", parseAgentOption).option("--compare <ref>", "Compare score against a git ref (branch, tag, or SHA)").action(tracked("score", scoreCommand));
+program.command("score").description("Score your AI context configuration (deterministic, no network)").option("--json", "Output as JSON").option("--quiet", "One-line output for scripts/hooks").option("--agent <type>", "Target agents (comma-separated): claude, cursor, codex, github-copilot", parseAgentOption).option("--compare <ref>", "Compare score against a git ref (branch, tag, or SHA)").action(tracked("score", scoreCommand));
 program.command("refresh").description("Update docs based on recent code changes").option("--quiet", "Suppress output (for use in hooks)").option("--dry-run", "Preview changes without writing files").action(tracked("refresh", refreshCommand));
 program.command("hooks").description("Manage auto-refresh hooks (toggle interactively)").option("--install", "Enable all hooks non-interactively").option("--remove", "Disable all hooks non-interactively").action(tracked("hooks", hooksCommand));
 program.command("insights").description("Show agent performance insights and learning impact").option("--json", "Output as JSON").action(tracked("insights", insightsCommand));
@@ -11863,7 +12017,7 @@ sources.command("list").description("Show configured and auto-detected sources")
 sources.command("add").description("Add an external source").argument("<path>", "Path to repo directory or file").action(tracked("sources:add", sourcesAddCommand));
 sources.command("remove").description("Remove a configured source").argument("<name>", "Source path or role to remove").action(tracked("sources:remove", sourcesRemoveCommand));
 program.command("publish").description("Generate a machine-readable summary for other repos to consume").action(tracked("publish", publishCommand));
-var learn = program.command("learn", { hidden: true }).description("[dev] Session learning \u2014 observe tool usage and extract reusable instructions");
+var learn = program.command("learn").description("Manage session learning \u2014 extract patterns from your AI coding sessions");
 learn.command("observe").description("Record a tool event from stdin (called by hooks)").option("--failure", "Mark event as a tool failure").option("--prompt", "Record a user prompt event").action(tracked("learn:observe", learnObserveCommand));
 learn.command("finalize").description("Analyze session events and update CALIBER_LEARNINGS.md (called on SessionEnd)").option("--force", "Skip the running-process check (for manual invocation)").option("--auto", "Silent mode for hooks (lower threshold, no interactive output)").option("--incremental", "Extract learnings mid-session without clearing events").action(tracked("learn:finalize", (opts) => learnFinalizeCommand(opts)));
 learn.command("install").description("Install learning hooks into .claude/settings.json").action(tracked("learn:install", learnInstallCommand));
@@ -11874,16 +12028,16 @@ learn.command("delete <index>").description("Delete a learning by its index numb
 learn.command("add <content>").description("Add a learning directly (used by agent skills)").option("--personal", "Save as a personal learning instead of project-level").action(tracked("learn:add", learnAddCommand));
 
 // src/utils/version-check.ts
-import fs47 from "fs";
-import path38 from "path";
+import fs48 from "fs";
+import path39 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { execSync as execSync16 } from "child_process";
 import chalk27 from "chalk";
 import ora8 from "ora";
 import confirm2 from "@inquirer/confirm";
-var __dirname_vc = path38.dirname(fileURLToPath2(import.meta.url));
+var __dirname_vc = path39.dirname(fileURLToPath2(import.meta.url));
 var pkg2 = JSON.parse(
-  fs47.readFileSync(path38.resolve(__dirname_vc, "..", "package.json"), "utf-8")
+  fs48.readFileSync(path39.resolve(__dirname_vc, "..", "package.json"), "utf-8")
 );
 function getChannel(version) {
   const match = version.match(/-(dev|next)\./);
@@ -11908,8 +12062,8 @@ function isNewer(registry, current) {
 function getInstalledVersion() {
   try {
     const globalRoot = execSync16("npm root -g", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-    const pkgPath = path38.join(globalRoot, "@rely-ai", "caliber", "package.json");
-    return JSON.parse(fs47.readFileSync(pkgPath, "utf-8")).version;
+    const pkgPath = path39.join(globalRoot, "@rely-ai", "caliber", "package.json");
+    return JSON.parse(fs48.readFileSync(pkgPath, "utf-8")).version;
   } catch {
     return null;
   }