@rely-ai/caliber 1.37.1 → 1.39.0

package/dist/bin.js

@@ -1099,14 +1099,14 @@ __export(lock_exports, {
   isCaliberRunning: () => isCaliberRunning,
   releaseLock: () => releaseLock
 });
-import fs39 from "fs";
-import path32 from "path";
+import fs40 from "fs";
+import path33 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`);
+  return path33.join(os8.tmpdir(), `.caliber-${hash}.lock`);
 }
 function getLockFile() {
   if (!_lockPath) _lockPath = buildLockPath();
@@ -1115,8 +1115,8 @@ function getLockFile() {
 function isCaliberRunning() {
   try {
     const lockFile = buildLockPath();
-    if (!fs39.existsSync(lockFile)) return false;
-    const raw = fs39.readFileSync(lockFile, "utf-8").trim();
+    if (!fs40.existsSync(lockFile)) return false;
+    const raw = fs40.readFileSync(lockFile, "utf-8").trim();
     const { pid, ts } = JSON.parse(raw);
     if (Date.now() - ts > STALE_MS) return false;
     try {
@@ -1131,14 +1131,14 @@ function isCaliberRunning() {
 }
 function acquireLock() {
   try {
-    fs39.writeFileSync(getLockFile(), JSON.stringify({ pid: process.pid, ts: Date.now() }));
+    fs40.writeFileSync(getLockFile(), JSON.stringify({ pid: process.pid, ts: Date.now() }));
   } catch {
   }
 }
 function releaseLock() {
   try {
     const lockFile = getLockFile();
-    if (fs39.existsSync(lockFile)) fs39.unlinkSync(lockFile);
+    if (fs40.existsSync(lockFile)) fs40.unlinkSync(lockFile);
   } catch {
   }
 }
@@ -1153,8 +1153,8 @@ var init_lock = __esm({
 
 // src/cli.ts
 import { Command } from "commander";
-import fs50 from "fs";
-import path41 from "path";
+import fs51 from "fs";
+import path42 from "path";
 import { fileURLToPath } from "url";
 
 // src/commands/init.ts
@@ -1309,6 +1309,19 @@ var REFRESH_LAST_ERROR_FILE = path2.join(CALIBER_DIR, "last-refresh-error.json")
 var MIN_SESSIONS_FOR_COMPARISON = 3;
 
 // src/fingerprint/existing-config.ts
+var CALIBER_MANAGED_PREFIX = "caliber-";
+var INCLUDABLE_DOC_PATTERNS = [
+  "ARCHITECTURE.md",
+  "CONTRIBUTING.md",
+  "DEVELOPMENT.md",
+  "SETUP.md",
+  "docs/ARCHITECTURE.md",
+  "docs/CONTRIBUTING.md",
+  "docs/DEVELOPMENT.md",
+  "docs/API.md",
+  "docs/GUIDE.md",
+  "docs/SETUP.md"
+];
 function readSkillsFromDir(skillsDir) {
   if (!fs2.existsSync(skillsDir)) return void 0;
   try {
@@ -1371,6 +1384,18 @@ function readExistingConfigs(dir) {
     } catch {
     }
   }
+  const claudeRulesDir = path3.join(dir, ".claude", "rules");
+  if (fs2.existsSync(claudeRulesDir)) {
+    try {
+      const files = fs2.readdirSync(claudeRulesDir).filter((f) => f.endsWith(".md"));
+      const rules = files.map((f) => ({
+        filename: f,
+        content: fs2.readFileSync(path3.join(claudeRulesDir, f), "utf-8")
+      }));
+      if (rules.length > 0) configs.claudeRules = rules;
+    } catch {
+    }
+  }
   const cursorrulesPath = path3.join(dir, ".cursorrules");
   if (fs2.existsSync(cursorrulesPath)) {
     configs.cursorrules = fs2.readFileSync(cursorrulesPath, "utf-8");
@@ -1434,6 +1459,8 @@ function readExistingConfigs(dir) {
     } catch {
     }
   }
+  const found = INCLUDABLE_DOC_PATTERNS.filter((p) => fs2.existsSync(path3.join(dir, p)));
+  if (found.length > 0) configs.includableDocs = found;
   return configs;
 }
 
@@ -2708,15 +2735,16 @@ var CLAUDE_CLI_BIN = "claude";
 var DEFAULT_TIMEOUT_MS2 = 10 * 60 * 1e3;
 var IS_WINDOWS2 = process.platform === "win32";
 function spawnClaude(args) {
+  const env = { ...process.env, CLAUDE_CODE_SIMPLE: "1" };
   return IS_WINDOWS2 ? spawn2([CLAUDE_CLI_BIN, ...args].join(" "), {
     cwd: process.cwd(),
     stdio: ["pipe", "pipe", "pipe"],
-    env: process.env,
+    env,
     shell: true
   }) : spawn2(CLAUDE_CLI_BIN, args, {
     cwd: process.cwd(),
     stdio: ["pipe", "pipe", "pipe"],
-    env: process.env
+    env
   });
 }
 var ClaudeCliProvider = class {
@@ -3113,6 +3141,7 @@ var CONFIG_FILE_TYPES = `You understand these config files:
 - .agents/skills/{name}/SKILL.md: Same OpenSkills format for Codex skills (Codex scans .agents/skills/ for skills).
 - .opencode/skills/{name}/SKILL.md: Same OpenSkills format for OpenCode skills (OpenCode scans .opencode/skills/ for skills).
 - .cursor/skills/{name}/SKILL.md: Same OpenSkills format for Cursor skills.
+- .claude/rules/*.md: Path-scoped rules for Claude Code with YAML frontmatter. Each rule file contains a \`paths:\` field with glob patterns \u2014 Claude Code only loads the rule when the user works on matching files. Use for domain-specific conventions (e.g., API patterns, test conventions, database rules). Always-apply rules omit the \`paths:\` field.
 - .cursorrules: Coding rules for Cursor (deprecated legacy format \u2014 do NOT generate this).
 - .cursor/rules/*.mdc: Modern Cursor rules with frontmatter (description, globs, alwaysApply).
 - .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.
@@ -3152,6 +3181,7 @@ Skill field requirements:
 - "name" MUST NOT be any of these reserved names (they are managed by Caliber automatically): "setup-caliber", "find-skills", "save-learning". Do NOT generate skills with these names.
 - "description": MUST include WHAT it does + WHEN to use it with specific trigger phrases. Example: "Manages database migrations. Use when user says 'run migration', 'create migration', 'db schema change', or modifies files in db/migrations/."
 - "content": markdown body only \u2014 do NOT include YAML frontmatter, it is generated from name+description.
+- "paths" (optional): array of glob patterns. When provided, the skill is only loaded when the user works on matching files. Use for skills tied to specific file types or directories. Example: ["src/api/**", "src/routes/**"] for an API skill, or ["Dockerfile*", "docker-compose*"] for a Docker skill. Omit for general-purpose skills.
 
 Skill content structure \u2014 follow this template:
 1. A heading with the skill name
@@ -3160,6 +3190,31 @@ Skill content structure \u2014 follow this template:
 4. "## Troubleshooting" (optional) \u2014 common errors and how to fix them
 
 Keep skill content under 200 lines. Focus on actionable instructions, not documentation prose.`;
+var CLAUDE_RULES_FORMAT = `CLAUDE RULES FORMAT \u2014 .claude/rules/*.md files:
+Claude Code loads .claude/rules/*.md files as path-scoped instructions. Generate 2-4 rules that extract domain-specific conventions from CLAUDE.md into focused, contextually-loaded files.
+
+Each rule file uses YAML frontmatter with an optional \`paths:\` field:
+\`\`\`markdown
+---
+paths:
+  - src/api/**
+  - src/routes/**
+---
+
+# API Conventions
+
+- All endpoints return \`{ data, error }\` envelope
+- Use \`validateRequest(schema)\` middleware before handlers
+\`\`\`
+
+Rules without \`paths:\` apply globally (use sparingly \u2014 prefer path-scoped rules).
+
+Guidelines:
+- Extract patterns from the codebase that apply to specific file types or directories
+- Keep each rule under 50 lines \u2014 these are loaded into context, conciseness matters
+- Good candidates: testing patterns, API conventions, database query patterns, component structure
+- Do NOT duplicate content from CLAUDE.md \u2014 rules supplement it with path-specific detail
+- filename must be kebab-case ending in .md (e.g. \`testing-patterns.md\`, \`api-conventions.md\`)`;
 var SCORING_CRITERIA = `SCORING CRITERIA \u2014 your output is scored deterministically against the actual filesystem. Optimize for 100/100:
 
 Existence (25 pts):
@@ -3202,7 +3257,13 @@ For command sections, use code blocks with one command per line.
 
 - Each skill content: max 150 lines. Focus on patterns and examples, not exhaustive docs.
 - Cursor rules: max 5 .mdc files.
-- If the project is large, prioritize depth on the 3-4 most critical tools over breadth across everything.`;
+- If the project is large, prioritize depth on the 3-4 most critical tools over breadth across everything.
+
+@include directives (Claude Code only):
+- If the project has existing documentation files (ARCHITECTURE.md, CONTRIBUTING.md, API docs, etc.), reference them in CLAUDE.md using \`@./path\` instead of summarizing their content. Claude Code will inline them automatically.
+- Example: Instead of writing an architecture summary, add \`@./ARCHITECTURE.md\` in the relevant section.
+- This keeps CLAUDE.md compact while giving the agent access to detailed docs.
+- Only use @include for files that actually exist in the provided file tree.`;
 var GENERATION_SYSTEM_PROMPT = `${ROLE_AND_CONTEXT}
 
 ${CONFIG_FILE_TYPES}
@@ -3224,18 +3285,19 @@ AgentSetup schema:
   ],
   "claude": {
     "claudeMd": "string (markdown content for CLAUDE.md)",
-    "skills": [{ "name": "string (kebab-case, matches directory name)", "description": "string (what this skill does and when to use it)", "content": "string (markdown body \u2014 NO frontmatter, it will be generated from name+description)" }]
+    "rules": [{ "filename": "string.md (kebab-case, e.g. api-conventions.md)", "content": "string (markdown with YAML frontmatter containing paths: glob)" }],
+    "skills": [{ "name": "string (kebab-case, matches directory name)", "description": "string (what this skill does and when to use it)", "content": "string (markdown body \u2014 NO frontmatter, it will be generated from name+description)", "paths": ["optional array of glob patterns \u2014 omit for general-purpose skills"] }]
   },
   "codex": {
     "agentsMd": "string (markdown content for AGENTS.md \u2014 the primary Codex instructions file, same quality/structure as CLAUDE.md)",
-    "skills": [{ "name": "string (kebab-case, matches directory name)", "description": "string (what this skill does and when to use it)", "content": "string (markdown body \u2014 NO frontmatter, it will be generated from name+description)" }]
+    "skills": [{ "name": "string (kebab-case, matches directory name)", "description": "string (what this skill does and when to use it)", "content": "string (markdown body \u2014 NO frontmatter, it will be generated from name+description)", "paths": ["optional array of glob patterns \u2014 omit for general-purpose skills"] }]
   },
   "opencode": {
     "agentsMd": "string (markdown content for AGENTS.md \u2014 reuse codex.agentsMd if codex is also targeted, otherwise generate fresh)",
-    "skills": [{ "name": "string (kebab-case, matches directory name)", "description": "string (what this skill does and when to use it)", "content": "string (markdown body \u2014 NO frontmatter, it will be generated from name+description)" }]
+    "skills": [{ "name": "string (kebab-case, matches directory name)", "description": "string (what this skill does and when to use it)", "content": "string (markdown body \u2014 NO frontmatter, it will be generated from name+description)", "paths": ["optional array of glob patterns \u2014 omit for general-purpose skills"] }]
   },
   "cursor": {
-    "skills": [{ "name": "string (kebab-case, matches directory name)", "description": "string (what this skill does and when to use it)", "content": "string (markdown body \u2014 NO frontmatter, it will be generated from name+description)" }],
+    "skills": [{ "name": "string (kebab-case, matches directory name)", "description": "string (what this skill does and when to use it)", "content": "string (markdown body \u2014 NO frontmatter, it will be generated from name+description)", "paths": ["optional array of glob patterns \u2014 omit for general-purpose skills"] }],
     "rules": [{ "filename": "string.mdc", "content": "string (with frontmatter)" }]
   },
   "copilot": {
@@ -3248,12 +3310,15 @@ NOTE: If both "codex" and "opencode" are targeted, set opencode.agentsMd to the
 
 ${SKILL_FORMAT_RULES}
 
+${CLAUDE_RULES_FORMAT}
+
 ${FILE_DESCRIPTIONS_RULES}
 
 ${SCORING_CRITERIA}
 
 ${OUTPUT_SIZE_CONSTRAINTS}
-- Skills: generate 3-6 skills per target platform based on project complexity. Each skill should cover a distinct tool, workflow, or domain \u2014 don't pad with generic skills.`;
+- Skills: generate 3-6 skills per target platform based on project complexity. Each skill should cover a distinct tool, workflow, or domain \u2014 don't pad with generic skills.
+- Claude rules: generate 2-4 .claude/rules/*.md files when claude is targeted. Each rule should extract domain-specific patterns from the codebase.`;
 var CORE_GENERATION_PROMPT = `${ROLE_AND_CONTEXT}
 
 ${CONFIG_FILE_TYPES}
@@ -3275,6 +3340,7 @@ CoreSetup schema:
   ],
   "claude": {
     "claudeMd": "string (markdown content for CLAUDE.md)",
+    "rules": [{ "filename": "string.md (kebab-case, e.g. api-conventions.md)", "content": "string (markdown with YAML frontmatter containing paths: glob)" }],
     "skillTopics": [{ "name": "string (kebab-case)", "description": "string (what this skill does and WHEN to use it \u2014 include trigger phrases)" }]
   },
   "codex": {
@@ -3308,12 +3374,15 @@ Skill topic description MUST follow this formula: [What it does] + [When to use
 Include specific trigger phrases users would actually say. Also include negative triggers to prevent over-triggering.
 Example: "Creates a new API endpoint following the project's route pattern. Handles request validation, error responses, and DB queries. Use when user says 'add endpoint', 'new route', 'create API', or adds files to src/routes/. Do NOT use for modifying existing routes."
 
+${CLAUDE_RULES_FORMAT}
+
 ${FILE_DESCRIPTIONS_RULES}
 
 ${SCORING_CRITERIA}
 
 ${OUTPUT_SIZE_CONSTRAINTS}
-- Skill topics: 3-6 per platform based on project complexity (name + description only, no content).`;
+- Skill topics: 3-6 per platform based on project complexity (name + description only, no content).
+- Claude rules: generate 2-4 .claude/rules/*.md files when claude is targeted.`;
 var SKILL_GENERATION_PROMPT = `You generate a single skill file for a coding agent (Claude Code, Cursor, Codex, or OpenCode).
 
 Given project context and a skill topic, produce a focused SKILL.md body.
@@ -3343,7 +3412,7 @@ Rules:
 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.
 
 Return ONLY a JSON object:
-{"name": "string (kebab-case)", "description": "string (what + when + capabilities + negative triggers)", "content": "string (markdown body)"}`;
+{"name": "string (kebab-case)", "description": "string (what + when + capabilities + negative triggers)", "content": "string (markdown body)", "paths": ["optional glob patterns \u2014 include when the skill applies to specific file types or directories, omit for general-purpose skills"]}`;
 var REFINE_SYSTEM_PROMPT = `You are an expert at modifying coding agent configurations (Claude Code, Cursor, Codex, OpenCode, and GitHub Copilot).
 
 You will receive the current AgentSetup JSON and a user request describing what to change.
@@ -3400,7 +3469,7 @@ var REFRESH_SYSTEM_PROMPT = `You are an expert at maintaining coding project doc
 
 You will receive:
 1. Git diffs showing what code changed
-2. Current contents of documentation files (CLAUDE.md, README.md, skills, cursor rules, copilot instructions)
+2. Current contents of documentation files (CLAUDE.md, .claude/rules/*.md, README.md, skills, cursor rules, copilot instructions)
 3. Project context (languages, frameworks, file tree)
 
 CONSERVATIVE UPDATE means:
@@ -3419,6 +3488,12 @@ 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)
 
+Claude rules (.claude/rules/*.md):
+- If the diff affects code in a domain covered by an existing rule, update that rule
+- If the diff introduces a new domain pattern (e.g., new API conventions, new test patterns), create a new rule file
+- Rules with paths: frontmatter should only contain conventions relevant to those paths
+- Keep rules under 50 lines \u2014 they load into context alongside other instructions
+
 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).
@@ -3435,6 +3510,7 @@ Return a JSON object with this exact shape:
   "updatedDocs": {
     "agentsMd": "<updated content or null>",
     "claudeMd": "<updated content or null>",
+    "claudeRules": [{"filename": "name.md", "content": "full content with frontmatter"}] or null,
     "readmeMd": "<updated content or null>",
     "cursorrules": "<updated content or null>",
     "cursorRules": [{"filename": "name.mdc", "content": "..."}] or null,
@@ -3695,7 +3771,7 @@ function getDetectedWorkspaces(dir) {
 
 // src/fingerprint/index.ts
 async function collectFingerprint(dir) {
-  const gitRemoteUrl = getGitRemoteUrl();
+  const gitRemoteUrl = getGitRemoteUrl(dir);
   const fileTree = getFileTree(dir);
   const existingConfigs = readExistingConfigs(dir);
   const packageName = readPackageName(dir);
@@ -4028,6 +4104,55 @@ function removeHook() {
   writeSettings(settings);
   return { removed: true, notFound: false };
 }
+function createScriptHook(config) {
+  const { eventName, scriptPath, scriptContent, description } = config;
+  const hasHook = (matchers) => matchers.some((entry) => entry.hooks?.some((h) => h.description === description));
+  function isInstalled() {
+    const settings = readSettings();
+    const matchers = settings.hooks?.[eventName];
+    return Array.isArray(matchers) && hasHook(matchers);
+  }
+  function install() {
+    const settings = readSettings();
+    if (!settings.hooks) settings.hooks = {};
+    const matchers = settings.hooks[eventName];
+    if (Array.isArray(matchers) && hasHook(matchers)) {
+      return { installed: false, alreadyInstalled: true };
+    }
+    const scriptDir = path10.dirname(scriptPath);
+    if (!fs10.existsSync(scriptDir)) fs10.mkdirSync(scriptDir, { recursive: true });
+    fs10.writeFileSync(scriptPath, scriptContent);
+    fs10.chmodSync(scriptPath, 493);
+    if (!Array.isArray(settings.hooks[eventName])) {
+      settings.hooks[eventName] = [];
+    }
+    settings.hooks[eventName].push({
+      matcher: "",
+      hooks: [{ type: "command", command: scriptPath, description }]
+    });
+    writeSettings(settings);
+    return { installed: true, alreadyInstalled: false };
+  }
+  function remove() {
+    const settings = readSettings();
+    const matchers = settings.hooks?.[eventName];
+    if (!Array.isArray(matchers)) return { removed: false, notFound: true };
+    const idx = matchers.findIndex(
+      (entry) => entry.hooks?.some((h) => h.description === description)
+    );
+    if (idx === -1) return { removed: false, notFound: true };
+    matchers.splice(idx, 1);
+    if (matchers.length === 0) delete settings.hooks[eventName];
+    if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
+    writeSettings(settings);
+    try {
+      fs10.unlinkSync(scriptPath);
+    } catch {
+    }
+    return { removed: true, notFound: false };
+  }
+  return { isInstalled, install, remove };
+}
 var STOP_HOOK_SCRIPT_CONTENT = `#!/bin/sh
 if grep -q "caliber" .git/hooks/pre-commit 2>/dev/null; then
   exit 0
@@ -4040,58 +4165,44 @@ fi
 touch "$FLAG"
 printf '{"decision":"block","reason":"Caliber agent config sync is not set up on this machine. Tell the user: This project uses Caliber to keep agent configs in sync \u2014 it is not set up yet. Want me to run /setup-caliber? (~30 seconds)"}'
 `;
-var STOP_HOOK_SCRIPT_PATH = path10.join(".claude", "hooks", "caliber-check-sync.sh");
-var STOP_HOOK_DESCRIPTION = "Caliber: offer setup if not configured";
-function hasStopHook(matchers) {
-  return matchers.some(
-    (entry) => entry.hooks?.some((h) => h.description === STOP_HOOK_DESCRIPTION)
-  );
-}
-function installStopHook() {
-  const settings = readSettings();
-  if (!settings.hooks) settings.hooks = {};
-  const stop = settings.hooks.Stop;
-  if (Array.isArray(stop) && hasStopHook(stop)) {
-    return { installed: false, alreadyInstalled: true };
-  }
-  const scriptDir = path10.dirname(STOP_HOOK_SCRIPT_PATH);
-  if (!fs10.existsSync(scriptDir)) fs10.mkdirSync(scriptDir, { recursive: true });
-  fs10.writeFileSync(STOP_HOOK_SCRIPT_PATH, STOP_HOOK_SCRIPT_CONTENT);
-  fs10.chmodSync(STOP_HOOK_SCRIPT_PATH, 493);
-  if (!Array.isArray(settings.hooks.Stop)) {
-    settings.hooks.Stop = [];
-  }
-  settings.hooks.Stop.push({
-    matcher: "",
-    hooks: [
-      {
-        type: "command",
-        command: STOP_HOOK_SCRIPT_PATH,
-        description: STOP_HOOK_DESCRIPTION
-      }
-    ]
-  });
-  writeSettings(settings);
-  return { installed: true, alreadyInstalled: false };
-}
-function removeStopHook() {
-  const settings = readSettings();
-  const stop = settings.hooks?.Stop;
-  if (!Array.isArray(stop)) return { removed: false, notFound: true };
-  const idx = stop.findIndex(
-    (entry) => entry.hooks?.some((h) => h.description === STOP_HOOK_DESCRIPTION)
-  );
-  if (idx === -1) return { removed: false, notFound: true };
-  stop.splice(idx, 1);
-  if (stop.length === 0) delete settings.hooks.Stop;
-  if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
-  writeSettings(settings);
-  try {
-    fs10.unlinkSync(STOP_HOOK_SCRIPT_PATH);
-  } catch {
-  }
-  return { removed: true, notFound: false };
-}
+var stopHook = createScriptHook({
+  eventName: "Stop",
+  scriptPath: path10.join(".claude", "hooks", "caliber-check-sync.sh"),
+  scriptContent: STOP_HOOK_SCRIPT_CONTENT,
+  description: "Caliber: offer setup if not configured"
+});
+var installStopHook = stopHook.install;
+var removeStopHook = stopHook.remove;
+var FRESHNESS_SCRIPT = `#!/bin/sh
+STATE_FILE=".caliber/.caliber-state.json"
+[ ! -f "$STATE_FILE" ] && exit 0
+LAST_SHA=$(grep -o '"lastRefreshSha":"[^"]*"' "$STATE_FILE" 2>/dev/null | cut -d'"' -f4)
+[ -z "$LAST_SHA" ] && exit 0
+CURRENT_SHA=$(git rev-parse HEAD 2>/dev/null)
+[ "$LAST_SHA" = "$CURRENT_SHA" ] && exit 0
+COMMITS_BEHIND=$(git rev-list --count "$LAST_SHA".."$CURRENT_SHA" 2>/dev/null || echo 0)
+if [ "$COMMITS_BEHIND" -gt 15 ]; then
+  printf '{"systemMessage":"Caliber: agent configs are %s commits behind. Run caliber refresh to sync."}' "$COMMITS_BEHIND"
+fi
+`;
+var sessionStartHook = createScriptHook({
+  eventName: "SessionStart",
+  scriptPath: path10.join(".claude", "hooks", "caliber-session-freshness.sh"),
+  scriptContent: FRESHNESS_SCRIPT,
+  description: "Caliber: check config freshness on session start"
+});
+var isSessionStartHookInstalled = sessionStartHook.isInstalled;
+var installSessionStartHook = sessionStartHook.install;
+var removeSessionStartHook = sessionStartHook.remove;
+var notificationHook = createScriptHook({
+  eventName: "Notification",
+  scriptPath: path10.join(".claude", "hooks", "caliber-freshness-notify.sh"),
+  scriptContent: FRESHNESS_SCRIPT,
+  description: "Caliber: warn when agent configs are stale"
+});
+var isNotificationHookInstalled = notificationHook.isInstalled;
+var installNotificationHook = notificationHook.install;
+var removeNotificationHook = notificationHook.remove;
 var PRECOMMIT_START = "# caliber:pre-commit:start";
 var PRECOMMIT_END = "# caliber:pre-commit:end";
 function getPrecommitBlock() {
@@ -4698,15 +4809,15 @@ init_config();
 // src/utils/dependencies.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { join as join2 } from "path";
-function readFileOrNull2(path43) {
+function readFileOrNull2(path44) {
   try {
-    return readFileSync2(path43, "utf-8");
+    return readFileSync2(path44, "utf-8");
   } catch {
     return null;
   }
 }
-function readJsonOrNull(path43) {
-  const content = readFileOrNull2(path43);
+function readJsonOrNull(path44) {
+  const content = readFileOrNull2(path44);
   if (!content) return null;
   try {
     return JSON.parse(content);
@@ -4972,7 +5083,8 @@ Generate the skill content following the instructions in the system prompt.`;
   return {
     name: result.name || topic.name,
     description: result.description || topic.description,
-    content
+    content,
+    ...result.paths?.length ? { paths: result.paths } : {}
   };
 }
 async function streamGeneration(config) {
@@ -5188,7 +5300,7 @@ function sampleFileTree(fileTree, codeAnalysisPaths, limit) {
 function buildGeneratePrompt(fingerprint, targetAgent, prompt, failingChecks, currentScore, passingChecks) {
   const parts = [];
   const existing = fingerprint.existingConfigs;
-  const hasExistingConfigs = !!(existing.claudeMd || existing.claudeSettings || existing.claudeSkills?.length || existing.readmeMd || existing.agentsMd || existing.cursorrules || existing.cursorRules?.length);
+  const hasExistingConfigs = !!(existing.claudeMd || existing.claudeSettings || existing.claudeSkills?.length || existing.claudeRules?.length || existing.readmeMd || existing.agentsMd || existing.cursorrules || existing.cursorRules?.length);
   const isTargetedFix = failingChecks && failingChecks.length > 0 && currentScore !== void 0 && currentScore >= 95;
   if (isTargetedFix) {
     parts.push(`TARGETED FIX MODE \u2014 current score: ${currentScore}/100, target: ${targetAgent}`);
@@ -5280,6 +5392,16 @@ ${truncate(skill.content, LIMITS.SKILL_CHARS)}`
 (${existing.claudeSkills.length - LIMITS.SKILLS_MAX} more skills omitted)`);
     }
   }
+  if (existing.claudeRules?.length) {
+    parts.push("\n--- Existing Claude Rules ---");
+    for (const rule of existing.claudeRules.slice(0, LIMITS.RULES_MAX)) {
+      parts.push(
+        `
+[.claude/rules/${rule.filename}]
+${truncate(rule.content, LIMITS.SKILL_CHARS)}`
+      );
+    }
+  }
   if (existing.cursorrules)
     parts.push(
       `
@@ -5327,6 +5449,13 @@ ${existing.personalLearnings}`
 Project dependencies (${allDeps.length}):`);
     parts.push(allDeps.join(", "));
   }
+  if (existing.includableDocs?.length) {
+    parts.push("\n--- Existing Documentation Files (use @include) ---");
+    parts.push("These files exist and can be referenced in CLAUDE.md using @./path:");
+    for (const doc of existing.includableDocs) {
+      parts.push(`- ${doc}`);
+    }
+  }
   if (prompt) parts.push(`
 User instructions: ${prompt}`);
   if (fingerprint.codeAnalysis) {
@@ -5390,18 +5519,29 @@ function writeClaudeConfig(config) {
     appendSyncBlock(appendLearningsBlock(appendPreCommitBlock(config.claudeMd)))
   );
   written.push("CLAUDE.md");
+  if (config.rules?.length) {
+    const rulesDir = path12.join(".claude", "rules");
+    if (!fs12.existsSync(rulesDir)) fs12.mkdirSync(rulesDir, { recursive: true });
+    for (const rule of config.rules) {
+      const rulePath = path12.join(rulesDir, rule.filename);
+      fs12.writeFileSync(rulePath, rule.content);
+      written.push(rulePath);
+    }
+  }
   if (config.skills?.length) {
     for (const skill of config.skills) {
       const skillDir = path12.join(".claude", "skills", skill.name);
       if (!fs12.existsSync(skillDir)) fs12.mkdirSync(skillDir, { recursive: true });
       const skillPath = path12.join(skillDir, "SKILL.md");
-      const frontmatter = [
-        "---",
-        `name: ${skill.name}`,
-        `description: ${skill.description}`,
-        "---",
-        ""
-      ].join("\n");
+      const frontmatterLines = ["---", `name: ${skill.name}`, `description: ${skill.description}`];
+      if (skill.paths?.length) {
+        frontmatterLines.push("paths:");
+        for (const p of skill.paths) {
+          frontmatterLines.push(`  - ${p}`);
+        }
+      }
+      frontmatterLines.push("---", "");
+      const frontmatter = frontmatterLines.join("\n");
       fs12.writeFileSync(skillPath, frontmatter + skill.content);
       written.push(skillPath);
     }
@@ -5688,6 +5828,9 @@ function getFilesToWrite(setup) {
   if (setup.targetAgent.includes("claude") && setup.claude) {
     files.push("CLAUDE.md");
     if (setup.claude.mcpServers) files.push(".mcp.json");
+    if (setup.claude.rules) {
+      for (const r of setup.claude.rules) files.push(`.claude/rules/${r.filename}`);
+    }
     if (setup.claude.skills) {
       for (const s of setup.claude.skills) {
         files.push(`.claude/skills/${s.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase()}/SKILL.md`);
@@ -6230,6 +6373,7 @@ var POINTS_SKILLS_BONUS_PER_EXTRA = 1;
 var POINTS_SKILLS_BONUS_CAP = 2;
 var POINTS_CURSOR_MDC_RULES = 3;
 var POINTS_MCP_SERVERS = 3;
+var POINTS_CLAUDE_RULES = 3;
 var POINTS_CROSS_PLATFORM_PARITY = 2;
 var POINTS_EXECUTABLE_CONTENT = 8;
 var POINTS_CONCISE_CONFIG = 6;
@@ -6299,7 +6443,11 @@ var SECRET_PLACEHOLDER_PATTERNS = [
   /<[^>]+>/
 ];
 var CURSOR_ONLY_CHECKS = /* @__PURE__ */ new Set(["cursor_rules_exist", "cursor_mdc_rules"]);
-var CLAUDE_ONLY_CHECKS = /* @__PURE__ */ new Set(["claude_md_exists", "claude_md_freshness"]);
+var CLAUDE_ONLY_CHECKS = /* @__PURE__ */ new Set([
+  "claude_md_exists",
+  "claude_md_freshness",
+  "claude_rules_exist"
+]);
 var BOTH_ONLY_CHECKS = /* @__PURE__ */ new Set(["cross_platform_parity", "no_duplicate_content"]);
 var CODEX_ONLY_CHECKS = /* @__PURE__ */ new Set(["codex_agents_md_exists"]);
 var COPILOT_ONLY_CHECKS = /* @__PURE__ */ new Set(["copilot_instructions_exists"]);
@@ -6368,6 +6516,32 @@ function checkExistence(dir) {
       instruction: "Create CLAUDE.md with project context, commands, architecture, and conventions."
     }
   });
+  const claudeRulesDir = join3(dir, ".claude", "rules");
+  let claudeRuleFiles = [];
+  if (existsSync3(claudeRulesDir)) {
+    try {
+      claudeRuleFiles = readdirSync2(claudeRulesDir).filter(
+        (f) => f.endsWith(".md") && !f.startsWith(CALIBER_MANAGED_PREFIX)
+      );
+    } catch {
+    }
+  }
+  const hasClaudeRules = claudeRuleFiles.length > 0;
+  checks.push({
+    id: "claude_rules_exist",
+    name: "Claude rules exist (.claude/rules/)",
+    category: "existence",
+    maxPoints: POINTS_CLAUDE_RULES,
+    earnedPoints: hasClaudeRules ? POINTS_CLAUDE_RULES : 0,
+    passed: hasClaudeRules,
+    detail: hasClaudeRules ? `${claudeRuleFiles.length} rule${claudeRuleFiles.length === 1 ? "" : "s"} found` : "No .claude/rules/*.md files",
+    suggestion: hasClaudeRules ? void 0 : "Add .claude/rules/*.md with path-scoped conventions for better context efficiency",
+    fix: hasClaudeRules ? void 0 : {
+      action: "create_file",
+      data: { file: ".claude/rules/" },
+      instruction: "Create .claude/rules/ with path-scoped markdown rules (e.g., testing-patterns.md, api-conventions.md)."
+    }
+  });
   const hasCursorrules = existsSync3(join3(dir, ".cursorrules"));
   const cursorRulesDir = existsSync3(join3(dir, ".cursor", "rules"));
   const cursorRulesExist = hasCursorrules || cursorRulesDir;
@@ -7626,8 +7800,8 @@ function trackInitSkillsSearch(searched, installedCount) {
 function trackInitScoreRegression(oldScore, newScore) {
   trackEvent("init_score_regression", { old_score: oldScore, new_score: newScore });
 }
-function trackInitCompleted(path43, score) {
-  trackEvent("init_completed", { path: path43, score });
+function trackInitCompleted(path44, score) {
+  trackEvent("init_completed", { path: path44, score });
 }
 function trackRegenerateCompleted(action, durationMs) {
   trackEvent("regenerate_completed", { action, duration_ms: durationMs });
@@ -8640,11 +8814,11 @@ async function scoreAndRefine(setup, dir, sessionHistory, callbacks, options) {
   const maxIterations = options?.thorough ? 3 : MAX_REFINE_ITERATIONS;
   const minPoints = options?.thorough ? 1 : MIN_POINTS_TO_REFINE;
   const existsCache = /* @__PURE__ */ new Map();
-  const cachedExists = (path43) => {
-    const cached = existsCache.get(path43);
+  const cachedExists = (path44) => {
+    const cached = existsCache.get(path44);
     if (cached !== void 0) return cached;
-    const result = existsSync9(path43);
-    existsCache.set(path43, result);
+    const result = existsSync9(path44);
+    existsCache.set(path44, result);
     return result;
   };
   const projectStructure = collectProjectStructure(dir);
@@ -10056,6 +10230,8 @@ async function initCommand(options) {
   }
   installStopHook();
   console.log(`  ${chalk14.green("\u2713")} Onboarding hook \u2014 nudges new team members to set up`);
+  installSessionStartHook();
+  console.log(`  ${chalk14.green("\u2713")} Freshness hook \u2014 warns when configs are stale`);
   const { ensureBuiltinSkills: ensureBuiltinSkills2 } = await Promise.resolve().then(() => (init_builtin_skills(), builtin_skills_exports));
   for (const agent of targetAgent) {
     if (agent === "claude" && !fs34.existsSync(".claude"))
@@ -11051,8 +11227,8 @@ async function scoreCommand(options) {
 }
 
 // src/commands/refresh.ts
-import fs40 from "fs";
-import path33 from "path";
+import fs41 from "fs";
+import path34 from "path";
 import chalk19 from "chalk";
 import ora6 from "ora";
 
@@ -11139,52 +11315,91 @@ function collectDiff(lastSha) {
   const summary = parts.join(", ") || "no changes";
   return { hasChanges, committedDiff, stagedDiff, unstagedDiff, changedFiles, summary };
 }
+function scopeDiffToDir(diff, dir, allConfigDirs) {
+  if (dir === ".") {
+    const otherDirs = allConfigDirs.filter((d) => d !== ".");
+    if (otherDirs.length === 0) return diff;
+    const changedFiles2 = diff.changedFiles.filter(
+      (f) => !otherDirs.some((d) => f.startsWith(`${d}/`))
+    );
+    const hasChanges2 = changedFiles2.length > 0;
+    return {
+      ...diff,
+      changedFiles: changedFiles2,
+      hasChanges: hasChanges2,
+      summary: hasChanges2 ? `${changedFiles2.length} files changed` : "no changes"
+    };
+  }
+  const prefix = `${dir}/`;
+  const changedFiles = diff.changedFiles.filter((f) => f.startsWith(prefix)).map((f) => f.slice(prefix.length));
+  const hasChanges = changedFiles.length > 0;
+  return {
+    ...diff,
+    changedFiles,
+    hasChanges,
+    summary: hasChanges ? `${changedFiles.length} files changed` : "no changes"
+  };
+}
 
 // src/writers/refresh.ts
 init_pre_commit_block();
 import fs37 from "fs";
 import path30 from "path";
-function writeRefreshDocs(docs) {
+function writeFileGroup(groupDir, files) {
+  fs37.mkdirSync(groupDir, { recursive: true });
+  return files.map((file) => {
+    const filePath = path30.join(groupDir, file.filename);
+    fs37.writeFileSync(filePath, file.content);
+    return filePath.replace(/\\/g, "/");
+  });
+}
+function writeRefreshDocs(docs, dir = ".") {
   const written = [];
+  const p = (relPath) => (dir === "." ? relPath : path30.join(dir, relPath)).replace(/\\/g, "/");
+  const ensureParent = (filePath) => {
+    const parent = path30.dirname(filePath);
+    if (parent !== "." && !fs37.existsSync(parent)) fs37.mkdirSync(parent, { recursive: true });
+  };
   if (docs.agentsMd) {
-    fs37.writeFileSync("AGENTS.md", appendManagedBlocks(docs.agentsMd, "codex"));
-    written.push("AGENTS.md");
+    const filePath = p("AGENTS.md");
+    ensureParent(filePath);
+    fs37.writeFileSync(filePath, appendManagedBlocks(docs.agentsMd, "codex"));
+    written.push(filePath);
   }
   if (docs.claudeMd) {
-    fs37.writeFileSync("CLAUDE.md", appendManagedBlocks(docs.claudeMd));
-    written.push("CLAUDE.md");
+    const filePath = p("CLAUDE.md");
+    ensureParent(filePath);
+    fs37.writeFileSync(filePath, appendManagedBlocks(docs.claudeMd));
+    written.push(filePath);
+  }
+  if (docs.claudeRules) {
+    written.push(...writeFileGroup(p(path30.join(".claude", "rules")), docs.claudeRules));
   }
   if (docs.readmeMd) {
-    fs37.writeFileSync("README.md", docs.readmeMd);
-    written.push("README.md");
+    const filePath = p("README.md");
+    ensureParent(filePath);
+    fs37.writeFileSync(filePath, docs.readmeMd);
+    written.push(filePath);
   }
   if (docs.cursorrules) {
-    fs37.writeFileSync(".cursorrules", docs.cursorrules);
-    written.push(".cursorrules");
+    const filePath = p(".cursorrules");
+    ensureParent(filePath);
+    fs37.writeFileSync(filePath, docs.cursorrules);
+    written.push(filePath);
   }
   if (docs.cursorRules) {
-    const rulesDir = path30.join(".cursor", "rules");
-    if (!fs37.existsSync(rulesDir)) fs37.mkdirSync(rulesDir, { recursive: true });
-    for (const rule of docs.cursorRules) {
-      fs37.writeFileSync(path30.join(rulesDir, rule.filename), rule.content);
-      written.push(`.cursor/rules/${rule.filename}`);
-    }
+    written.push(...writeFileGroup(p(path30.join(".cursor", "rules")), docs.cursorRules));
   }
   if (docs.copilotInstructions) {
-    fs37.mkdirSync(".github", { recursive: true });
-    fs37.writeFileSync(
-      path30.join(".github", "copilot-instructions.md"),
-      appendManagedBlocks(docs.copilotInstructions, "copilot")
-    );
-    written.push(".github/copilot-instructions.md");
+    const filePath = p(path30.join(".github", "copilot-instructions.md"));
+    ensureParent(filePath);
+    fs37.writeFileSync(filePath, appendManagedBlocks(docs.copilotInstructions, "copilot"));
+    written.push(filePath);
   }
   if (docs.copilotInstructionFiles) {
-    const instructionsDir = path30.join(".github", "instructions");
-    fs37.mkdirSync(instructionsDir, { recursive: true });
-    for (const file of docs.copilotInstructionFiles) {
-      fs37.writeFileSync(path30.join(instructionsDir, file.filename), file.content);
-      written.push(`.github/instructions/${file.filename}`);
-    }
+    written.push(
+      ...writeFileGroup(p(path30.join(".github", "instructions")), docs.copilotInstructionFiles)
+    );
   }
   return written;
 }
@@ -11192,8 +11407,15 @@ 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);
+async function refreshDocs(diff, existingDocs, projectContext, learnedSection, sources2, scope) {
+  const prompt = buildRefreshPrompt(
+    diff,
+    existingDocs,
+    projectContext,
+    learnedSection,
+    sources2,
+    scope
+  );
   const fastModel = getFastModel();
   const raw = await llmCall({
     system: REFRESH_SYSTEM_PROMPT,
@@ -11203,8 +11425,14 @@ async function refreshDocs(diff, existingDocs, projectContext, learnedSection, s
   });
   return parseJsonResponse(raw);
 }
-function buildRefreshPrompt(diff, existingDocs, projectContext, learnedSection, sources2) {
+function buildRefreshPrompt(diff, existingDocs, projectContext, learnedSection, sources2, scope) {
   const parts = [];
+  if (scope) {
+    parts.push(`You are updating docs for the \`${scope}\` subdirectory of a monorepo.`);
+    parts.push("Only include changes relevant to files under this directory.");
+    parts.push("The changed files list has been filtered to this directory already.");
+    parts.push("Ignore diff content for files outside this directory.\n");
+  }
   parts.push("Update documentation based on the following code changes.\n");
   if (projectContext.packageName) parts.push(`Project: ${projectContext.packageName}`);
   if (projectContext.languages?.length)
@@ -11258,9 +11486,17 @@ Changed files: ${diff.changedFiles.join(", ")}`);
       parts.push(skill.content);
     }
   }
+  if (existingDocs.claudeRules?.length) {
+    for (const rule of existingDocs.claudeRules) {
+      if (rule.filename.startsWith(CALIBER_MANAGED_PREFIX)) continue;
+      parts.push(`
+[.claude/rules/${rule.filename}]`);
+      parts.push(rule.content);
+    }
+  }
   if (existingDocs.cursorRules?.length) {
     for (const rule of existingDocs.cursorRules) {
-      if (rule.filename.startsWith("caliber-")) continue;
+      if (rule.filename.startsWith(CALIBER_MANAGED_PREFIX)) continue;
       parts.push(`
 [.cursor/rules/${rule.filename}]`);
       parts.push(rule.content);
@@ -11277,6 +11513,16 @@ Changed files: ${diff.changedFiles.join(", ")}`);
       parts.push(file.content);
     }
   }
+  if (existingDocs.includableDocs?.length) {
+    parts.push(`
+--- Existing Documentation Files (use @include) ---`);
+    parts.push(
+      "These files exist in the project and can be referenced in CLAUDE.md using @./path:"
+    );
+    for (const doc of existingDocs.includableDocs) {
+      parts.push(`- ${doc}`);
+    }
+  }
   if (learnedSection) {
     parts.push("\n--- Learned Patterns (from session learning) ---");
     parts.push("Consider these accumulated learnings when deciding what to update:");
@@ -11486,10 +11732,77 @@ function migrateInlineLearnings() {
 init_config();
 init_resolve_caliber();
 init_builtin_skills();
+
+// src/lib/config-discovery.ts
+import fs39 from "fs";
+import path32 from "path";
+var CONFIG_FILE_MARKERS = [
+  "CLAUDE.md",
+  "AGENTS.md",
+  ".cursorrules",
+  ".github/copilot-instructions.md"
+];
+var CONFIG_DIR_MARKERS = [".cursor/rules", ".github/instructions", ".opencode/skills"];
+var IGNORE_DIRS3 = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  "build",
+  ".cache",
+  ".turbo",
+  "coverage",
+  ".caliber",
+  "__pycache__",
+  ".venv",
+  "vendor",
+  "target"
+]);
+var MAX_DEPTH = 4;
+function hasConfigFiles(dir) {
+  for (const marker of CONFIG_FILE_MARKERS) {
+    if (fs39.existsSync(path32.join(dir, marker))) return true;
+  }
+  for (const marker of CONFIG_DIR_MARKERS) {
+    const markerPath = path32.join(dir, marker);
+    if (fs39.existsSync(markerPath) && fs39.statSync(markerPath).isDirectory()) return true;
+  }
+  return false;
+}
+function discoverConfigDirs(rootDir) {
+  const dirs = [];
+  if (hasConfigFiles(rootDir)) {
+    dirs.push(".");
+  }
+  walkForConfigs(rootDir, rootDir, 0, dirs);
+  dirs.sort();
+  return dirs;
+}
+function walkForConfigs(baseDir, currentDir, depth, result) {
+  if (depth >= MAX_DEPTH) return;
+  let entries;
+  try {
+    entries = fs39.readdirSync(currentDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".") || IGNORE_DIRS3.has(entry.name)) continue;
+    const fullPath = path32.join(currentDir, entry.name);
+    const relPath = path32.relative(baseDir, fullPath).replace(/\\/g, "/");
+    if (hasConfigFiles(fullPath)) {
+      result.push(relPath);
+    }
+    walkForConfigs(baseDir, fullPath, depth + 1, result);
+  }
+}
+
+// src/commands/refresh.ts
 function writeRefreshError(error) {
   try {
-    if (!fs40.existsSync(CALIBER_DIR)) fs40.mkdirSync(CALIBER_DIR, { recursive: true });
-    fs40.writeFileSync(
+    if (!fs41.existsSync(CALIBER_DIR)) fs41.mkdirSync(CALIBER_DIR, { recursive: true });
+    fs41.writeFileSync(
       REFRESH_LAST_ERROR_FILE,
       JSON.stringify(
         {
@@ -11508,15 +11821,15 @@ function writeRefreshError(error) {
 }
 function readRefreshError() {
   try {
-    if (!fs40.existsSync(REFRESH_LAST_ERROR_FILE)) return null;
-    return JSON.parse(fs40.readFileSync(REFRESH_LAST_ERROR_FILE, "utf-8"));
+    if (!fs41.existsSync(REFRESH_LAST_ERROR_FILE)) return null;
+    return JSON.parse(fs41.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);
+    if (fs41.existsSync(REFRESH_LAST_ERROR_FILE)) fs41.unlinkSync(REFRESH_LAST_ERROR_FILE);
   } catch {
   }
 }
@@ -11536,11 +11849,11 @@ function log2(quiet, ...args) {
 function discoverGitRepos(parentDir) {
   const repos = [];
   try {
-    const entries = fs40.readdirSync(parentDir, { withFileTypes: true });
+    const entries = fs41.readdirSync(parentDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-      const childPath = path33.join(parentDir, entry.name);
-      if (fs40.existsSync(path33.join(childPath, ".git"))) {
+      const childPath = path34.join(parentDir, entry.name);
+      if (fs41.existsSync(path34.join(childPath, ".git"))) {
         repos.push(childPath);
       }
     }
@@ -11548,51 +11861,37 @@ function discoverGitRepos(parentDir) {
   }
   return repos.sort();
 }
-function collectFilesToWrite(updatedDocs) {
+function collectFilesToWrite(updatedDocs, dir = ".") {
   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");
+  const p = (relPath) => (dir === "." ? relPath : path34.join(dir, relPath)).replace(/\\/g, "/");
+  if (updatedDocs.agentsMd) files.push(p("AGENTS.md"));
+  if (updatedDocs.claudeMd) files.push(p("CLAUDE.md"));
+  if (Array.isArray(updatedDocs.claudeRules)) {
+    for (const r of updatedDocs.claudeRules)
+      files.push(p(`.claude/rules/${r.filename}`));
+  }
+  if (updatedDocs.readmeMd) files.push(p("README.md"));
+  if (updatedDocs.cursorrules) files.push(p(".cursorrules"));
   if (Array.isArray(updatedDocs.cursorRules)) {
     for (const r of updatedDocs.cursorRules)
-      files.push(`.cursor/rules/${r.filename}`);
+      files.push(p(`.cursor/rules/${r.filename}`));
   }
-  if (updatedDocs.copilotInstructions) files.push(".github/copilot-instructions.md");
+  if (updatedDocs.copilotInstructions) files.push(p(".github/copilot-instructions.md"));
   if (Array.isArray(updatedDocs.copilotInstructionFiles)) {
     for (const f of updatedDocs.copilotInstructionFiles)
-      files.push(`.github/instructions/${f.filename}`);
+      files.push(p(`.github/instructions/${f.filename}`));
   }
   return files;
 }
 var REFRESH_COOLDOWN_MS = 3e4;
-async function refreshSingleRepo(repoDir, options) {
+async function refreshDir(repoDir, dir, diff, options) {
   const quiet = !!options.quiet;
   const prefix = options.label ? `${chalk19.bold(options.label)} ` : "";
-  const state = readState();
-  const lastSha = state?.lastRefreshSha ?? null;
-  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.`)
-      );
-      return;
-    }
-  }
-  const diff = collectDiff(lastSha);
-  if (!diff.hasChanges) {
-    if (currentSha) {
-      writeState({ lastRefreshSha: currentSha, lastRefreshTimestamp: (/* @__PURE__ */ new Date()).toISOString() });
-    }
-    log2(quiet, chalk19.dim(`${prefix}No changes since last refresh.`));
-    return;
-  }
+  const absDir = dir === "." ? repoDir : path34.resolve(repoDir, dir);
+  const scope = dir === "." ? void 0 : dir;
   const spinner = quiet ? null : ora6(`${prefix}Analyzing changes...`).start();
   const learnedSection = readLearnedSection();
-  const fingerprint = await collectFingerprint(repoDir);
+  const fingerprint = await collectFingerprint(absDir);
   const existingDocs = fingerprint.existingConfigs;
   const projectContext = {
     languages: fingerprint.languages,
@@ -11600,8 +11899,8 @@ async function refreshSingleRepo(repoDir, options) {
     packageName: fingerprint.packageName,
     fileTree: fingerprint.fileTree
   };
-  const workspaces = getDetectedWorkspaces(repoDir);
-  const sources2 = resolveAllSources(repoDir, [], workspaces);
+  const workspaces = getDetectedWorkspaces(absDir);
+  const sources2 = resolveAllSources(absDir, [], workspaces);
   const diffPayload = {
     committed: diff.committedDiff,
     staged: diff.stagedDiff,
@@ -11617,7 +11916,8 @@ async function refreshSingleRepo(repoDir, options) {
       existingDocs,
       projectContext,
       learnedSection,
-      sourcesPayload
+      sourcesPayload,
+      scope
     );
   } catch (firstErr) {
     const isTransient = firstErr instanceof Error && TRANSIENT_ERRORS.some((e) => firstErr.message.toLowerCase().includes(e.toLowerCase()));
@@ -11628,7 +11928,8 @@ async function refreshSingleRepo(repoDir, options) {
         existingDocs,
         projectContext,
         learnedSection,
-        sourcesPayload
+        sourcesPayload,
+        scope
       );
     } catch {
       spinner?.fail(`${prefix}Refresh failed after retry`);
@@ -11637,10 +11938,7 @@ async function refreshSingleRepo(repoDir, options) {
   }
   if (!response.docsUpdated || response.docsUpdated.length === 0) {
     spinner?.succeed(`${prefix}No doc updates needed`);
-    if (currentSha) {
-      writeState({ lastRefreshSha: currentSha, lastRefreshTimestamp: (/* @__PURE__ */ new Date()).toISOString() });
-    }
-    return;
+    return { written: [] };
   }
   if (options.dryRun) {
     spinner?.info(`${prefix}Dry run \u2014 would update:`);
@@ -11651,49 +11949,53 @@ async function refreshSingleRepo(repoDir, options) {
       console.log(chalk19.dim(`
   ${response.changesSummary}`));
     }
-    return;
+    return { written: [] };
   }
-  const targetAgent = state?.targetAgent ?? detectTargetAgent(repoDir);
-  const preScore = computeLocalScore(repoDir, targetAgent);
-  const allFilesToWrite = collectFilesToWrite(response.updatedDocs);
+  const allFilesToWrite = collectFilesToWrite(response.updatedDocs, dir);
   const preRefreshContents = /* @__PURE__ */ new Map();
   for (const filePath of allFilesToWrite) {
-    const fullPath = path33.resolve(repoDir, filePath);
+    const fullPath = path34.resolve(repoDir, filePath);
     try {
-      preRefreshContents.set(filePath, fs40.readFileSync(fullPath, "utf-8"));
+      preRefreshContents.set(filePath, fs41.readFileSync(fullPath, "utf-8"));
     } catch {
       preRefreshContents.set(filePath, null);
     }
   }
-  const written = writeRefreshDocs(response.updatedDocs);
+  const state = readState();
+  const targetAgent = state?.targetAgent ?? detectTargetAgent(repoDir);
+  const runQualityGate = dir === ".";
+  const preScore = runQualityGate ? computeLocalScore(absDir, targetAgent) : null;
+  const written = writeRefreshDocs(response.updatedDocs, dir);
   const trigger = quiet ? "hook" : "manual";
   trackRefreshCompleted(written.length, Date.now(), trigger);
-  const postScore = computeLocalScore(repoDir, targetAgent);
-  if (postScore.score < preScore.score) {
-    for (const [filePath, content] of preRefreshContents) {
-      const fullPath = path33.resolve(repoDir, filePath);
-      if (content === null) {
-        try {
-          fs40.unlinkSync(fullPath);
-        } catch {
+  if (runQualityGate && preScore) {
+    const postScore = computeLocalScore(absDir, targetAgent);
+    if (postScore.score < preScore.score) {
+      for (const [filePath, content] of preRefreshContents) {
+        const fullPath = path34.resolve(repoDir, filePath);
+        if (content === null) {
+          try {
+            fs41.unlinkSync(fullPath);
+          } catch {
+          }
+        } else {
+          fs41.writeFileSync(fullPath, content);
         }
-      } else {
-        fs40.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.`));
+      return { written: [] };
     }
-    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");
   }
-  recordScore(postScore, "refresh");
   spinner?.succeed(`${prefix}Updated ${written.length} doc${written.length === 1 ? "" : "s"}`);
   const fileChangesMap = new Map(
-    (response.fileChanges || []).map((fc) => [fc.file, fc.description])
+    (response.fileChanges || []).map((fc) => [
+      fc.file,
+      fc.description
+    ])
   );
   for (const file of written) {
     const desc = fileChangesMap.get(file);
@@ -11709,6 +12011,59 @@ async function refreshSingleRepo(repoDir, options) {
     log2(quiet, chalk19.dim(`
   ${response.changesSummary}`));
   }
+  return { written };
+}
+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;
+  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.`)
+      );
+      return;
+    }
+  }
+  const diff = collectDiff(lastSha);
+  if (!diff.hasChanges) {
+    if (currentSha) {
+      writeState({ lastRefreshSha: currentSha, lastRefreshTimestamp: (/* @__PURE__ */ new Date()).toISOString() });
+    }
+    log2(quiet, chalk19.dim(`${prefix}No changes since last refresh.`));
+    return;
+  }
+  const configDirs = discoverConfigDirs(repoDir);
+  if (configDirs.length <= 1) {
+    await refreshDir(repoDir, ".", diff, options);
+  } else {
+    log2(quiet, chalk19.dim(`${prefix}Found configs in ${configDirs.length} directories
+`));
+    let hadFailure = false;
+    for (const dir of configDirs) {
+      const scopedDiff = scopeDiffToDir(diff, dir, configDirs);
+      if (!scopedDiff.hasChanges) continue;
+      const dirLabel = dir === "." ? "root" : dir;
+      try {
+        await refreshDir(repoDir, dir, scopedDiff, { ...options, label: dirLabel });
+      } catch (err) {
+        hadFailure = true;
+        log2(
+          quiet,
+          chalk19.yellow(
+            `  ${dirLabel}: refresh failed \u2014 ${err instanceof Error ? err.message : "unknown error"}`
+          )
+        );
+      }
+    }
+    if (hadFailure) {
+      return;
+    }
+  }
   const builtinWritten = ensureBuiltinSkills();
   for (const file of builtinWritten) {
     log2(quiet, `  ${chalk19.green("\u2713")} ${file} ${chalk19.dim("(built-in)")}`);
@@ -11765,7 +12120,7 @@ async function refreshCommand(options) {
 `));
     const originalDir = process.cwd();
     for (const repo of repos) {
-      const repoName = path33.basename(repo);
+      const repoName = path34.basename(repo);
       try {
         process.chdir(repo);
         await refreshSingleRepo(repo, { ...options, label: repoName });
@@ -11793,7 +12148,7 @@ async function refreshCommand(options) {
 
 // src/commands/hooks.ts
 import chalk20 from "chalk";
-import fs41 from "fs";
+import fs42 from "fs";
 var HOOKS = [
   {
     id: "session-end",
@@ -11810,6 +12165,22 @@ var HOOKS = [
     isInstalled: isPreCommitHookInstalled,
     install: installPreCommitHook,
     remove: removePreCommitHook
+  },
+  {
+    id: "session-start",
+    label: "Claude Code SessionStart",
+    description: "Check config freshness when a session starts",
+    isInstalled: isSessionStartHookInstalled,
+    install: installSessionStartHook,
+    remove: removeSessionStartHook
+  },
+  {
+    id: "notification",
+    label: "Claude Code Notification",
+    description: "Warn when agent configs are stale (>15 commits behind)",
+    isInstalled: isNotificationHookInstalled,
+    install: installNotificationHook,
+    remove: removeNotificationHook
   }
 ];
 function printStatus() {
@@ -11825,8 +12196,12 @@ function printStatus() {
 }
 async function hooksCommand(options) {
   if (!options.install && !options.remove) {
-    console.log(chalk20.dim("\n  Note: caliber now adds refresh instructions directly to config files."));
-    console.log(chalk20.dim("  These hooks are available for non-agent workflows (manual commits).\n"));
+    console.log(
+      chalk20.dim("\n  Note: caliber now adds refresh instructions directly to config files.")
+    );
+    console.log(
+      chalk20.dim("  These hooks are available for non-agent workflows (manual commits).\n")
+    );
   }
   if (options.install) {
     for (const hook of HOOKS) {
@@ -11837,11 +12212,11 @@ async function hooksCommand(options) {
         console.log(chalk20.green("  \u2713") + ` ${hook.label} enabled`);
       }
     }
-    if (fs41.existsSync(".claude")) {
+    if (fs42.existsSync(".claude")) {
       const r = installLearningHooks();
       if (r.installed) console.log(chalk20.green("  \u2713") + " Claude Code learning hooks enabled");
     }
-    if (fs41.existsSync(".cursor")) {
+    if (fs42.existsSync(".cursor")) {
       const r = installCursorLearningHooks();
       if (r.installed) console.log(chalk20.green("  \u2713") + " Cursor learning hooks enabled");
     }
@@ -12009,8 +12384,8 @@ async function configCommand() {
 }
 
 // src/commands/learn.ts
-import fs45 from "fs";
-import path37 from "path";
+import fs46 from "fs";
+import path38 from "path";
 import chalk23 from "chalk";
 
 // src/learner/stdin.ts
@@ -12041,8 +12416,8 @@ function readStdin() {
 }
 
 // src/learner/storage.ts
-import fs42 from "fs";
-import path34 from "path";
+import fs43 from "fs";
+import path35 from "path";
 var MAX_RESPONSE_LENGTH = 2e3;
 var DEFAULT_STATE = {
   sessionId: null,
@@ -12051,15 +12426,15 @@ var DEFAULT_STATE = {
   lastAnalysisEventCount: 0
 };
 function ensureLearningDir() {
-  if (!fs42.existsSync(getLearningDir())) {
-    fs42.mkdirSync(getLearningDir(), { recursive: true });
+  if (!fs43.existsSync(getLearningDir())) {
+    fs43.mkdirSync(getLearningDir(), { recursive: true });
   }
 }
 function sessionFilePath() {
-  return path34.join(getLearningDir(), LEARNING_SESSION_FILE);
+  return path35.join(getLearningDir(), LEARNING_SESSION_FILE);
 }
 function stateFilePath() {
-  return path34.join(getLearningDir(), LEARNING_STATE_FILE);
+  return path35.join(getLearningDir(), LEARNING_STATE_FILE);
 }
 function truncateResponse(response) {
   const str = JSON.stringify(response);
@@ -12069,10 +12444,10 @@ function truncateResponse(response) {
 function trimSessionFileIfNeeded(filePath) {
   const state = readState2();
   if (state.eventCount + 1 > LEARNING_MAX_EVENTS) {
-    const lines = fs42.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
+    const lines = fs43.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
     if (lines.length > LEARNING_MAX_EVENTS) {
       const kept = lines.slice(lines.length - LEARNING_MAX_EVENTS);
-      fs42.writeFileSync(filePath, kept.join("\n") + "\n");
+      fs43.writeFileSync(filePath, kept.join("\n") + "\n");
     }
   }
 }
@@ -12080,19 +12455,19 @@ function appendEvent(event) {
   ensureLearningDir();
   const truncated = { ...event, tool_response: truncateResponse(event.tool_response) };
   const filePath = sessionFilePath();
-  fs42.appendFileSync(filePath, JSON.stringify(truncated) + "\n");
+  fs43.appendFileSync(filePath, JSON.stringify(truncated) + "\n");
   trimSessionFileIfNeeded(filePath);
 }
 function appendPromptEvent(event) {
   ensureLearningDir();
   const filePath = sessionFilePath();
-  fs42.appendFileSync(filePath, JSON.stringify(event) + "\n");
+  fs43.appendFileSync(filePath, JSON.stringify(event) + "\n");
   trimSessionFileIfNeeded(filePath);
 }
 function readAllEvents() {
   const filePath = sessionFilePath();
-  if (!fs42.existsSync(filePath)) return [];
-  const lines = fs42.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
+  if (!fs43.existsSync(filePath)) return [];
+  const lines = fs43.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
   const events = [];
   for (const line of lines) {
     try {
@@ -12104,26 +12479,26 @@ function readAllEvents() {
 }
 function getEventCount() {
   const filePath = sessionFilePath();
-  if (!fs42.existsSync(filePath)) return 0;
-  const content = fs42.readFileSync(filePath, "utf-8");
+  if (!fs43.existsSync(filePath)) return 0;
+  const content = fs43.readFileSync(filePath, "utf-8");
   return content.split("\n").filter(Boolean).length;
 }
 function clearSession() {
   const filePath = sessionFilePath();
-  if (fs42.existsSync(filePath)) fs42.unlinkSync(filePath);
+  if (fs43.existsSync(filePath)) fs43.unlinkSync(filePath);
 }
 function readState2() {
   const filePath = stateFilePath();
-  if (!fs42.existsSync(filePath)) return { ...DEFAULT_STATE };
+  if (!fs43.existsSync(filePath)) return { ...DEFAULT_STATE };
   try {
-    return JSON.parse(fs42.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs43.readFileSync(filePath, "utf-8"));
   } catch {
     return { ...DEFAULT_STATE };
   }
 }
 function writeState2(state) {
   ensureLearningDir();
-  fs42.writeFileSync(stateFilePath(), JSON.stringify(state, null, 2));
+  fs43.writeFileSync(stateFilePath(), JSON.stringify(state, null, 2));
 }
 function resetState() {
   writeState2({ ...DEFAULT_STATE });
@@ -12131,16 +12506,16 @@ function resetState() {
 var LOCK_FILE = "finalize.lock";
 var LOCK_STALE_MS = 5 * 60 * 1e3;
 function lockFilePath() {
-  return path34.join(getLearningDir(), LOCK_FILE);
+  return path35.join(getLearningDir(), LOCK_FILE);
 }
 function acquireFinalizeLock() {
   ensureLearningDir();
   const lockPath = lockFilePath();
-  if (fs42.existsSync(lockPath)) {
+  if (fs43.existsSync(lockPath)) {
     try {
-      const stat = fs42.statSync(lockPath);
+      const stat = fs43.statSync(lockPath);
       if (Date.now() - stat.mtimeMs < LOCK_STALE_MS) {
-        const pid = parseInt(fs42.readFileSync(lockPath, "utf-8").trim(), 10);
+        const pid = parseInt(fs43.readFileSync(lockPath, "utf-8").trim(), 10);
         if (!isNaN(pid) && isProcessAlive(pid)) {
           return false;
         }
@@ -12148,12 +12523,12 @@ function acquireFinalizeLock() {
     } catch {
     }
     try {
-      fs42.unlinkSync(lockPath);
+      fs43.unlinkSync(lockPath);
     } catch {
     }
   }
   try {
-    fs42.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+    fs43.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
     return true;
   } catch {
     return false;
@@ -12170,30 +12545,30 @@ function isProcessAlive(pid) {
 function releaseFinalizeLock() {
   const lockPath = lockFilePath();
   try {
-    if (fs42.existsSync(lockPath)) fs42.unlinkSync(lockPath);
+    if (fs43.existsSync(lockPath)) fs43.unlinkSync(lockPath);
   } catch {
   }
 }
 
 // src/lib/notifications.ts
-import fs43 from "fs";
-import path35 from "path";
+import fs44 from "fs";
+import path36 from "path";
 import chalk22 from "chalk";
 function notificationFilePath() {
-  return path35.join(getLearningDir(), "last-finalize-summary.json");
+  return path36.join(getLearningDir(), "last-finalize-summary.json");
 }
 function writeFinalizeSummary(summary) {
   try {
     ensureLearningDir();
-    fs43.writeFileSync(notificationFilePath(), JSON.stringify(summary, null, 2));
+    fs44.writeFileSync(notificationFilePath(), JSON.stringify(summary, null, 2));
   } catch {
   }
 }
 function checkPendingNotifications() {
   try {
-    if (!fs43.existsSync(notificationFilePath())) return;
-    const raw = fs43.readFileSync(notificationFilePath(), "utf-8");
-    fs43.unlinkSync(notificationFilePath());
+    if (!fs44.existsSync(notificationFilePath())) return;
+    const raw = fs44.readFileSync(notificationFilePath(), "utf-8");
+    fs44.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)` : "";
@@ -12209,7 +12584,7 @@ function checkPendingNotifications() {
     console.log("");
   } catch {
     try {
-      fs43.unlinkSync(notificationFilePath());
+      fs44.unlinkSync(notificationFilePath());
     } catch {
     }
   }
@@ -12361,8 +12736,8 @@ function calculateSessionWaste(events) {
 init_config();
 
 // src/learner/roi.ts
-import fs44 from "fs";
-import path36 from "path";
+import fs45 from "fs";
+import path37 from "path";
 var DEFAULT_TOTALS = {
   totalWasteTokens: 0,
   totalWasteSeconds: 0,
@@ -12376,19 +12751,19 @@ var DEFAULT_TOTALS = {
   lastSessionTimestamp: ""
 };
 function roiFilePath() {
-  return path36.join(getLearningDir(), LEARNING_ROI_FILE);
+  return path37.join(getLearningDir(), LEARNING_ROI_FILE);
 }
 function readROIStats() {
   const filePath = roiFilePath();
-  if (!fs44.existsSync(filePath)) {
+  if (!fs45.existsSync(filePath)) {
     return { learnings: [], sessions: [], totals: { ...DEFAULT_TOTALS } };
   }
   try {
-    return JSON.parse(fs44.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs45.readFileSync(filePath, "utf-8"));
   } catch {
     try {
       const corruptPath = filePath + ".corrupt";
-      fs44.renameSync(filePath, corruptPath);
+      fs45.renameSync(filePath, corruptPath);
       console.error(`caliber: roi-stats.json was corrupt \u2014 renamed to ${corruptPath}`);
     } catch {
     }
@@ -12397,7 +12772,7 @@ function readROIStats() {
 }
 function writeROIStats(stats) {
   ensureLearningDir();
-  fs44.writeFileSync(roiFilePath(), JSON.stringify(stats, null, 2));
+  fs45.writeFileSync(roiFilePath(), JSON.stringify(stats, null, 2));
 }
 function recalculateTotals(stats) {
   const totals = stats.totals;
@@ -12606,9 +12981,9 @@ var AUTO_SETTLE_MS = 200;
 var INCREMENTAL_INTERVAL = 50;
 function writeFinalizeError(message) {
   try {
-    const errorPath = path37.join(getLearningDir(), LEARNING_LAST_ERROR_FILE);
-    if (!fs45.existsSync(getLearningDir())) fs45.mkdirSync(getLearningDir(), { recursive: true });
-    fs45.writeFileSync(errorPath, JSON.stringify({
+    const errorPath = path38.join(getLearningDir(), LEARNING_LAST_ERROR_FILE);
+    if (!fs46.existsSync(getLearningDir())) fs46.mkdirSync(getLearningDir(), { recursive: true });
+    fs46.writeFileSync(errorPath, JSON.stringify({
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error: message,
       pid: process.pid
@@ -12618,9 +12993,9 @@ function writeFinalizeError(message) {
 }
 function readFinalizeError() {
   try {
-    const errorPath = path37.join(getLearningDir(), LEARNING_LAST_ERROR_FILE);
-    if (!fs45.existsSync(errorPath)) return null;
-    return JSON.parse(fs45.readFileSync(errorPath, "utf-8"));
+    const errorPath = path38.join(getLearningDir(), LEARNING_LAST_ERROR_FILE);
+    if (!fs46.existsSync(errorPath)) return null;
+    return JSON.parse(fs46.readFileSync(errorPath, "utf-8"));
   } catch {
     return null;
   }
@@ -12667,14 +13042,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 = path37.join(getLearningDir(), LEARNING_FINALIZE_LOG);
-        if (!fs45.existsSync(getLearningDir())) fs45.mkdirSync(getLearningDir(), { recursive: true });
-        const logFd = fs45.openSync(logPath, "a");
+        const logPath = path38.join(getLearningDir(), LEARNING_FINALIZE_LOG);
+        if (!fs46.existsSync(getLearningDir())) fs46.mkdirSync(getLearningDir(), { recursive: true });
+        const logFd = fs46.openSync(logPath, "a");
         spawn4(bin, ["learn", "finalize", "--auto", "--incremental"], {
           detached: true,
           stdio: ["ignore", logFd, logFd]
         }).unref();
-        fs45.closeSync(logFd);
+        fs46.closeSync(logFd);
       } catch {
       }
     }
@@ -12881,7 +13256,7 @@ async function learnFinalizeCommand(options) {
 }
 async function learnInstallCommand() {
   let anyInstalled = false;
-  if (fs45.existsSync(".claude")) {
+  if (fs46.existsSync(".claude")) {
     const r = installLearningHooks();
     if (r.installed) {
       console.log(chalk23.green("\u2713") + " Claude Code learning hooks installed");
@@ -12890,7 +13265,7 @@ async function learnInstallCommand() {
       console.log(chalk23.dim("  Claude Code hooks already installed"));
     }
   }
-  if (fs45.existsSync(".cursor")) {
+  if (fs46.existsSync(".cursor")) {
     const r = installCursorLearningHooks();
     if (r.installed) {
       console.log(chalk23.green("\u2713") + " Cursor learning hooks installed");
@@ -12899,7 +13274,7 @@ async function learnInstallCommand() {
       console.log(chalk23.dim("  Cursor hooks already installed"));
     }
   }
-  if (!fs45.existsSync(".claude") && !fs45.existsSync(".cursor")) {
+  if (!fs46.existsSync(".claude") && !fs46.existsSync(".cursor")) {
     console.log(chalk23.yellow("No .claude/ or .cursor/ directory found."));
     console.log(chalk23.dim(`  Run \`${resolveCaliber()} init\` first, or create the directory manually.`));
     return;
@@ -12957,8 +13332,8 @@ async function learnStatusCommand() {
   if (lastError) {
     console.log(`Last error: ${chalk23.red(lastError.error)}`);
     console.log(chalk23.dim(`  at ${lastError.timestamp}`));
-    const logPath = path37.join(getLearningDir(), LEARNING_FINALIZE_LOG);
-    if (fs45.existsSync(logPath)) {
+    const logPath = path38.join(getLearningDir(), LEARNING_FINALIZE_LOG);
+    if (fs46.existsSync(logPath)) {
       console.log(chalk23.dim(`  Full log: ${logPath}`));
     }
   }
@@ -13038,11 +13413,11 @@ async function learnDeleteCommand(indexStr) {
   }
   const item = items[targetIdx];
   const filePath = item.source === "personal" ? PERSONAL_LEARNINGS_FILE : "CALIBER_LEARNINGS.md";
-  if (!fs45.existsSync(filePath)) {
+  if (!fs46.existsSync(filePath)) {
     console.log(chalk23.red("Learnings file not found."));
     return;
   }
-  const content = fs45.readFileSync(filePath, "utf-8");
+  const content = fs46.readFileSync(filePath, "utf-8");
   const lines = content.split("\n");
   const bulletsOfSource = items.filter((i) => i.source === item.source);
   const posInFile = bulletsOfSource.indexOf(item);
@@ -13063,9 +13438,9 @@ async function learnDeleteCommand(indexStr) {
   }
   const bulletToRemove = lines[lineToRemove];
   const newLines = lines.filter((_, i) => i !== lineToRemove);
-  fs45.writeFileSync(filePath, newLines.join("\n"));
+  fs46.writeFileSync(filePath, newLines.join("\n"));
   if (item.source === "personal") {
-    fs45.chmodSync(filePath, 384);
+    fs46.chmodSync(filePath, 384);
   }
   const roiStats = readROIStats();
   const cleanText = bulletToRemove.replace(/^- /, "").replace(/^\*\*\[[^\]]+\]\*\*\s*/, "").trim();
@@ -13238,8 +13613,8 @@ async function insightsCommand(options) {
 }
 
 // src/commands/sources.ts
-import fs46 from "fs";
-import path38 from "path";
+import fs47 from "fs";
+import path39 from "path";
 import chalk25 from "chalk";
 init_resolve_caliber();
 async function sourcesListCommand() {
@@ -13256,9 +13631,9 @@ async function sourcesListCommand() {
   if (configSources.length > 0) {
     for (const source of configSources) {
       const sourcePath = source.path || source.url || "";
-      const exists = source.path ? fs46.existsSync(path38.resolve(dir, source.path)) : false;
+      const exists = source.path ? fs47.existsSync(path39.resolve(dir, source.path)) : false;
       const status = exists ? chalk25.green("reachable") : chalk25.red("not found");
-      const hasSummary = source.path && fs46.existsSync(path38.join(path38.resolve(dir, source.path), ".caliber", "summary.json"));
+      const hasSummary = source.path && fs47.existsSync(path39.join(path39.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)}`);
@@ -13268,7 +13643,7 @@ async function sourcesListCommand() {
   if (workspaces.length > 0) {
     console.log(chalk25.dim("  Auto-detected workspaces:"));
     for (const ws of workspaces) {
-      const exists = fs46.existsSync(path38.resolve(dir, ws));
+      const exists = fs47.existsSync(path39.resolve(dir, ws));
       console.log(`    ${exists ? chalk25.green("\u25CF") : chalk25.red("\u25CF")} ${ws}`);
     }
     console.log("");
@@ -13276,8 +13651,8 @@ async function sourcesListCommand() {
 }
 async function sourcesAddCommand(sourcePath) {
   const dir = process.cwd();
-  const absPath = path38.resolve(dir, sourcePath);
-  if (!fs46.existsSync(absPath)) {
+  const absPath = path39.resolve(dir, sourcePath);
+  if (!fs47.existsSync(absPath)) {
     console.log(chalk25.red(`
   Path not found: ${sourcePath}
 `));
@@ -13292,7 +13667,7 @@ async function sourcesAddCommand(sourcePath) {
   }
   const existing = loadSourcesConfig(dir);
   const alreadyConfigured = existing.some(
-    (s) => s.path && path38.resolve(dir, s.path) === absPath
+    (s) => s.path && path39.resolve(dir, s.path) === absPath
   );
   if (alreadyConfigured) {
     console.log(chalk25.yellow(`
@@ -13340,8 +13715,8 @@ async function sourcesRemoveCommand(name) {
 }
 
 // src/commands/publish.ts
-import fs47 from "fs";
-import path39 from "path";
+import fs48 from "fs";
+import path40 from "path";
 import chalk26 from "chalk";
 import ora7 from "ora";
 init_config();
@@ -13356,10 +13731,10 @@ async function publishCommand() {
   const spinner = ora7("Generating project summary...").start();
   try {
     const fingerprint = await collectFingerprint(dir);
-    const claudeMd = readFileOrNull(path39.join(dir, "CLAUDE.md"));
+    const claudeMd = readFileOrNull(path40.join(dir, "CLAUDE.md"));
     const topLevelDirs = fingerprint.fileTree.filter((f) => f.endsWith("/") && !f.includes("/")).map((f) => f.replace(/\/$/, ""));
     const summary = {
-      name: fingerprint.packageName || path39.basename(dir),
+      name: fingerprint.packageName || path40.basename(dir),
       version: "1.0.0",
       description: fingerprint.description || "",
       languages: fingerprint.languages,
@@ -13371,7 +13746,7 @@ async function publishCommand() {
       summary.conventions = claudeMd.slice(0, 2e3);
     }
     try {
-      const pkgContent = readFileOrNull(path39.join(dir, "package.json"));
+      const pkgContent = readFileOrNull(path40.join(dir, "package.json"));
       if (pkgContent) {
         const pkg3 = JSON.parse(pkgContent);
         if (pkg3.scripts) {
@@ -13384,14 +13759,14 @@ async function publishCommand() {
       }
     } catch {
     }
-    const outputDir = path39.join(dir, ".caliber");
-    if (!fs47.existsSync(outputDir)) {
-      fs47.mkdirSync(outputDir, { recursive: true });
+    const outputDir = path40.join(dir, ".caliber");
+    if (!fs48.existsSync(outputDir)) {
+      fs48.mkdirSync(outputDir, { recursive: true });
     }
-    const outputPath = path39.join(outputDir, "summary.json");
-    fs47.writeFileSync(outputPath, JSON.stringify(summary, null, 2) + "\n", "utf-8");
+    const outputPath = path40.join(outputDir, "summary.json");
+    fs48.writeFileSync(outputPath, JSON.stringify(summary, null, 2) + "\n", "utf-8");
     spinner.succeed("Project summary published");
-    console.log(`  ${chalk26.green("\u2713")} ${path39.relative(dir, outputPath)}`);
+    console.log(`  ${chalk26.green("\u2713")} ${path40.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) {
@@ -13404,7 +13779,7 @@ async function publishCommand() {
 
 // src/commands/bootstrap.ts
 init_builtin_skills();
-import fs48 from "fs";
+import fs49 from "fs";
 import chalk27 from "chalk";
 var PLATFORM_SKILL_DIRS = {
   claude: ".claude/skills",
@@ -13425,8 +13800,8 @@ async function bootstrapCommand() {
     for (const skill of BUILTIN_SKILLS) {
       const skillDir = `${skillsDir}/${skill.name}`;
       const skillPath = `${skillDir}/SKILL.md`;
-      fs48.mkdirSync(skillDir, { recursive: true });
-      fs48.writeFileSync(skillPath, buildSkillContent(skill));
+      fs49.mkdirSync(skillDir, { recursive: true });
+      fs49.writeFileSync(skillPath, buildSkillContent(skill));
       written.push(skillPath);
     }
   }
@@ -13443,8 +13818,8 @@ async function bootstrapCommand() {
 }
 
 // src/commands/uninstall.ts
-import fs49 from "fs";
-import path40 from "path";
+import fs50 from "fs";
+import path41 from "path";
 import chalk28 from "chalk";
 import confirm3 from "@inquirer/confirm";
 init_pre_commit_block();
@@ -13452,18 +13827,19 @@ init_builtin_skills();
 init_config();
 var MANAGED_DOC_FILES = [
   "CLAUDE.md",
-  path40.join(".github", "copilot-instructions.md"),
+  path41.join(".github", "copilot-instructions.md"),
   "AGENTS.md"
 ];
 var SKILL_DIRS = PLATFORM_CONFIGS.map((c) => c.skillsDir);
-var CURSOR_RULES_DIR = path40.join(".cursor", "rules");
-function removeCaliberCursorRules() {
+var CURSOR_RULES_DIR = path41.join(".cursor", "rules");
+var CLAUDE_RULES_DIR = path41.join(".claude", "rules");
+function removeCaliberManagedFiles(dir, extension) {
   const removed = [];
-  if (!fs49.existsSync(CURSOR_RULES_DIR)) return removed;
-  for (const file of fs49.readdirSync(CURSOR_RULES_DIR)) {
-    if (file.startsWith("caliber-") && file.endsWith(".mdc")) {
-      const fullPath = path40.join(CURSOR_RULES_DIR, file);
-      fs49.unlinkSync(fullPath);
+  if (!fs50.existsSync(dir)) return removed;
+  for (const file of fs50.readdirSync(dir)) {
+    if (file.startsWith(CALIBER_MANAGED_PREFIX) && file.endsWith(extension)) {
+      const fullPath = path41.join(dir, file);
+      fs50.unlinkSync(fullPath);
       removed.push(fullPath);
     }
   }
@@ -13472,11 +13848,11 @@ function removeCaliberCursorRules() {
 function removeBuiltinSkills() {
   const removed = [];
   for (const skillsDir of SKILL_DIRS) {
-    if (!fs49.existsSync(skillsDir)) continue;
+    if (!fs50.existsSync(skillsDir)) continue;
     for (const name of BUILTIN_SKILL_NAMES) {
-      const skillDir = path40.join(skillsDir, name);
-      if (fs49.existsSync(skillDir)) {
-        fs49.rmSync(skillDir, { recursive: true });
+      const skillDir = path41.join(skillsDir, name);
+      if (fs50.existsSync(skillDir)) {
+        fs50.rmSync(skillDir, { recursive: true });
         removed.push(skillDir);
       }
     }
@@ -13486,15 +13862,15 @@ function removeBuiltinSkills() {
 function stripManagedBlocksFromFiles() {
   const modified = [];
   for (const filePath of MANAGED_DOC_FILES) {
-    if (!fs49.existsSync(filePath)) continue;
-    const original = fs49.readFileSync(filePath, "utf-8");
+    if (!fs50.existsSync(filePath)) continue;
+    const original = fs50.readFileSync(filePath, "utf-8");
     const stripped = stripManagedBlocks(original);
     if (stripped !== original) {
       const trimmed = stripped.trim();
       if (!trimmed || /^#\s*\S*$/.test(trimmed)) {
-        fs49.unlinkSync(filePath);
+        fs50.unlinkSync(filePath);
       } else {
-        fs49.writeFileSync(filePath, stripped);
+        fs50.writeFileSync(filePath, stripped);
       }
       modified.push(filePath);
     }
@@ -13502,8 +13878,8 @@ function stripManagedBlocksFromFiles() {
   return modified;
 }
 function removeDirectory(dir) {
-  if (!fs49.existsSync(dir)) return false;
-  fs49.rmSync(dir, { recursive: true });
+  if (!fs50.existsSync(dir)) return false;
+  fs50.rmSync(dir, { recursive: true });
   return true;
 }
 async function uninstallCommand(options) {
@@ -13535,6 +13911,16 @@ async function uninstallCommand(options) {
     console.log(`  ${chalk28.red("\u2717")} Onboarding hook removed`);
     actions.push("onboarding hook");
   }
+  const notificationHookResult = removeNotificationHook();
+  if (notificationHookResult.removed) {
+    console.log(`  ${chalk28.red("\u2717")} Notification hook removed`);
+    actions.push("notification hook");
+  }
+  const sessionStartResult = removeSessionStartHook();
+  if (sessionStartResult.removed) {
+    console.log(`  ${chalk28.red("\u2717")} SessionStart hook removed`);
+    actions.push("session-start hook");
+  }
   const learnResult = removeLearningHooks();
   if (learnResult.removed) {
     console.log(`  ${chalk28.red("\u2717")} Claude Code learning hooks removed`);
@@ -13550,18 +13936,23 @@ async function uninstallCommand(options) {
     console.log(`  ${chalk28.yellow("~")} ${file} \u2014 managed blocks removed`);
     actions.push(file);
   }
-  const removedRules = removeCaliberCursorRules();
-  for (const rule of removedRules) {
+  const removedCursorRules = removeCaliberManagedFiles(CURSOR_RULES_DIR, ".mdc");
+  for (const rule of removedCursorRules) {
     console.log(`  ${chalk28.red("\u2717")} ${rule}`);
   }
-  if (removedRules.length > 0) actions.push("cursor rules");
+  if (removedCursorRules.length > 0) actions.push("cursor rules");
+  const removedClaudeRules = removeCaliberManagedFiles(CLAUDE_RULES_DIR, ".md");
+  for (const rule of removedClaudeRules) {
+    console.log(`  ${chalk28.red("\u2717")} ${rule}`);
+  }
+  if (removedClaudeRules.length > 0) actions.push("claude rules");
   const removedSkills = removeBuiltinSkills();
   for (const skill of removedSkills) {
     console.log(`  ${chalk28.red("\u2717")} ${skill}/`);
   }
   if (removedSkills.length > 0) actions.push("builtin skills");
-  if (fs49.existsSync("CALIBER_LEARNINGS.md")) {
-    fs49.unlinkSync("CALIBER_LEARNINGS.md");
+  if (fs50.existsSync("CALIBER_LEARNINGS.md")) {
+    fs50.unlinkSync("CALIBER_LEARNINGS.md");
     console.log(`  ${chalk28.red("\u2717")} CALIBER_LEARNINGS.md`);
     actions.push("learnings file");
   }
@@ -13575,18 +13966,18 @@ async function uninstallCommand(options) {
   }
   trackUninstallExecuted();
   const configPath = getConfigFilePath();
-  if (fs49.existsSync(configPath)) {
+  if (fs50.existsSync(configPath)) {
     console.log("");
     const removeConfig = options.force || await confirm3({
       message: `Remove global config (~/.caliber/config.json)? This affects all projects.`
     });
     if (removeConfig) {
-      fs49.unlinkSync(configPath);
+      fs50.unlinkSync(configPath);
       console.log(`  ${chalk28.red("\u2717")} ${configPath}`);
-      const configDir = path40.dirname(configPath);
+      const configDir = path41.dirname(configPath);
       try {
-        const remaining = fs49.readdirSync(configDir);
-        if (remaining.length === 0) fs49.rmdirSync(configDir);
+        const remaining = fs50.readdirSync(configDir);
+        if (remaining.length === 0) fs50.rmdirSync(configDir);
       } catch {
       }
     }
@@ -13597,8 +13988,8 @@ async function uninstallCommand(options) {
 }
 
 // src/cli.ts
-var __dirname = path41.dirname(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(fs50.readFileSync(path41.resolve(__dirname, "..", "package.json"), "utf-8"));
+var __dirname = path42.dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(fs51.readFileSync(path42.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("AI context infrastructure for coding agents").version(displayVersion).option("--no-traces", "Disable anonymous telemetry for this run");
@@ -13709,15 +14100,15 @@ 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 fs51 from "fs";
-import path42 from "path";
+import fs52 from "fs";
+import path43 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { execSync as execSync16, execFileSync as execFileSync3 } from "child_process";
 import chalk29 from "chalk";
 import ora8 from "ora";
 import confirm4 from "@inquirer/confirm";
-var __dirname_vc = path42.dirname(fileURLToPath2(import.meta.url));
-var pkg2 = JSON.parse(fs51.readFileSync(path42.resolve(__dirname_vc, "..", "package.json"), "utf-8"));
+var __dirname_vc = path43.dirname(fileURLToPath2(import.meta.url));
+var pkg2 = JSON.parse(fs52.readFileSync(path43.resolve(__dirname_vc, "..", "package.json"), "utf-8"));
 function getChannel(version) {
   const match = version.match(/-(dev|next)\./);
   return match ? match[1] : "latest";
@@ -13744,8 +14135,8 @@ function getInstalledVersion() {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
-    const pkgPath = path42.join(globalRoot, "@rely-ai", "caliber", "package.json");
-    return JSON.parse(fs51.readFileSync(pkgPath, "utf-8")).version;
+    const pkgPath = path43.join(globalRoot, "@rely-ai", "caliber", "package.json");
+    return JSON.parse(fs52.readFileSync(pkgPath, "utf-8")).version;
   } catch {
     return null;
   }