@rely-ai/caliber 1.38.0 → 1.40.0

package/dist/bin.js

@@ -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,
@@ -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() {
@@ -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;
@@ -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"))
@@ -11169,6 +11345,14 @@ function scopeDiffToDir(diff, dir, allConfigDirs) {
 init_pre_commit_block();
 import fs37 from "fs";
 import path30 from "path";
+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, "/");
@@ -11188,6 +11372,9 @@ function writeRefreshDocs(docs, dir = ".") {
     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) {
     const filePath = p("README.md");
     ensureParent(filePath);
@@ -11201,12 +11388,7 @@ function writeRefreshDocs(docs, dir = ".") {
     written.push(filePath);
   }
   if (docs.cursorRules) {
-    const rulesDir = p(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(p(path30.join(".cursor", "rules", rule.filename)));
-    }
+    written.push(...writeFileGroup(p(path30.join(".cursor", "rules")), docs.cursorRules));
   }
   if (docs.copilotInstructions) {
     const filePath = p(path30.join(".github", "copilot-instructions.md"));
@@ -11215,12 +11397,9 @@ function writeRefreshDocs(docs, dir = ".") {
     written.push(filePath);
   }
   if (docs.copilotInstructionFiles) {
-    const instructionsDir = p(path30.join(".github", "instructions"));
-    if (!fs37.existsSync(instructionsDir)) fs37.mkdirSync(instructionsDir, { recursive: true });
-    for (const file of docs.copilotInstructionFiles) {
-      fs37.writeFileSync(path30.join(instructionsDir, file.filename), file.content);
-      written.push(p(path30.join(".github", "instructions", file.filename)));
-    }
+    written.push(
+      ...writeFileGroup(p(path30.join(".github", "instructions")), docs.copilotInstructionFiles)
+    );
   }
   return written;
 }
@@ -11307,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);
@@ -11326,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:");
@@ -11669,6 +11866,10 @@ function collectFilesToWrite(updatedDocs, dir = ".") {
   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)) {
@@ -11964,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() {
@@ -11979,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) {
@@ -13611,12 +13832,13 @@ var MANAGED_DOC_FILES = [
 ];
 var SKILL_DIRS = PLATFORM_CONFIGS.map((c) => c.skillsDir);
 var CURSOR_RULES_DIR = path41.join(".cursor", "rules");
-function removeCaliberCursorRules() {
+var CLAUDE_RULES_DIR = path41.join(".claude", "rules");
+function removeCaliberManagedFiles(dir, extension) {
   const removed = [];
-  if (!fs50.existsSync(CURSOR_RULES_DIR)) return removed;
-  for (const file of fs50.readdirSync(CURSOR_RULES_DIR)) {
-    if (file.startsWith("caliber-") && file.endsWith(".mdc")) {
-      const fullPath = path41.join(CURSOR_RULES_DIR, file);
+  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);
     }
@@ -13689,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`);
@@ -13704,11 +13936,16 @@ 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 (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 (removedRules.length > 0) actions.push("cursor rules");
+  if (removedClaudeRules.length > 0) actions.push("claude rules");
   const removedSkills = removeBuiltinSkills();
   for (const skill of removedSkills) {
     console.log(`  ${chalk28.red("\u2717")} ${skill}/`);

package/package.json

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