ctxloom-pro 1.3.0 → 1.4.0

package/dist/{chunk-Q2KTZNNU.js → chunk-7GZVGIQL.js}

@@ -5,6 +5,9 @@ import {
   collectFiles,
   generateEmbedding
 } from "./chunk-UVR65QBJ.js";
+import {
+  diskSink
+} from "./chunk-5I6CJITG.js";
 import {
   logger
 } from "./chunk-TYDMSHV7.js";
@@ -3457,8 +3460,8 @@ var CoChangeIndex = class _CoChangeIndex {
     if (event.isBulk || event.isMerge) return;
     const paths = event.files.map((f) => f.path);
     if (paths.length === 0) return;
-    for (const path36 of paths) {
-      this.nodeCounts.set(path36, (this.nodeCounts.get(path36) ?? 0) + 1);
+    for (const path37 of paths) {
+      this.nodeCounts.set(path37, (this.nodeCounts.get(path37) ?? 0) + 1);
     }
     for (let i = 0; i < paths.length; i++) {
       for (let j = i + 1; j < paths.length; j++) {
@@ -3605,8 +3608,8 @@ var ChurnIndex = class _ChurnIndex {
    */
   snapshot() {
     const nodes = {};
-    for (const [path36, raw] of this.nodes) {
-      nodes[path36] = {
+    for (const [path37, raw] of this.nodes) {
+      nodes[path37] = {
         commits: raw.commits,
         churnLines: raw.churnLines,
         bugCommits: raw.bugCommits,
@@ -3621,8 +3624,8 @@ var ChurnIndex = class _ChurnIndex {
    */
   static load(s) {
     const idx = new _ChurnIndex();
-    for (const [path36, raw] of Object.entries(s.nodes)) {
-      idx.nodes.set(path36, {
+    for (const [path37, raw] of Object.entries(s.nodes)) {
+      idx.nodes.set(path37, {
         commits: raw.commits,
         churnLines: raw.churnLines,
         bugCommits: raw.bugCommits,
@@ -3635,8 +3638,8 @@ var ChurnIndex = class _ChurnIndex {
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  getOrCreate(path36) {
-    const existing = this.nodes.get(path36);
+  getOrCreate(path37) {
+    const existing = this.nodes.get(path37);
     if (existing !== void 0) return existing;
     const fresh = {
       commits: 0,
@@ -3645,7 +3648,7 @@ var ChurnIndex = class _ChurnIndex {
       authorCounts: {},
       lastTouch: 0
     };
-    this.nodes.set(path36, fresh);
+    this.nodes.set(path37, fresh);
     return fresh;
   }
 };
@@ -3726,12 +3729,12 @@ var OwnershipIndex = class _OwnershipIndex {
    */
   snapshot() {
     const nodes = {};
-    for (const [path36, raw] of this.nodes) {
+    for (const [path37, raw] of this.nodes) {
       const authorWeights = {};
       for (const [email, entry] of Object.entries(raw.authorWeights)) {
         authorWeights[email] = { ...entry };
       }
-      nodes[path36] = { authorWeights, lastTouch: raw.lastTouch };
+      nodes[path37] = { authorWeights, lastTouch: raw.lastTouch };
     }
     return { version: 1, nodes };
   }
@@ -3740,23 +3743,23 @@ var OwnershipIndex = class _OwnershipIndex {
    */
   static load(s) {
     const idx = new _OwnershipIndex();
-    for (const [path36, raw] of Object.entries(s.nodes)) {
+    for (const [path37, raw] of Object.entries(s.nodes)) {
       const authorWeights = {};
       for (const [email, entry] of Object.entries(raw.authorWeights)) {
         authorWeights[email] = { ...entry };
       }
-      idx.nodes.set(path36, { authorWeights, lastTouch: raw.lastTouch });
+      idx.nodes.set(path37, { authorWeights, lastTouch: raw.lastTouch });
     }
     return idx;
   }
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  getOrCreate(path36) {
-    const existing = this.nodes.get(path36);
+  getOrCreate(path37) {
+    const existing = this.nodes.get(path37);
     if (existing !== void 0) return existing;
     const fresh = { authorWeights: {}, lastTouch: 0 };
-    this.nodes.set(path36, fresh);
+    this.nodes.set(path37, fresh);
     return fresh;
   }
 };
@@ -4562,7 +4565,7 @@ function renderStatusXml(input) {
   return lines.join("\n");
 }
 function registerStatusTool(registry, ctx) {
-  const Schema30 = z2.object({ project_root: ProjectRootField });
+  const Schema31 = z2.object({ project_root: ProjectRootField });
   registry.register(
     "ctx_status",
     {
@@ -4576,7 +4579,7 @@ function registerStatusTool(registry, ctx) {
       }
     },
     async (args) => {
-      const { project_root } = Schema30.parse(args ?? {});
+      const { project_root } = Schema31.parse(args ?? {});
       void project_root;
       return renderStatusXml({
         defaultRoot: ctx.noDefaultMode ? null : ctx.projectRoot,
@@ -4611,6 +4614,325 @@ var ToolRegistry = class {
 // packages/core/src/tools/search.ts
 import { z as z3 } from "zod";
 
+// packages/core/src/budget/nextToolSuggestions.ts
+var STATIC_RULES = {
+  // ─── Source-returning / file-shaped tools ────────────────────────
+  ctx_get_file: [
+    {
+      tool: "ctx_get_call_graph",
+      why: "Check who depends on this file before modifying.",
+      estimated_tokens: 800
+    },
+    {
+      tool: "ctx_get_definition",
+      why: "Cheaper view if you need a specific symbol, not the whole file.",
+      estimated_tokens: 2e3
+    },
+    {
+      tool: "ctx_blast_radius",
+      why: "Transitive impact analysis before a write.",
+      estimated_tokens: 1500
+    }
+  ],
+  ctx_get_definition: [
+    {
+      tool: "ctx_get_call_graph",
+      why: "Who calls this symbol? Almost always your next step.",
+      estimated_tokens: 800
+    },
+    {
+      tool: "ctx_blast_radius",
+      why: "What would break if this signature changes?",
+      estimated_tokens: 1500
+    }
+  ],
+  ctx_get_context_packet: [
+    {
+      tool: "ctx_get_call_graph",
+      why: "Surface external callers not visible inside the packet.",
+      estimated_tokens: 800
+    },
+    {
+      tool: "ctx_get_affected_flows",
+      why: "Execution-flow coverage of the packet files.",
+      estimated_tokens: 2e3
+    }
+  ],
+  ctx_search: [
+    {
+      tool: "ctx_get_definition",
+      why: "Pull the canonical definition of a top result.",
+      estimated_tokens: 2e3
+    },
+    {
+      tool: "ctx_similar_files",
+      why: "Find related files outside the keyword/vector hit set.",
+      estimated_tokens: 1e3
+    }
+  ],
+  ctx_full_text_search: [
+    {
+      tool: "ctx_get_file",
+      why: "Inspect a specific match in context.",
+      estimated_tokens: 8e3
+    },
+    {
+      tool: "ctx_get_call_graph",
+      why: "Caller graph for matched symbols.",
+      estimated_tokens: 800
+    }
+  ],
+  ctx_similar_files: [
+    {
+      tool: "ctx_get_context_packet",
+      why: "Bundle the cluster into a single packet for review.",
+      estimated_tokens: 6e3
+    }
+  ],
+  // ─── Graph / structural queries ──────────────────────────────────
+  // ctx_get_call_graph is the canonical "find callers" tool — pass
+  // direction: 'callers' or 'callees' in args. The follow-ups below
+  // assume the caller is investigating impact / coverage on the
+  // returned caller set.
+  ctx_get_call_graph: [
+    {
+      tool: "ctx_blast_radius",
+      why: "Transitive dependents \u2014 callers of the callers you just found.",
+      estimated_tokens: 1500
+    },
+    {
+      tool: "ctx_get_affected_flows",
+      why: "Which execution paths break if any caller is removed?",
+      estimated_tokens: 2e3
+    },
+    {
+      tool: "ctx_execution_flow",
+      why: "Linearize the caller set into ordered execution sequences.",
+      estimated_tokens: 4e3
+    }
+  ],
+  ctx_blast_radius: [
+    {
+      tool: "ctx_get_affected_flows",
+      why: "Execution-flow impact on the affected files.",
+      estimated_tokens: 2e3
+    },
+    { tool: "ctx_knowledge_gaps", why: "Identify test-coverage gaps on affected files.", estimated_tokens: 1200 }
+  ],
+  ctx_get_affected_flows: [
+    {
+      tool: "ctx_execution_flow",
+      why: "Drill into a specific affected flow.",
+      estimated_tokens: 4e3
+    },
+    {
+      tool: "ctx_blast_radius",
+      why: "Reverse direction \u2014 what affects this flow?",
+      estimated_tokens: 1500
+    }
+  ],
+  ctx_execution_flow: [
+    {
+      tool: "ctx_get_call_graph",
+      why: "External callers of the flow entry-point.",
+      estimated_tokens: 800
+    }
+  ],
+  // ─── Architecture / overview tools ───────────────────────────────
+  ctx_architecture_overview: [
+    {
+      tool: "ctx_community_list",
+      why: "Drill into a specific community.",
+      estimated_tokens: 1e3
+    },
+    {
+      tool: "ctx_hub_nodes",
+      why: "Top fan-in/out nodes deserving deeper inspection.",
+      estimated_tokens: 1200
+    },
+    {
+      tool: "ctx_bridge_nodes",
+      why: "Cross-community bridges (high architectural leverage).",
+      estimated_tokens: 1e3
+    }
+  ],
+  ctx_community_list: [
+    {
+      tool: "ctx_get_context_packet",
+      why: "Bundle a community into a single review packet.",
+      estimated_tokens: 6e3
+    }
+  ],
+  ctx_hub_nodes: [
+    {
+      tool: "ctx_get_call_graph",
+      why: "Who depends on the top hub?",
+      estimated_tokens: 800
+    },
+    {
+      tool: "ctx_blast_radius",
+      why: "Hub change-impact analysis.",
+      estimated_tokens: 1500
+    }
+  ],
+  ctx_bridge_nodes: [
+    {
+      tool: "ctx_get_call_graph",
+      why: "Callers across the bridge.",
+      estimated_tokens: 800
+    }
+  ],
+  ctx_surprising_connections: [
+    {
+      tool: "ctx_blast_radius",
+      why: "Impact analysis on a surprising-connection target.",
+      estimated_tokens: 1500
+    }
+  ],
+  // ─── Review / diff tools ─────────────────────────────────────────
+  ctx_detect_changes: [
+    {
+      tool: "ctx_get_file",
+      why: "Inspect a specific risky file.",
+      estimated_tokens: 8e3
+    },
+    {
+      tool: "ctx_get_affected_flows",
+      why: "Which execution paths the change touches.",
+      estimated_tokens: 2e3
+    },
+    {
+      tool: "ctx_git_diff_review",
+      why: "Full diff packet for the changeset.",
+      estimated_tokens: 8e3
+    }
+  ],
+  ctx_git_diff_review: [
+    {
+      tool: "ctx_risk_overlay",
+      why: "Score the changed files by historical churn + coupling.",
+      estimated_tokens: 1500
+    },
+    {
+      tool: "ctx_get_call_graph",
+      why: "Caller-side impact of the changes.",
+      estimated_tokens: 800
+    }
+  ],
+  ctx_risk_overlay: [
+    {
+      tool: "ctx_get_file",
+      why: "Inspect the highest-risk file in detail.",
+      estimated_tokens: 8e3
+    }
+  ],
+  ctx_git_coupling: [
+    {
+      tool: "ctx_blast_radius",
+      why: "Static impact analysis to complement co-change signal.",
+      estimated_tokens: 1500
+    }
+  ],
+  // ─── Refactor tools ──────────────────────────────────────────────
+  ctx_refactor_preview: [
+    {
+      tool: "ctx_apply_refactor",
+      why: "Commit the preview after you reviewed the rename.",
+      estimated_tokens: 2e3
+    }
+  ],
+  ctx_apply_refactor: [
+    {
+      tool: "ctx_detect_changes",
+      why: "Verify the refactor produced the expected risk profile.",
+      estimated_tokens: 1500
+    }
+  ],
+  // ─── Knowledge / coverage tools ──────────────────────────────────
+  ctx_knowledge_gaps: [
+    { tool: "ctx_knowledge_gaps", why: "Identify test-coverage gaps on affected files.", estimated_tokens: 1200 },
+    {
+      tool: "ctx_get_call_graph",
+      why: "Caller frequency on untested symbols (impact ranking).",
+      estimated_tokens: 800
+    }
+  ],
+  ctx_find_large_functions: [
+    {
+      tool: "ctx_get_definition",
+      why: "Inspect the largest function.",
+      estimated_tokens: 2e3
+    }
+  ],
+  // ─── Metadata / status ───────────────────────────────────────────
+  ctx_get_minimal_context: [
+    // intentionally empty — the suggested_first_tool field IS the
+    // next-step suggestion. Adding rules here would be redundant.
+  ],
+  ctx_status: [],
+  ctx_get_rules: [
+    {
+      tool: "ctx_rules_check",
+      why: "Validate code against rules.",
+      estimated_tokens: 1200
+    }
+  ],
+  ctx_rules_check: [],
+  ctx_get_workflow: [],
+  ctx_suggested_questions: [],
+  // ─── Wiki / export ───────────────────────────────────────────────
+  ctx_wiki_generate: [
+    {
+      tool: "ctx_architecture_overview",
+      why: "Confirm the wiki structure against the live overview.",
+      estimated_tokens: 2e3
+    }
+  ],
+  ctx_graph_export: [],
+  ctx_graph_snapshot: [
+    {
+      tool: "ctx_graph_diff",
+      why: "Compare against a later snapshot.",
+      estimated_tokens: 2e3
+    }
+  ],
+  ctx_graph_diff: [
+    {
+      tool: "ctx_detect_changes",
+      why: "Risk-scored view of the graph delta.",
+      estimated_tokens: 1500
+    }
+  ],
+  // ─── Cross-repo ──────────────────────────────────────────────────
+  ctx_cross_repo_search: [
+    {
+      tool: "ctx_get_file",
+      why: "Inspect a hit in a specific repo.",
+      estimated_tokens: 8e3
+    }
+  ]
+  // ─── Query primitive ─────────────────────────────────────────────
+  // ─── Affected flows (sibling to get_affected_flows but worth pinning) ─
+  // ─── Definition aliases / structurals not listed above are deliberate
+  //     — the test enforces the full registered-tool list is covered.
+};
+var TOKEN_ESTIMATE_MIN = 0;
+var TOKEN_ESTIMATE_MAX = 1e5;
+function clampEstimate(n) {
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(TOKEN_ESTIMATE_MIN, Math.min(TOKEN_ESTIMATE_MAX, Math.round(n)));
+}
+function suggestNext(fromTool, registeredTools) {
+  const raw = STATIC_RULES[fromTool] ?? [];
+  const filtered = registeredTools ? raw.filter((s) => registeredTools.has(s.tool)) : raw;
+  return filtered.slice(0, 3).map((s) => ({
+    tool: s.tool,
+    args: s.args,
+    why: s.why,
+    estimated_tokens: clampEstimate(s.estimated_tokens)
+  }));
+}
+
 // packages/core/src/budget/budget.ts
 var defaultTokenEstimator = (text) => Math.ceil(text.length / 4);
 function hasBudgetArgs(args) {
@@ -4634,23 +4956,33 @@ function readBudgetArgs(args) {
 function isBudgetDisabled() {
   return process.env.CTXLOOM_DISABLE_BUDGET === "1";
 }
-function emitTelemetry(event) {
+function emitTelemetry(event, sink = diskSink) {
   if (process.env.CTXLOOM_TELEMETRY_LEVEL !== "full") return;
   logger.info(event.event, event);
+  try {
+    sink.append(event);
+  } catch {
+  }
 }
 async function enforceBudget(opts) {
   const { full, args, toolName, defaultMaxTokens, skeletonProducer } = opts;
   const estimate = opts.estimator ?? defaultTokenEstimator;
+  const sink = opts.sink ?? opts.ctx?.telemetrySink ?? diskSink;
+  const nextToolSuggestions = suggestNext(toolName);
+  const withSuggestions = (base) => {
+    if (nextToolSuggestions.length === 0) return base;
+    return { ...base, next_tool_suggestions: nextToolSuggestions };
+  };
   const originalTokens = estimate(full);
   if (isBudgetDisabled()) {
     return {
       text: full,
-      meta: {
+      meta: withSuggestions({
         format: "full",
         original_tokens_est: originalTokens,
         returned_tokens_est: originalTokens,
         fallback_reason: null
-      }
+      })
     };
   }
   if (args.response_format === "skeleton" && skeletonProducer) {
@@ -4659,45 +4991,45 @@ async function enforceBudget(opts) {
       const skTokens = estimate(skeleton2);
       return {
         text: skeleton2,
-        meta: {
+        meta: withSuggestions({
           format: "skeleton",
           original_tokens_est: originalTokens,
           returned_tokens_est: skTokens,
           fallback_reason: null
-        }
+        })
       };
     }
     return {
       text: full,
-      meta: {
+      meta: withSuggestions({
         format: "full",
         original_tokens_est: originalTokens,
         returned_tokens_est: originalTokens,
         fallback_reason: "skeleton_failed"
-      }
+      })
     };
   }
   const budget = args.max_response_tokens ?? defaultMaxTokens;
   if (budget === void 0) {
     return {
       text: full,
-      meta: {
+      meta: withSuggestions({
         format: "full",
         original_tokens_est: originalTokens,
         returned_tokens_est: originalTokens,
         fallback_reason: null
-      }
+      })
     };
   }
   if (originalTokens <= budget) {
     return {
       text: full,
-      meta: {
+      meta: withSuggestions({
         format: "full",
         original_tokens_est: originalTokens,
         returned_tokens_est: originalTokens,
         fallback_reason: null
-      }
+      })
     };
   }
   emitTelemetry({
@@ -4706,7 +5038,7 @@ async function enforceBudget(opts) {
     original_tokens: originalTokens,
     budget,
     ratio: originalTokens / budget
-  });
+  }, sink);
   const mode = args.on_budget_exceeded ?? "skeleton";
   if (mode === "error") {
     const err = new Error(
@@ -4725,15 +5057,15 @@ async function enforceBudget(opts) {
       tool: toolName,
       fallback_reason: "budget_exceeded",
       mode: "truncate"
-    });
+    }, sink);
     return {
       text: sliced2,
-      meta: {
+      meta: withSuggestions({
         format: "truncated",
         original_tokens_est: originalTokens,
         returned_tokens_est: slicedTokens,
         fallback_reason: "budget_exceeded"
-      }
+      })
     };
   }
   const skeleton = skeletonProducer ? await safeSkeleton(skeletonProducer, toolName) : null;
@@ -4745,15 +5077,15 @@ async function enforceBudget(opts) {
         tool: toolName,
         fallback_reason: "budget_exceeded",
         mode: "skeleton"
-      });
+      }, sink);
       return {
         text: skeleton,
-        meta: {
+        meta: withSuggestions({
           format: "skeleton",
           original_tokens_est: originalTokens,
           returned_tokens_est: skTokens,
           fallback_reason: "budget_exceeded"
-        }
+        })
       };
     }
     const slicedSk = skeleton.slice(0, budget * 4);
@@ -4762,15 +5094,15 @@ async function enforceBudget(opts) {
       tool: toolName,
       fallback_reason: "budget_exceeded",
       mode: "skeleton+truncate"
-    });
+    }, sink);
     return {
       text: slicedSk,
-      meta: {
+      meta: withSuggestions({
         format: "truncated",
         original_tokens_est: originalTokens,
         returned_tokens_est: estimate(slicedSk),
         fallback_reason: "budget_exceeded"
-      }
+      })
     };
   }
   const sliced = full.slice(0, budget * 4);
@@ -4779,15 +5111,15 @@ async function enforceBudget(opts) {
     tool: toolName,
     fallback_reason: "skeleton_failed",
     mode: "truncate-fallback"
-  });
+  }, sink);
   return {
     text: sliced,
-    meta: {
+    meta: withSuggestions({
       format: "truncated",
       original_tokens_est: originalTokens,
       returned_tokens_est: estimate(sliced),
       fallback_reason: "skeleton_failed"
-    }
+    })
   };
 }
 async function safeSkeleton(producer, toolName) {
@@ -4887,6 +5219,7 @@ function registerSearchTool(registry, ctx) {
       if (!hasBudgetArgs(args)) return full;
       const skeletonProducer = async () => renderResults(parsed.query, ranked, false);
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_search",
@@ -4946,6 +5279,7 @@ function registerFileTool(registry, ctx) {
       const absPath = validator.validate(parsed.path);
       const skeletonizer = await ctx.getSkeletonizer(parsed.project_root);
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_get_file",
@@ -5054,6 +5388,7 @@ ${sk}`;
         return renderPacket({ ...parts, primaryContent: primarySkeleton });
       };
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_get_context_packet",
@@ -5217,6 +5552,7 @@ function registerDefinitionTool(registry, ctx) {
       }
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_get_definition",
@@ -6258,6 +6594,7 @@ function registerWikiGenerateTool(registry, ctx) {
       const full = detail_level === "minimal" ? renderMinimal() : renderStandard();
       if (!hasBudgetArgs(args)) return full;
       const budgetResult = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_wiki_generate",
@@ -6405,6 +6742,7 @@ function registerGitDiffReviewTool(registry, ctx) {
       const maybeBudget = async (full2, skeletonProducer) => {
         if (!hasBudgetArgs(args)) return full2;
         const result = await enforceBudget({
+          ctx,
           full: full2,
           args: readBudgetArgs(args),
           toolName: "ctx_git_diff_review",
@@ -6440,7 +6778,7 @@ function registerGitDiffReviewTool(registry, ctx) {
           skeleton: include_skeletons && i < skeletonLimit ? await trySkeletonize(ctx, file, project_root) : ""
         }))
       );
-      const render = (withSkeletons, withTransitive) => {
+      const render2 = (withSkeletons, withTransitive) => {
         const out = [`<git_diff_review changed_files="${files.length}" depth="${depth}">`];
         out.push(`  <changed_files count="${files.length}">`);
         for (const cd of changedFileData) {
@@ -6486,8 +6824,8 @@ function registerGitDiffReviewTool(registry, ctx) {
         out.push("</git_diff_review>");
         return out.join("\n");
       };
-      const full = render(include_skeletons, true);
-      return maybeBudget(full, async () => render(false, false));
+      const full = render2(include_skeletons, true);
+      return maybeBudget(full, async () => render2(false, false));
     }
   );
 }
@@ -6589,7 +6927,7 @@ function registerRefactorPreviewTool(registry, ctx) {
           totalOccurrences += occurrences.length;
         }
       }
-      const render = (includeChanges) => {
+      const render2 = (includeChanges) => {
         const xmlLines = [
           `<refactor_preview symbol="${escapeXML17(symbol)}" new_name="${escapeXML17(new_name)}" total_files="${fileChanges.length}" total_occurrences="${totalOccurrences}">`
         ];
@@ -6619,14 +6957,15 @@ function registerRefactorPreviewTool(registry, ctx) {
         xmlLines.push("</refactor_preview>");
         return xmlLines.join("\n");
       };
-      const full = render(true);
+      const full = render2(true);
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_refactor_preview",
         defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS7,
-        skeletonProducer: async () => render(false)
+        skeletonProducer: async () => render2(false)
       });
       return wrapResponse(result);
     }
@@ -6743,6 +7082,7 @@ function registerExecutionFlowTool(registry, ctx) {
       const maybeBudget = async (full) => {
         if (!hasBudgetArgs(args)) return full;
         const result = await enforceBudget({
+          ctx,
           full,
           args: readBudgetArgs(args),
           toolName: "ctx_execution_flow",
@@ -6899,7 +7239,7 @@ var Schema20 = z22.object({
 function escapeXML19(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function registerCrossRepoSearchTool(registry, _ctx, registryFilePath) {
+function registerCrossRepoSearchTool(registry, ctx, registryFilePath) {
   const repoRegistryPath = registryFilePath ?? path18.join(process.env.HOME ?? process.env.USERPROFILE ?? "", ".ctxloom", "repos.json");
   registry.register(
     "ctx_cross_repo_search",
@@ -6988,7 +7328,7 @@ function registerCrossRepoSearchTool(registry, _ctx, registryFilePath) {
         );
       }
       xmlLines.push("  </repos>");
-      const render = (includeContent) => {
+      const render2 = (includeContent) => {
         const out = [...xmlLines];
         out.push(`  <results count="${topResults.length}">`);
         for (const r of topResults) {
@@ -7004,14 +7344,15 @@ function registerCrossRepoSearchTool(registry, _ctx, registryFilePath) {
         out.push("</cross_repo_search>");
         return out.join("\n");
       };
-      const full = render(true);
+      const full = render2(true);
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_cross_repo_search",
         defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS9,
-        skeletonProducer: async () => render(false)
+        skeletonProducer: async () => render2(false)
       });
       return wrapResponse(result);
     }
@@ -7116,6 +7457,7 @@ function registerApplyRefactorTool(registry, ctx) {
       const full = xml.join("\n");
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_apply_refactor",
@@ -7333,6 +7675,7 @@ function registerFullTextSearchTool(registry, ctx) {
       const maybeBudget = async (full, skeletonProducer) => {
         if (!hasBudgetArgs(args)) return full;
         const result = await enforceBudget({
+          ctx,
           full,
           args: readBudgetArgs(args),
           toolName: "ctx_full_text_search",
@@ -7396,7 +7739,7 @@ function registerFullTextSearchTool(registry, ctx) {
         } catch {
         }
       }
-      const render = (includeSnippets) => {
+      const render2 = (includeSnippets) => {
         const xml = [
           `<full_text_search query="${escapeXML22(query)}" mode="${mode}" case_sensitive="${case_sensitive}" count="${merged.length}">`
         ];
@@ -7415,8 +7758,8 @@ function registerFullTextSearchTool(registry, ctx) {
         return xml.join("\n");
       };
       return maybeBudget(
-        render(true),
-        async () => render(false)
+        render2(true),
+        async () => render2(false)
       );
     }
   );
@@ -7897,6 +8240,7 @@ function registerFindLargeFunctionsTool(registry, ctx) {
       }
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_find_large_functions",
@@ -8448,6 +8792,279 @@ function registerGetAffectedFlowsTool(registry, ctx) {
   );
 }
 
+// packages/core/src/tools/minimal-context.ts
+import { execSync } from "child_process";
+import { z as z36 } from "zod";
+var Schema30 = z36.object({
+  task: z36.string().max(200).optional().describe(
+    "Free-text description of what you're about to do (e.g. 'review PR 142', 'rename emitTelemetry'). The tool routes by regex to the most-fitting suggested-first-tool. Capped at 200 chars; control characters stripped."
+  ),
+  project_root: ProjectRootField,
+  max_response_tokens: z36.number().int().positive().optional(),
+  on_budget_exceeded: z36.enum(["skeleton", "truncate", "error"]).optional(),
+  response_format: z36.enum(["full", "skeleton", "auto"]).optional()
+});
+var DEFAULT_MAX_RESPONSE_TOKENS13 = 250;
+function routeFirstTool(task, hasDirtyChanges) {
+  const t = (task ?? "").toLowerCase();
+  if (/\b(rename|refactor|move\s+\w+|extract)\b/.test(t)) {
+    return {
+      tool: "ctx_get_call_graph",
+      why: "Renames + refactors need every caller surfaced before the edit. Start here.",
+      estimated_tokens: 800
+    };
+  }
+  if (/\b(blast|impact|breaks?|affects?)\b/.test(t)) {
+    return {
+      tool: "ctx_blast_radius",
+      why: "Blast-radius analysis gives transitive dependents; start here for impact questions.",
+      estimated_tokens: 1500
+    };
+  }
+  if (/\b(architect|overview|explore|onboard|tour)\b/.test(t)) {
+    return {
+      tool: "ctx_architecture_overview",
+      why: "Top-down map of communities + hub nodes; the natural starting point for exploration.",
+      estimated_tokens: 2e3
+    };
+  }
+  if (/\b(test|coverage|tested)\b/.test(t)) {
+    return {
+      tool: "ctx_knowledge_gaps",
+      why: "Knowledge-gap report highlights files lacking test coverage.",
+      estimated_tokens: 1200
+    };
+  }
+  if (/\b(review|audit|check|diff)\b/.test(t)) {
+    return {
+      tool: "ctx_detect_changes",
+      why: "Risk-scored change analysis is the canonical start for reviews.",
+      estimated_tokens: 1500
+    };
+  }
+  if (hasDirtyChanges) {
+    return {
+      tool: "ctx_detect_changes",
+      why: "Working tree has uncommitted changes \u2014 review-mode is the most-likely intent.",
+      estimated_tokens: 1500
+    };
+  }
+  return {
+    tool: "ctx_architecture_overview",
+    why: "Clean working tree + no task hint \u2014 orientation is the safe default.",
+    estimated_tokens: 2e3
+  };
+}
+function classifyStaleness(lastBuildIso) {
+  if (!lastBuildIso) return "unbuilt";
+  const ms = Date.now() - new Date(lastBuildIso).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return "unbuilt";
+  if (ms < 5 * 60 * 1e3) return "fresh";
+  if (ms < 60 * 60 * 1e3) return "stale_minutes";
+  return "stale_hours";
+}
+function readRecentChanges(projectRoot) {
+  try {
+    const stdout = execSync("git status --porcelain", {
+      cwd: projectRoot,
+      timeout: 2e3,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf-8"
+    });
+    const lines = stdout.split("\n").filter((l) => l.trim() !== "");
+    return lines.slice(0, 20).map((line) => {
+      const x = line[0];
+      const y = line[1];
+      const path37 = line.slice(3).trim();
+      let status = "?";
+      const xy = x === " " ? y : x;
+      if (xy === "M" || xy === "A" || xy === "D" || xy === "R") status = xy;
+      return { file: path37, status };
+    });
+  } catch {
+    return [];
+  }
+}
+function computeTopHubs(graph) {
+  const files = graph.allFiles();
+  const scored = files.map((file) => {
+    const inDeg = graph.getImporters(file).length;
+    const outDeg = graph.getImports(file).length;
+    return { file, inDeg, outDeg, total: inDeg + outDeg };
+  }).filter((s) => s.total >= 2).sort((a, b) => b.total - a.total).slice(0, 5);
+  return scored.map((s) => ({
+    name: s.file,
+    reason: s.inDeg > s.outDeg ? "fan_in" : s.outDeg > s.inDeg ? "fan_out" : "bridge"
+  }));
+}
+var CACHE_TTL_MS = 1e4;
+var responseCache = /* @__PURE__ */ new Map();
+function cacheKey(projectRoot, task) {
+  return `${projectRoot}|${task ?? ""}`;
+}
+function cacheGet(key) {
+  const e = responseCache.get(key);
+  if (!e) return null;
+  if (e.expiresAt < Date.now()) {
+    responseCache.delete(key);
+    return null;
+  }
+  return e.body;
+}
+function cachePut(key, body) {
+  responseCache.set(key, { expiresAt: Date.now() + CACHE_TTL_MS, body });
+}
+function sanitizeTask(raw) {
+  if (raw == null) return void 0;
+  const stripped = raw.replace(/[\x00-\x1f\x7f]/g, "").slice(0, 200);
+  return stripped === "" ? void 0 : stripped;
+}
+function escapeXML26(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function render(input) {
+  const lines = ["<minimal_context>"];
+  lines.push(
+    `  <graph ready="${input.graphReady}" nodes="${input.nodes}" edges="${input.edges}" last_build="${escapeXML26(input.lastBuildIso ?? "never")}" staleness="${input.staleness}" />`
+  );
+  if (input.languages.length > 0) {
+    lines.push(`  <languages>${input.languages.map(escapeXML26).join(", ")}</languages>`);
+  }
+  if (input.recentChanges.length > 0) {
+    lines.push(`  <recent_changes count="${input.recentChanges.length}">`);
+    for (const c of input.recentChanges) {
+      lines.push(`    <change status="${c.status}" file="${escapeXML26(c.file)}" />`);
+    }
+    lines.push("  </recent_changes>");
+  } else {
+    lines.push('  <recent_changes count="0" />');
+  }
+  if (input.topHubs.length > 0) {
+    lines.push(`  <top_hubs count="${input.topHubs.length}">`);
+    for (const h of input.topHubs) {
+      lines.push(`    <hub reason="${h.reason}" name="${escapeXML26(h.name)}" />`);
+    }
+    lines.push("  </top_hubs>");
+  }
+  lines.push("  <suggested_first_tool>");
+  lines.push(`    <tool>${escapeXML26(input.suggested.tool)}</tool>`);
+  lines.push(`    <why>${escapeXML26(input.suggested.why)}</why>`);
+  lines.push(`    <estimated_tokens>${input.suggested.estimated_tokens}</estimated_tokens>`);
+  if (input.suggested.args && Object.keys(input.suggested.args).length > 0) {
+    lines.push(`    <args>${escapeXML26(JSON.stringify(input.suggested.args))}</args>`);
+  }
+  lines.push("  </suggested_first_tool>");
+  lines.push("</minimal_context>");
+  return lines.join("\n");
+}
+function renderSkeleton(input) {
+  const lines = ['<minimal_context format="skeleton">'];
+  lines.push(
+    `  <graph ready="${input.graphReady}" nodes="${input.nodes}" edges="${input.edges}" staleness="${input.staleness}" />`
+  );
+  lines.push(`  <recent_changes count="${input.recentChanges.length}" />`);
+  lines.push(`  <top_hubs count="${input.topHubs.length}" />`);
+  lines.push("  <suggested_first_tool>");
+  lines.push(`    <tool>${escapeXML26(input.suggested.tool)}</tool>`);
+  lines.push(`    <why>${escapeXML26(input.suggested.why)}</why>`);
+  lines.push(`    <estimated_tokens>${input.suggested.estimated_tokens}</estimated_tokens>`);
+  lines.push("  </suggested_first_tool>");
+  lines.push("</minimal_context>");
+  return lines.join("\n");
+}
+function registerMinimalContextTool(registry, ctx) {
+  registry.register(
+    "ctx_get_minimal_context",
+    {
+      name: "ctx_get_minimal_context",
+      description: 'Orientation anchor \u2014 call this FIRST in any workflow. Returns ~150 tokens covering graph readiness, recent working-tree changes, top hub nodes, and a task-aware suggested-first-tool. Cached for 10s. Pass `task` as a free-text intent description ("review PR 142", "rename X", "check coverage") and the tool routes to the most-fitting follow-up. The agent should call the suggested tool next rather than guessing.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          task: {
+            type: "string",
+            description: "Free-text intent (max 200 chars). Routes the suggested-first-tool by regex. Keywords: review/audit, rename/refactor, blast/impact, architect/explore, test/coverage."
+          },
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: {
+            type: "number",
+            description: "Optional response token budget. Default 250."
+          },
+          on_budget_exceeded: {
+            type: "string",
+            enum: ["skeleton", "truncate", "error"]
+          },
+          response_format: {
+            type: "string",
+            enum: ["full", "skeleton", "auto"]
+          }
+        }
+      }
+    },
+    async (args) => {
+      const parsed = Schema30.parse(args);
+      const task = sanitizeTask(parsed.task);
+      const projectRoot = parsed.project_root ?? ctx.projectRoot;
+      const key = cacheKey(projectRoot, task);
+      const cached = cacheGet(key);
+      if (cached) {
+        return cached;
+      }
+      const graphReady = ctx.isGraphInitialized();
+      let nodes = 0;
+      let edges = 0;
+      let lastBuildIso = null;
+      const languages = [];
+      let topHubs = [];
+      if (graphReady) {
+        try {
+          const graph = await ctx.getGraph(projectRoot);
+          nodes = graph.allFiles().length;
+          edges = graph.allFiles().reduce((acc, f) => acc + graph.getImports(f).length, 0);
+          const extensions = /* @__PURE__ */ new Set();
+          for (const f of graph.allFiles()) {
+            const ext = f.split(".").pop();
+            if (ext && ext.length <= 4) extensions.add(ext);
+          }
+          languages.push(...Array.from(extensions).sort());
+          topHubs = computeTopHubs(graph);
+        } catch {
+        }
+      }
+      const recentChanges = readRecentChanges(projectRoot);
+      const suggested = routeFirstTool(task, recentChanges.length > 0);
+      const staleness = classifyStaleness(lastBuildIso);
+      const renderInput = {
+        graphReady,
+        nodes,
+        edges,
+        lastBuildIso,
+        staleness,
+        languages,
+        recentChanges,
+        topHubs,
+        suggested
+      };
+      const full = render(renderInput);
+      if (!hasBudgetArgs(parsed)) {
+        cachePut(key, full);
+        return full;
+      }
+      const result = await enforceBudget({
+        ctx,
+        full,
+        args: readBudgetArgs(parsed),
+        toolName: "ctx_get_minimal_context",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS13,
+        skeletonProducer: async () => renderSkeleton(renderInput)
+      });
+      const body = wrapResponse(result);
+      cachePut(key, body);
+      return body;
+    }
+  );
+}
+
 // packages/core/src/tools/index.ts
 function createToolRegistry(ctx) {
   const registry = new ToolRegistry();
@@ -8484,6 +9101,7 @@ function createToolRegistry(ctx) {
   registerGitCouplingTool(registry, ctx);
   registerRiskOverlayTool(registry, ctx);
   registerGetAffectedFlowsTool(registry, ctx);
+  registerMinimalContextTool(registry, ctx);
   return registry;
 }
 
@@ -9116,20 +9734,20 @@ import { readFileSync, writeFileSync, unlinkSync, mkdirSync, chmodSync, existsSy
 import path29 from "path";
 
 // packages/core/src/license/types.ts
-import { z as z36 } from "zod";
+import { z as z37 } from "zod";
 var FINGERPRINT_RE = /^sha256:[0-9a-f]{64}$/;
-var LicenseFileSchema = z36.object({
-  schemaVersion: z36.literal(1),
-  key: z36.string().min(1),
-  tier: z36.enum(["pro", "team", "enterprise", "trial"]),
-  status: z36.enum(["active", "trialing", "expired"]),
-  fingerprint: z36.string().regex(FINGERPRINT_RE),
-  seats: z36.number().int().positive(),
-  issuedAt: z36.string().datetime(),
-  expiresAt: z36.string().datetime(),
-  lastValidatedAt: z36.string().datetime(),
-  licenseId: z36.string().min(1),
-  instanceId: z36.string().min(1)
+var LicenseFileSchema = z37.object({
+  schemaVersion: z37.literal(1),
+  key: z37.string().min(1),
+  tier: z37.enum(["pro", "team", "enterprise", "trial"]),
+  status: z37.enum(["active", "trialing", "expired"]),
+  fingerprint: z37.string().regex(FINGERPRINT_RE),
+  seats: z37.number().int().positive(),
+  issuedAt: z37.string().datetime(),
+  expiresAt: z37.string().datetime(),
+  lastValidatedAt: z37.string().datetime(),
+  licenseId: z37.string().min(1),
+  instanceId: z37.string().min(1)
 });
 
 // packages/core/src/license/LicenseStore.ts
@@ -9342,7 +9960,7 @@ var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
 function getTelemetryLevel() {
   return TELEMETRY_LEVEL;
 }
-var CTXLOOM_VERSION = "1.3.0".length > 0 ? "1.3.0" : "dev";
+var CTXLOOM_VERSION = "1.4.0".length > 0 ? "1.4.0" : "dev";
 var POSTHOG_HOST = "https://eu.i.posthog.com";
 var POSTHOG_KEY = process.env["POSTHOG_API_KEY"] ?? (true ? "phc_CiDkmFLcZ2K6uCpcoSUQLmFrnnUvsyXGhSxopX5TVKE6" : "");
 var SENTRY_DSN = process.env["SENTRY_DSN"] ?? (true ? "https://81c94a0f04a8e242dee493ac1e17f733@o4508531702497280.ingest.de.sentry.io/4511256875368528" : "");
@@ -9966,6 +10584,732 @@ var EmittedOnceTracker = class {
   }
 };
 
+// packages/core/src/install/installer.ts
+import fs28 from "fs";
+import path36 from "path";
+
+// packages/core/src/install/templates.ts
+var RULES_BLOCK_NAME = "CTXLOOM-RULES";
+var RULES_BLOCK_CONTENT = `## MCP Tools: ctxloom
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+ctxloom MCP tools BEFORE Grep/Glob/Read to explore the codebase.**
+The graph is faster, cheaper (fewer tokens), and gives you
+structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### Start every workflow with \`ctx_get_minimal_context\`
+
+The first MCP call into ctxloom should always be
+\`ctx_get_minimal_context(task="<what you're about to do>")\`. It
+returns ~150 tokens of orientation plus a task-aware
+\`suggested_first_tool\` you should call next instead of guessing.
+
+### When to use graph tools FIRST
+
+- **Code review**: \`ctx_detect_changes\` + \`ctx_get_review_context\`
+  instead of reading whole files
+- **Understanding impact**: \`ctx_blast_radius\` + \`ctx_get_affected_flows\`
+  instead of manually tracing imports
+- **Refactor planning**: \`ctx_get_call_graph(direction: 'callers')\`
+  + \`ctx_refactor_preview\` before any rename
+- **Architecture questions**: \`ctx_architecture_overview\`,
+  \`ctx_community_list\`, \`ctx_hub_nodes\`
+- **Finding code**: \`ctx_search\` or \`ctx_full_text_search\` instead
+  of \`Grep\`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover
+what you need.
+
+### Follow the \`next_tool_suggestions\` in every response
+
+Every budget-wrapped ctxloom response includes
+\`meta.next_tool_suggestions\` \u2014 author-curated follow-ups with
+\`why\` reasoning and \`estimated_tokens\` per entry. Pick from
+those instead of guessing.
+
+### Token-budget protocol
+
+- Target: \u22648 tool calls per task, \u22642000 total tokens of graph context
+- Pass \`max_response_tokens\` on calls that might return large
+  responses; the budget surface returns skeletons instead of dumping
+- Use \`response_format: 'skeleton'\` when you know you only need
+  signatures, not bodies
+
+### Key tools at a glance
+
+| Tool | Use when |
+|------|----------|
+| \`ctx_get_minimal_context\` | START HERE \u2014 orientation anchor |
+| \`ctx_detect_changes\` | Reviewing code changes; risk-scored |
+| \`ctx_get_review_context\` | Token-efficient review snippets |
+| \`ctx_blast_radius\` | Blast radius of a change |
+| \`ctx_get_affected_flows\` | Execution paths impacted |
+| \`ctx_get_call_graph\` | Callers / callees of a symbol |
+| \`ctx_search\` / \`ctx_full_text_search\` | Find code |
+| \`ctx_architecture_overview\` | High-level codebase map |
+| \`ctx_refactor_preview\` / \`ctx_apply_refactor\` | Plan a rename |
+
+### Hooks keep the graph fresh
+
+\`ctxloom init\` installed a PostToolUse hook on \`Write|Edit\` that
+runs \`ctxloom update --incremental --quiet\` \u2014 so the graph is
+always up to date when you query it. No "did the index update yet?"
+guessing.`;
+var SESSION_START_HEADER = `#!/usr/bin/env bash
+# ctxloom \u2014 agent-harness session-start hook
+# Generated by \`ctxloom init\`. Re-run \`ctxloom init\` to update.
+# Manual edits will be overwritten on the next install.
+
+set -e
+`;
+var SESSION_START_BODY = `DB=".ctxloom/graph.db"
+
+if [ -f "$DB" ]; then
+  # \`ctxloom status --json\` is cached + sub-100ms \u2014 keeps the hook
+  # under its 2s timeout even on cold disk.
+  STATS=$(ctxloom status --json 2>/dev/null || echo '{"nodes":0,"edges":0}')
+  NODES=$(echo "$STATS" | grep -oE '"nodes":\\s*[0-9]+' | grep -oE '[0-9]+' || echo "?")
+  EDGES=$(echo "$STATS" | grep -oE '"edges":\\s*[0-9]+' | grep -oE '[0-9]+' || echo "?")
+
+  cat <<EOF
+[ctxloom] Knowledge graph ready (\${NODES} nodes, \${EDGES} edges).
+
+Start every workflow with \\\`ctx_get_minimal_context(task="...")\\\`.
+It returns ~150 tokens of orientation + a task-aware
+suggested_first_tool. Follow the meta.next_tool_suggestions on
+every response.
+
+Prefer ctxloom MCP tools over Grep/Glob/Read:
+  - ctx_detect_changes for code review
+  - ctx_blast_radius / ctx_get_call_graph before refactoring
+  - ctx_architecture_overview for orientation
+EOF
+else
+  cat <<EOF
+[ctxloom] No knowledge graph found here.
+Run: ctxloom build
+
+Then restart this session to enable graph-powered queries.
+EOF
+fi
+`;
+var SESSION_START_FULL = SESSION_START_HEADER + "\n" + SESSION_START_BODY;
+var CTXLOOM_HOOK_ENTRIES = {
+  SessionStart: {
+    matcher: "",
+    hooks: [{ type: "command", command: ".claude/hooks/session-start.sh", timeout: 2 }]
+  },
+  PostToolUse: {
+    matcher: "Write|Edit",
+    hooks: [
+      {
+        type: "command",
+        command: "ctxloom update --incremental --quiet",
+        timeout: 30
+      }
+    ]
+  }
+};
+
+// packages/core/src/install/hmacBlock.ts
+import crypto6 from "crypto";
+var DEFAULT_HMAC_KEY = "ctxloom-agent-harness-v1-published";
+function resolveHmacKey() {
+  return process.env.CTXLOOM_INSTALL_KEY ?? DEFAULT_HMAC_KEY;
+}
+function computeBlockHmac(content, key = resolveHmacKey()) {
+  return crypto6.createHmac("sha256", key).update(content, "utf-8").digest("hex");
+}
+function wrapBlock(name, content) {
+  const hmac = computeBlockHmac(content);
+  return [
+    `<!-- BEGIN ${name} v:1 hmac:sha256:${hmac} -->`,
+    content,
+    `<!-- END ${name} -->`
+  ].join("\n");
+}
+var START_RE_TEMPLATE = (name) => new RegExp(`<!-- BEGIN ${escapeRegex(name)} v:(\\d+) hmac:sha256:([0-9a-f]{64}) -->`);
+var END_RE_TEMPLATE = (name) => new RegExp(`<!-- END ${escapeRegex(name)} -->`);
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function extractBlock(fileContent, name) {
+  const startRe = START_RE_TEMPLATE(name);
+  const endRe = END_RE_TEMPLATE(name);
+  const startMatch = startRe.exec(fileContent);
+  if (!startMatch) return null;
+  const startIdx = startMatch.index;
+  const afterStart = startIdx + startMatch[0].length;
+  endRe.lastIndex = afterStart;
+  const endMatch = endRe.exec(fileContent.slice(afterStart));
+  if (!endMatch) return null;
+  const endIdx = afterStart + endMatch.index + endMatch[0].length;
+  let inner = fileContent.slice(afterStart, afterStart + endMatch.index);
+  if (inner.startsWith("\n")) inner = inner.slice(1);
+  if (inner.endsWith("\n")) inner = inner.slice(0, -1);
+  return {
+    content: inner,
+    declaredHmac: startMatch[2],
+    version: Number(startMatch[1]),
+    start: startIdx,
+    end: endIdx
+  };
+}
+function verifyBlock(block) {
+  return computeBlockHmac(block.content) === block.declaredHmac;
+}
+function upsertBlock(fileContent, name, newContent) {
+  const wrapped = wrapBlock(name, newContent);
+  const existing = extractBlock(fileContent, name);
+  if (existing) {
+    return fileContent.slice(0, existing.start) + wrapped + fileContent.slice(existing.end);
+  }
+  const sep = fileContent.length === 0 || fileContent.endsWith("\n\n") ? "" : fileContent.endsWith("\n") ? "\n" : "\n\n";
+  return fileContent + sep + wrapped + "\n";
+}
+
+// packages/core/src/install/skillTemplates.ts
+var EXPLORE_CONTENT = `---
+name: ctxloom-explore
+description: Orient yourself to an unfamiliar codebase using ctxloom's structural graph. Architecture overview + communities + top hubs in \u22645 tool calls.
+---
+
+# Explore Codebase
+
+Use this when you need to understand a codebase you haven't worked in
+before, or when re-orienting after time away.
+
+## Steps
+
+1. **Orientation anchor**: call \`ctx_get_minimal_context(task="explore this codebase")\`.
+   The response includes graph stats, top hubs, and a
+   \`suggested_first_tool\` \u2014 follow it (likely
+   \`ctx_architecture_overview\`).
+
+2. **Architecture overview**: call \`ctx_architecture_overview(max_response_tokens=2000)\`.
+   Returns the community structure + hub nodes + cross-community bridges.
+
+3. **Drill into the biggest communities**: from the overview's
+   \`meta.next_tool_suggestions\`, call \`ctx_community_list\` for the
+   top 1\u20132 communities. Skip communities labeled "tests" or
+   "config" \u2014 they're usually peripheral.
+
+4. **Investigate the architectural bridges**: call \`ctx_bridge_nodes\`.
+   Bridge nodes are high-leverage \u2014 changing one affects multiple
+   communities. Read these first to understand the codebase's
+   coupling story.
+
+5. **Tour the hubs**: call \`ctx_hub_nodes(limit=5, detail_level="minimal")\`.
+   Top 5 most-depended-upon files. These are usually the heart of
+   the codebase.
+
+## Budget
+
+- \u22645 ctxloom tool calls
+- \u22642000 tokens total response budget
+- Don't \`ctx_get_file\` anything during exploration \u2014 signatures are
+  enough. Drop to file reads only if a specific symbol needs
+  inspection (and only via \`ctx_get_definition\`, not raw read).
+
+## Output
+
+Summarize for the user:
+- Main communities (3\u20135 named clusters)
+- Top hubs by fan-in (the load-bearing files)
+- Top bridges (the architectural seams)
+- Recommended deep-dive starting points
+`;
+var BLAST_CONTENT = `---
+name: ctxloom-blast
+description: Compute blast radius + affected execution flows for a symbol or file before changing it. Pinpoints what will break.
+argument-hint: "<symbol-name | file-path>"
+---
+
+# Blast Radius
+
+Use this before any change to a public function, type, or file
+where you're not sure who depends on it.
+
+## Inputs
+
+- \`$ARGUMENTS\` \u2014 the symbol name (e.g. \`emitTelemetry\`) or file
+  path (e.g. \`src/server.ts\`) you're about to modify.
+
+## Steps
+
+1. **Orientation**: call \`ctx_get_minimal_context(task="blast radius for $ARGUMENTS")\`.
+
+2. **Blast radius**: call \`ctx_blast_radius(target="$ARGUMENTS", max_response_tokens=1500)\`.
+   Returns transitive dependents \u2014 every file (and indirectly,
+   every flow) that would be affected by a breaking change.
+
+3. **Caller graph**: call \`ctx_get_call_graph(symbol="$ARGUMENTS", direction="callers", depth=2)\`.
+   Direct + grandparent callers. Pair with the blast radius
+   to distinguish "many transitive deps" from "load-bearing
+   direct API."
+
+4. **Affected execution flows**: call \`ctx_get_affected_flows(target="$ARGUMENTS")\`.
+   Maps the change to ordered execution sequences \u2014 useful for
+   debugging "what user-facing path breaks?"
+
+5. **Test coverage check**: call \`ctx_knowledge_gaps(scope="$ARGUMENTS")\`.
+   Highlights affected files lacking test coverage \u2014 those are the
+   real risk surface.
+
+## Budget
+
+- \u22645 ctxloom tool calls
+- \u22642000 tokens total
+
+## Output
+
+Report to the user:
+- Total transitive dependents (number + top 5 by depth)
+- Direct callers (the API consumers)
+- Affected execution flows (named user-facing paths)
+- Coverage gaps on the affected files (the risk surface)
+- Recommendation: "safe to change" / "review carefully" / "needs migration plan"
+`;
+var REFACTOR_CONTENT = `---
+name: ctxloom-refactor-safely
+description: Plan and execute a rename or signature change with full caller-aware safety. Preview before applying.
+argument-hint: "<old-name> <new-name>"
+---
+
+# Refactor Safely
+
+Use this for renames, signature changes, or function moves. The
+skill enforces preview-before-apply.
+
+## Inputs
+
+- \`$1\` \u2014 current symbol name (e.g. \`emitTelemetry\`)
+- \`$2\` \u2014 target name (e.g. \`emitTelemetryEvent\`)
+
+## Steps
+
+1. **Orientation**: call \`ctx_get_minimal_context(task="refactor $1 to $2")\`.
+
+2. **Surface every caller**: call \`ctx_get_call_graph(symbol="$1", direction="callers", depth=1)\`.
+   The exhaustive caller list. Without this, a rename can break
+   files you didn't notice depended on the symbol.
+
+3. **Blast radius**: call \`ctx_blast_radius(target="$1")\`.
+   Transitive impact \u2014 useful to gauge whether this should be a
+   single PR or split with a deprecation period.
+
+4. **Generate the refactor preview**: call \`ctx_refactor_preview(symbol="$1", new_name="$2")\`.
+   Returns a diff preview WITHOUT writing anything. Inspect it.
+
+5. **Confirm with the user**: show the preview summary
+   (N files changed, M call sites updated). **DO NOT proceed to
+   step 6 without explicit user confirmation.**
+
+6. **Apply the refactor**: call \`ctx_apply_refactor(symbol="$1", new_name="$2")\`.
+   This writes the changes to disk. Irreversible without a git
+   reset.
+
+7. **Verify**: call \`ctx_detect_changes\` and confirm the diff
+   matches what the preview said. Surface any unexpected changes.
+
+## Safety rails
+
+- ALWAYS run step 4 (preview) before step 6 (apply)
+- ALWAYS ask the user for confirmation between preview and apply
+- If preview shows >50 files affected, recommend splitting into
+  a deprecation-style migration instead of a single rename
+- If the symbol is exported from a public API package, refuse to
+  proceed and recommend the user open a tracked migration plan
+
+## Budget
+
+- \u22647 ctxloom tool calls
+- \u22643000 tokens total (preview output can be larger than other skills)
+`;
+var COVERAGE_GAP_CONTENT = `---
+name: ctxloom-coverage-gap
+description: Identify code that lacks test coverage, prioritized by caller frequency and risk.
+---
+
+# Coverage Gap Analysis
+
+Use this to find untested code that genuinely matters \u2014 the
+intersection of "no tests" + "many callers" + "high risk score."
+
+## Steps
+
+1. **Orientation**: call \`ctx_get_minimal_context(task="check test coverage")\`.
+
+2. **Knowledge gaps**: call \`ctx_knowledge_gaps(max_response_tokens=1200)\`.
+   Lists every file lacking a \`tests_for\` graph edge. Raw list
+   without prioritization.
+
+3. **Score by impact**: for each gap, call
+   \`ctx_get_call_graph(symbol=<gap_symbol>, direction="callers")\`
+   to count callers. High caller-count + no tests = high priority.
+
+4. **Cross-reference with churn**: call
+   \`ctx_git_coupling(file=<gap_file>)\` for the top 5 gaps.
+   Files churning often without tests are the urgent ones.
+
+5. **Risk overlay**: call \`ctx_risk_overlay(scope=<top_gap_files>)\`.
+   Combines churn + coupling into a single risk score.
+
+## Output
+
+Tabular report:
+
+\`\`\`
+| File / Symbol | Callers | Churn | Risk | Recommendation |
+|---|---|---|---|---|
+| ... | ... | ... | ... | ... |
+\`\`\`
+
+Recommendations should distinguish:
+- "Add tests now" (high caller count + high churn)
+- "Add tests during next change" (high caller count, low churn)
+- "Acceptable gap" (low caller count, low churn)
+
+## Budget
+
+- \u22646 ctxloom tool calls
+- \u22642500 tokens total
+`;
+var REVIEW_PR_CONTENT = `---
+name: ctxloom-review-pr
+description: Multi-tier code review of a PR using ctxloom's structural graph. Risk-scored, blast-radius-aware, coverage-conscious.
+argument-hint: "<PR number | branch name>"
+---
+
+# Review PR
+
+Comprehensive PR review using ctxloom's graph. Mirrors the
+multi-agent review the ctxloom-bot posts automatically \u2014 useful
+when reviewing manually or when the bot isn't wired up.
+
+## Inputs
+
+- \`$ARGUMENTS\` \u2014 PR number (e.g. \`142\`) or branch name (e.g. \`feat/foo\`).
+  Defaults to the current branch if unset.
+
+## Steps
+
+1. **Orientation**: call \`ctx_get_minimal_context(task="review PR $ARGUMENTS")\`.
+
+2. **Detect changes**: call \`ctx_detect_changes(base="main")\`.
+   Risk-scored per-file analysis. Take the top 5 highest-risk files.
+
+3. **Pull source for the risky files**: call \`ctx_git_diff_review(base="main", max_response_tokens=4000)\`.
+   Token-efficient diff packet covering the changed files.
+
+4. **Blast radius per high-risk file**: for the top 3 risky files,
+   call \`ctx_blast_radius(target=<file>)\`. Surfaces files that the
+   change indirectly affects but don't appear in the diff.
+
+5. **Affected flows**: call \`ctx_get_affected_flows(base="main")\`.
+   Which execution paths the PR touches. Use to identify what
+   integration tests should pass.
+
+6. **Coverage check**: call \`ctx_knowledge_gaps(scope=<changed_files>)\`.
+   Surface changed files lacking tests.
+
+7. **Generate the review**: structured output with:
+   - Risk summary (low/medium/high overall)
+   - File-by-file findings (severity-ranked)
+   - Coverage gaps that need addressing
+   - Blast-radius observations the diff doesn't show
+
+## Tier discipline
+
+This skill is the agent-driven equivalent of the bot's
+multi-specialist review. Use the same tier ladder:
+
+- **T0 (structural)**: use the tools listed above \u2014 they're
+  pre-fetched and cheap
+- **T1 (skeleton)**: \`ctx_get_definition\` for individual symbols
+- **T2 (full body)**: \`ctx_get_file\` only for files where the
+  skeleton view is insufficient
+- **T3 (raw read)**: avoid; if the graph can't answer the question,
+  prefer \`ctx_git_diff_review\` (token-efficient diff packet) over
+  raw \`Read\`
+
+## Budget
+
+- \u22648 ctxloom tool calls
+- \u22645000 tokens total (review needs more headroom than other skills)
+
+## Output format
+
+\`\`\`
+## PR Review: <title>
+
+### Summary
+<1\u20133 sentence overview>
+
+### Risk Assessment
+- Overall: Low / Medium / High
+- Blast radius: X files, Y flows impacted
+- Coverage: N changed symbols covered / M total
+
+### Findings
+
+#### <file_path>
+- **Severity**: ...
+- **Issue**: ...
+- **Suggested fix**: ...
+
+### Coverage Gaps
+
+<table>
+
+### Suggested follow-ups
+
+<list>
+\`\`\`
+`;
+var BUDGET_STATS_CONTENT = `---
+name: ctxloom-budget-stats
+description: Inspect ctxloom's per-tool budget telemetry \u2014 fallback distribution + original-token p50/p75/p95 \u2014 to tune defaults from real usage.
+---
+
+# Budget Stats
+
+Wrapper around \`ctxloom budget-stats\` for inline use inside a
+Claude Code session. Useful when:
+
+- Tuning per-tool \`DEFAULT_MAX_RESPONSE_TOKENS\` from real usage
+  (the Phase B follow-up)
+- Diagnosing why a tool keeps falling back to skeleton mode
+- Understanding which tools dominate the user's token budget
+
+## Steps
+
+1. **Orientation**: call \`ctx_get_minimal_context(task="inspect budget telemetry")\`.
+   Cheap (~150 tokens). Confirms the graph is wired up \u2014 if it's
+   not, the user's MCP server probably can't emit budget events
+   either, and the stats will be empty.
+
+3. **Window selection**: ask the user how far back to look
+   (default: 14d). Accept \`1d\`, \`7d\`, \`14d\`, \`30d\`.
+
+4. **Optional tool filter**: ask if they want stats for a specific
+   tool (e.g. \`ctx_get_file\`) or all tools.
+
+5. **Run the CLI**: \`Bash\`-tool execute:
+   \`ctxloom budget-stats --window=<N>d [--tool=<name>]\`
+
+6. **Parse + summarize the output**:
+   - Top 3 tools by breach count \u2192 these are the candidates for
+     budget tuning
+   - For each top tool, the p75 column is the suggested next
+     \`DEFAULT_MAX_RESPONSE_TOKENS\` value (rationale: 75% of
+     real-world calls fit under p75; the rest fall back gracefully
+     to skeletons)
+
+7. **Suggest concrete edits**: for each top tool, point to the
+   source file (\`packages/core/src/tools/<tool>.ts\`) and the
+   current constant. Don't apply edits without user confirmation.
+
+## Budget
+
+- \u22642 ctxloom tool calls (this skill is mostly Bash + parsing)
+- \u22641500 tokens response total
+
+## Output
+
+\`\`\`
+## Budget stats \u2014 <window>
+
+### Top tools by breach count
+1. <tool>: N breaches, skeleton%, p75=<tokens>
+2. ...
+
+### Suggested DEFAULT_MAX_RESPONSE_TOKENS tuning
+- packages/core/src/tools/<tool>.ts: <current> \u2192 <suggested-p75>
+  (rationale: ...)
+\`\`\`
+`;
+var CTXLOOM_SKILLS = [
+  { name: "ctxloom-explore", content: EXPLORE_CONTENT },
+  { name: "ctxloom-blast", content: BLAST_CONTENT },
+  { name: "ctxloom-refactor-safely", content: REFACTOR_CONTENT },
+  { name: "ctxloom-coverage-gap", content: COVERAGE_GAP_CONTENT },
+  { name: "ctxloom-review-pr", content: REVIEW_PR_CONTENT },
+  { name: "ctxloom-budget-stats", content: BUDGET_STATS_CONTENT }
+];
+function skillFilePath(name) {
+  return `.claude/skills/${name}/SKILL.md`;
+}
+
+// packages/core/src/install/installer.ts
+function installHarness(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const projectRoot = path36.resolve(cwd);
+  const stat = fs28.statSync(projectRoot);
+  if (!stat.isDirectory()) {
+    throw new Error(`installHarness: ${projectRoot} is not a directory`);
+  }
+  const dryRun = opts.dryRun === true;
+  const force = opts.force === true;
+  const warnings = [];
+  const claudeMd = writeRulesBlock(projectRoot, "CLAUDE.md", { dryRun, force, warnings });
+  const agentsMd = writeRulesBlock(projectRoot, "AGENTS.md", { dryRun, force, warnings });
+  const geminiMd = writeRulesBlock(projectRoot, "GEMINI.md", { dryRun, force, warnings });
+  const hooksJson = writeHooksJson(projectRoot, { dryRun, warnings });
+  const sessionStartSh = writeSessionStartScript(projectRoot, { dryRun });
+  const skills = CTXLOOM_SKILLS.map((s) => writeSkill(projectRoot, s, { dryRun }));
+  return {
+    projectRoot,
+    claudeMd,
+    agentsMd,
+    geminiMd,
+    hooksJson,
+    sessionStartSh,
+    skills,
+    warnings
+  };
+}
+function safeJoin(root, name) {
+  const target = path36.resolve(root, name);
+  const rootResolved = path36.resolve(root);
+  if (!target.startsWith(rootResolved + path36.sep) && target !== rootResolved) {
+    throw new Error(`installHarness: refusing to write outside project root: ${target}`);
+  }
+  return target;
+}
+function writeRulesBlock(projectRoot, filename, opts) {
+  const filePath = safeJoin(projectRoot, filename);
+  const existed = fs28.existsSync(filePath);
+  const existing = existed ? fs28.readFileSync(filePath, "utf-8") : "";
+  if (existed) {
+    const block = extractBlock(existing, RULES_BLOCK_NAME);
+    if (block) {
+      const intact = verifyBlock(block);
+      if (intact && block.content === RULES_BLOCK_CONTENT) {
+        return { path: filePath, created: false, updated: false, alreadyCorrect: true, dryRun: opts.dryRun };
+      }
+      if (!intact && !opts.force) {
+        opts.warnings.push(
+          `Drift detected in ${filename}: the CTXLOOM-RULES block has been hand-edited. Re-run \`ctxloom init --force\` to overwrite, or commit your changes and re-run.`
+        );
+        return { path: filePath, created: false, updated: false, alreadyCorrect: false, dryRun: opts.dryRun };
+      }
+    }
+  }
+  const next = upsertBlock(existing, RULES_BLOCK_NAME, RULES_BLOCK_CONTENT);
+  if (!opts.dryRun) {
+    fs28.writeFileSync(filePath, next, "utf-8");
+  }
+  return {
+    path: filePath,
+    created: !existed,
+    updated: existed,
+    alreadyCorrect: false,
+    dryRun: opts.dryRun
+  };
+}
+function writeHooksJson(projectRoot, opts) {
+  const dir = safeJoin(projectRoot, ".claude");
+  const filePath = safeJoin(projectRoot, ".claude/hooks.json");
+  const existed = fs28.existsSync(filePath);
+  let current = {};
+  if (existed) {
+    try {
+      const text = fs28.readFileSync(filePath, "utf-8");
+      current = JSON.parse(text);
+    } catch (err) {
+      opts.warnings.push(
+        `Could not parse existing ${path36.relative(projectRoot, filePath)}; treating as empty. (${err instanceof Error ? err.message : String(err)})`
+      );
+      current = {};
+    }
+  }
+  const merged = { ...current };
+  for (const event of ["SessionStart", "PostToolUse"]) {
+    const incoming = CTXLOOM_HOOK_ENTRIES[event];
+    const existingArr = Array.isArray(merged[event]) ? merged[event] : [];
+    const filtered = existingArr.filter(
+      (entry) => !isCtxloomEntry(entry, incoming.matcher)
+    );
+    merged[event] = [...filtered, incoming];
+  }
+  const nextJson = JSON.stringify(merged, null, 2) + "\n";
+  let alreadyCorrect = false;
+  if (existed) {
+    const currentText = fs28.readFileSync(filePath, "utf-8");
+    if (currentText === nextJson) alreadyCorrect = true;
+  }
+  if (!opts.dryRun && !alreadyCorrect) {
+    fs28.mkdirSync(dir, { recursive: true });
+    fs28.writeFileSync(filePath, nextJson, "utf-8");
+  }
+  return {
+    path: filePath,
+    created: !existed,
+    updated: existed && !alreadyCorrect,
+    alreadyCorrect,
+    dryRun: opts.dryRun
+  };
+}
+function isCtxloomEntry(entry, expectedMatcher) {
+  if (entry.matcher !== expectedMatcher) return false;
+  if (!Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some((h) => {
+    if (!h || typeof h !== "object") return false;
+    const cmd = h.command;
+    if (typeof cmd !== "string") return false;
+    return cmd.includes("ctxloom") || cmd.includes(".claude/hooks/session-start.sh");
+  });
+}
+function writeSkill(projectRoot, skill, opts) {
+  const dir = safeJoin(projectRoot, `.claude/skills/${skill.name}`);
+  const filePath = safeJoin(projectRoot, skillFilePath(skill.name));
+  const existed = fs28.existsSync(filePath);
+  let alreadyCorrect = false;
+  if (existed) {
+    if (fs28.readFileSync(filePath, "utf-8") === skill.content) {
+      alreadyCorrect = true;
+    }
+  }
+  if (!opts.dryRun && !alreadyCorrect) {
+    fs28.mkdirSync(dir, { recursive: true });
+    fs28.writeFileSync(filePath, skill.content, "utf-8");
+  }
+  return {
+    path: filePath,
+    created: !existed,
+    updated: existed && !alreadyCorrect,
+    alreadyCorrect,
+    dryRun: opts.dryRun
+  };
+}
+function writeSessionStartScript(projectRoot, opts) {
+  const dir = safeJoin(projectRoot, ".claude/hooks");
+  const filePath = safeJoin(projectRoot, ".claude/hooks/session-start.sh");
+  const existed = fs28.existsSync(filePath);
+  let alreadyCorrect = false;
+  if (existed) {
+    const current = fs28.readFileSync(filePath, "utf-8");
+    if (current === SESSION_START_FULL) alreadyCorrect = true;
+  }
+  if (!opts.dryRun && !alreadyCorrect) {
+    fs28.mkdirSync(dir, { recursive: true });
+    fs28.writeFileSync(filePath, SESSION_START_FULL, "utf-8");
+    try {
+      fs28.chmodSync(filePath, 493);
+    } catch {
+    }
+  }
+  return {
+    path: filePath,
+    created: !existed,
+    updated: existed && !alreadyCorrect,
+    alreadyCorrect,
+    dryRun: opts.dryRun
+  };
+}
+
 export {
   GRAMMAR_MANIFEST,
   findGrammar,
@@ -10070,6 +11414,20 @@ export {
   noParseableSourcesWarning,
   wrapWithIndexingEnvelope,
   FirstTouchTracker,
-  EmittedOnceTracker
+  EmittedOnceTracker,
+  RULES_BLOCK_NAME,
+  RULES_BLOCK_CONTENT,
+  SESSION_START_FULL,
+  CTXLOOM_HOOK_ENTRIES,
+  DEFAULT_HMAC_KEY,
+  resolveHmacKey,
+  computeBlockHmac,
+  wrapBlock,
+  extractBlock,
+  verifyBlock,
+  upsertBlock,
+  CTXLOOM_SKILLS,
+  skillFilePath,
+  installHarness
 };
-//# sourceMappingURL=chunk-Q2KTZNNU.js.map
+//# sourceMappingURL=chunk-7GZVGIQL.js.map