@levnikolaevich/hex-line-mcp 1.3.6 → 1.5.0

package/README.md

@@ -32,26 +32,26 @@ Advanced / occasional:
 
 | Tool | Description | Key Feature |
 |------|-------------|-------------|
-| `read_file` | Read file with hash-annotated lines, checksums, and revision | Partial reads via `offset`/`limit` |
+| `read_file` | Read file with hash-annotated lines, checksums, and revision | Partial reads via `offset`/`limit` or `ranges`, compact output by default |
 | `edit_file` | Revision-aware anchor edits (`set_line`, `replace_lines`, `insert_after`, `replace_between`) | Batched same-file edits + conservative auto-rebase |
 | `write_file` | Create new file or overwrite, auto-creates parent dirs | Path validation, no hash overhead |
-| `grep_search` | Search with ripgrep, 3 output modes, per-group checksums | Edit-ready: grep -> edit directly with checksums |
+| `grep_search` | Search with ripgrep, 3 output modes, per-group checksums | Plain `files`/`count`, compact edit-ready `content` |
 | `outline` | AST-based structural overview via tree-sitter WASM | 95% token reduction (10 lines instead of 500) |
 | `verify` | Check if held checksums / revision are still current | Staleness check without full re-read |
 | `directory_tree` | Compact directory tree with root .gitignore support | Skips node_modules/.git, shows file sizes |
 | `get_file_info` | File metadata without reading content | Size, lines, mtime, type, binary detection |
 | `setup_hooks` | Configure Claude hooks + install output style | Gemini/Codex get guidance only; no hooks |
 | `changes` | Compare file against git ref, shows added/removed/modified symbols | AST-level semantic diff |
-| `bulk_replace` | Search-and-replace across multiple files by glob | Per-file diffs, dry_run, max_files safety |
+| `bulk_replace` | Search-and-replace across multiple files by glob | Compact summary (default) or capped diffs via `format`, dry_run, max_files |
 
 ### Hooks (PreToolUse + PostToolUse)
 
 | Event | Trigger | Action |
 |-------|---------|--------|
-| **PreToolUse** | Read/Edit/Write/Grep on text files | Blocks built-in, forces hex-line tools |
+| **PreToolUse** | Read/Edit/Write/Grep on text files | Size-aware redirect: cheap small operations may pass, expensive ones are redirected |
 | **PreToolUse** | Bash with dangerous commands | Blocks `rm -rf /`, `git push --force`, etc. Agent must confirm with user |
 | **PostToolUse** | Bash with 50+ lines output | RTK: deduplicates, truncates, shows filtered summary to Claude as feedback |
-| **SessionStart** | Session begins | Injects full tool preference list into agent context |
+| **SessionStart** | Session begins | Injects a short no-discovery workflow for hex-line tools |
 
 
 ### Bash Redirects
@@ -90,45 +90,33 @@ The `setup_hooks` tool automatically installs the output style to `~/.claude/out
 
 ## Benchmarking
 
-`hex-line-mcp` now distinguishes:
+Two benchmark layers:
 
-- `tests` — correctness and regression safety
-- `benchmarks` — comparative workflow efficiency against built-in tools
-- `diagnostics` — modeled tool-level measurements for engineering inspection
-
-Public benchmark mode reports only comparative multi-step workflows:
+- `/benchmark-compare` — balanced built-in vs hex-line comparison inside Claude Code, validated by scenario manifests and saved diffs
+- `npm run benchmark` — hex-line standalone workflow metrics (Node.js, all real library calls, no simulations)
 
 ```bash
 npm run benchmark -- --repo /path/to/repo
-```
-
-Optional diagnostics stay available separately:
-
-```bash
 npm run benchmark:diagnostic -- --repo /path/to/repo
-npm run benchmark:diagnostic:graph -- --repo /path/to/repo
 ```
 
-The diagnostics output includes synthetic tool-level comparisons such as read, grep, verify, and graph-enrichment helpers. Those numbers are useful for inspecting output shape and token behavior, but they are not the public workflow benchmark score.
+Current standalone workflow metrics on the `hex-line-mcp` repo (all real library calls):
 
-Current sample run on the `hex-line-mcp` repo with session-derived workflows:
+| # | Workflow | Hex-line output | Ops |
+|---|----------|---------:|----:|
+| W1 | Debug hook file-listing redirect | 882 chars | 2 |
+| W2 | Adjust `setup_hooks` guidance and verify | 1,719 chars | 3 |
+| W3 | Repo-wide benchmark wording refresh | 213 chars | 1 |
+| W4 | Inspect large smoke test before edit | 2,322 chars | 3 |
+| W5 | Follow-up edit after unrelated line shift | 1,267 chars | 3 |
 
-| ID | Workflow | Built-in | hex-line | Savings | Ops |
-|----|----------|---------:|---------:|--------:|----:|
-| W1 | Debug hook file-listing redirect | 23,143 chars | 882 chars | 96% | 3→2 |
-| W2 | Adjust `setup_hooks` guidance and verify | 24,877 chars | 1,637 chars | 93% | 3→3 |
-| W3 | Repo-wide benchmark wording refresh | 137,796 chars | 38,918 chars | 72% | 15→1 |
-| W4 | Inspect large smoke test before edit | 49,566 chars | 2,104 chars | 96% | 3→3 |
-
-Workflow summary: `89%` average token savings, `24→9` tool calls (`63%` fewer).
-
-These workflows are derived from recent real Claude sessions, but executed against local reproducible fixtures in the repository. They should be read as workflow-efficiency measurements, not as correctness or semantic-quality claims.
+Workflow total: `6,403` chars across `12` ops. Run `/benchmark-compare` for the balanced scenario suite with activation checks and diff-based correctness.
 
 ### Optional Graph Enrichment
 
-If a project already has `.codegraph/index.db`, `hex-line` can add lightweight graph hints to `read_file`, `outline`, `grep_search`, and `edit_file`.
+If a project already has `.hex-skills/codegraph/index.db`, `hex-line` can add lightweight graph hints to `read_file`, `outline`, `grep_search`, and `edit_file`.
 
-- Graph enrichment is optional. If `.codegraph/index.db` is missing, `hex-line` falls back to standard behavior silently.
+- Graph enrichment is optional. If `.hex-skills/codegraph/index.db` is missing, `hex-line` falls back to standard behavior silently.
 - `better-sqlite3` is optional. If it is unavailable, `hex-line` still works without graph hints.
 - `edit_file` reports **Call impact**, not full semantic blast radius. The warning uses call-graph callers only.
 
@@ -160,11 +148,11 @@ Use `replace_between` inside `edit_file` when you know stable start/end anchors
 
 ### Literal rename / refactor
 
-Use `bulk_replace` for text rename patterns across one or more files. Do not use it as a substitute for structured block rewrites.
+Use `bulk_replace` for text rename patterns across one or more files. Returns compact summary by default; pass `format: "full"` for capped diffs. Do not use it as a substitute for structured block rewrites.
 
 ### read_file
 
-Read a file with FNV-1a hash-annotated lines, range checksums, file checksum, and revision. Supports directory listing.
+Read a file with FNV-1a hash-annotated lines, range checksums, file checksum, and revision. Supports batch reads, multi-range reads, and directory listing.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -172,17 +160,22 @@ Read a file with FNV-1a hash-annotated lines, range checksums, file checksum, an
 | `paths` | string[] | no | Array of file paths to read (batch mode) |
 | `offset` | number | no | Start line, 1-indexed (default: 1) |
 | `limit` | number | no | Max lines to return (default: 2000, 0 = all) |
+| `ranges` | array | no | Explicit line ranges, e.g. `[{ "start": 10, "end": 30 }]` |
+| `include_graph` | boolean | no | Opt in to graph annotations when the graph index exists |
 | `plain` | boolean | no | Omit hashes, output `lineNum\|content` instead |
 
-Output format:
+Default output is compact:
 
 ```
+File: lib/search.mjs
+meta: lines 1-20 of 282
+revision: rev-12-a1b2c3d4
+file: 1-282:beefcafe
+
 ab.1    import { resolve } from "node:path";
 cd.2    import { readFileSync } from "node:fs";
 ...
 checksum: 1-50:f7e2a1b0
-revision: rev-12-a1b2c3d4
-file: 1-120:beefcafe
 ```
 
 ### edit_file
@@ -215,6 +208,7 @@ Result footer includes:
 - `revision: ...`
 - `file: ...`
 - `changed_ranges: ...` when relevant
+- `remapped_refs: ...` when stale anchors were uniquely relocated
 - `retry_checksum: ...` on local conflicts
 
 ### write_file
@@ -228,7 +222,7 @@ Create a new file or overwrite an existing one. Creates parent directories autom
 
 ### grep_search
 
-Search file contents using ripgrep. Three output modes: `content` (hash-annotated with checksums), `files` (paths only), `count` (match counts).
+Search file contents using ripgrep. Three output modes: `content` (hash-annotated with checksums), `files` (plain path list), `count` (plain `file:count` list).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -248,7 +242,7 @@ Search file contents using ripgrep. Three output modes: `content` (hash-annotate
 | `total_limit` | number | no | Total match events across all files; multiline matches count as 1 (0 = unlimited) |
 | `plain` | boolean | no | Omit hash tags, return `file:line:content` |
 
-**Content mode** returns per-group checksums enabling direct `replace_lines` from grep results without intermediate `read_file`.
+`content` mode returns per-group checksums enabling direct `replace_lines` from grep results without intermediate `read_file`.
 
 ### outline
 
@@ -269,7 +263,7 @@ Check if range checksums from a prior read are still valid, optionally relative
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | string | yes | File path |
-| `checksums` | string | yes | JSON array of checksum strings, e.g. `["1-50:f7e2a1b0"]` |
+| `checksums` | string[] | yes | Array of checksum strings, e.g. `["1-50:f7e2a1b0"]` |
 | `base_revision` | string | no | Prior revision to compare against latest state |
 
 Returns a single-line confirmation or lists changed ranges.
@@ -330,7 +324,7 @@ Configuration constants in `hook.mjs`:
 
 ### SessionStart: Tool Preferences
 
-Injects hex-line tool preference list into agent context at session start.
+Injects a short operational workflow into agent context at session start: no `ToolSearch`, prefer `outline -> read_file -> edit_file -> verify`, and use targeted reads over full-file reads.
 
 ## Architecture
 

package/dist/hook.mjs

@@ -54,7 +54,7 @@ function normalizeOutput(text, opts = {}) {
 }
 
 // hook.mjs
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -91,13 +91,13 @@ var BINARY_EXT = /* @__PURE__ */ new Set([
 ]);
 var REVERSE_TOOL_HINTS = {
   "mcp__hex-line__read_file": "Read (file_path, offset, limit)",
-  "mcp__hex-line__edit_file": "Edit (revision-aware hash edits, block rewrite, auto-rebase)",
+  "mcp__hex-line__edit_file": "Edit (old_string, new_string, replace_all)",
   "mcp__hex-line__write_file": "Write (file_path, content)",
   "mcp__hex-line__grep_search": "Grep (pattern, path)",
   "mcp__hex-line__directory_tree": "Glob (pattern) or Bash(ls)",
   "mcp__hex-line__get_file_info": "Bash(stat/wc)",
   "mcp__hex-line__outline": "Read with offset/limit",
-  "mcp__hex-line__verify": "Verify held checksums / revision without reread",
+  "mcp__hex-line__verify": "Read (re-read file to check freshness)",
   "mcp__hex-line__changes": "Bash(git diff)",
   "mcp__hex-line__bulk_replace": "Edit (text rename/refactor across files)",
   "mcp__hex-line__setup_hooks": "Not available (hex-line disabled)"
@@ -114,10 +114,10 @@ var TOOL_HINTS = {
   stat: "mcp__hex-line__get_file_info (not stat/wc/file)",
   grep: "mcp__hex-line__grep_search (not grep/rg). Params: output, literal, context_before, context_after, multiline",
   sed: "mcp__hex-line__edit_file for hash edits, or mcp__hex-line__bulk_replace for text rename (not sed -i)",
-  diff: "mcp__hex-line__changes (not diff). Git-based semantic diff",
+  diff: "mcp__hex-line__changes (not diff). Git diff with change symbols",
   outline: "mcp__hex-line__outline (before reading large code files)",
   verify: "mcp__hex-line__verify (staleness / revision check without re-read)",
-  changes: "mcp__hex-line__changes (semantic AST diff)",
+  changes: "mcp__hex-line__changes (git diff with change symbols)",
   bulk: "mcp__hex-line__bulk_replace (multi-file search-replace)",
   setup: "mcp__hex-line__setup_hooks (configure hooks for agents)"
 };
@@ -183,10 +183,31 @@ var CMD_PATTERNS = [
 var LINE_THRESHOLD = 50;
 var HEAD_LINES = 15;
 var TAIL_LINES = 15;
+var LARGE_FILE_BYTES = 15 * 1024;
+var LARGE_EDIT_CHARS = 1200;
 function extOf(filePath) {
   const dot = filePath.lastIndexOf(".");
   return dot !== -1 ? filePath.slice(dot).toLowerCase() : "";
 }
+function getFilePath(toolInput) {
+  return toolInput.file_path || toolInput.path || "";
+}
+function resolveToolPath(filePath) {
+  if (!filePath) return "";
+  if (filePath.startsWith("~/")) return resolve(homedir(), filePath.slice(2));
+  return resolve(process.cwd(), filePath);
+}
+function getFileSize(filePath) {
+  if (!filePath) return null;
+  try {
+    return statSync(resolveToolPath(filePath)).size;
+  } catch {
+    return null;
+  }
+}
+function isPartialRead(toolInput) {
+  return [toolInput.offset, toolInput.limit, toolInput.start_line, toolInput.end_line, toolInput.ranges].some((value) => value !== void 0 && value !== null && value !== "");
+}
 function detectCommandType(cmd) {
   for (const [re, type] of CMD_PATTERNS) {
     if (re.test(cmd)) return type;
@@ -249,7 +270,8 @@ function handlePreToolUse(data) {
   }
   const hintKey = TOOL_REDIRECT_MAP[toolName];
   if (hintKey) {
-    const filePath = toolInput.file_path || toolInput.path || "";
+    const filePath = getFilePath(toolInput);
+    const fileSize = getFileSize(filePath);
     if (BINARY_EXT.has(extOf(filePath))) {
       process.exit(0);
     }
@@ -272,10 +294,30 @@ function handlePreToolUse(data) {
         process.exit(0);
       }
     }
-    const hint = TOOL_HINTS[hintKey];
-    const toolName2 = hint.split(" (")[0];
-    const pathNote = filePath ? ` with path="${filePath}"` : "";
-    block(`Use ${toolName2}${pathNote}`, hint);
+    if (toolName === "Read") {
+      if (isPartialRead(toolInput) || fileSize !== null && fileSize <= LARGE_FILE_BYTES) {
+        process.exit(0);
+      }
+      const target = filePath ? `Use mcp__hex-line__outline or mcp__hex-line__read_file with path="${filePath}"` : "Use mcp__hex-line__directory_tree or mcp__hex-line__read_file";
+      block(target, "For large or unknown full reads: call outline first, then read_file with offset/limit or ranges. Do not use built-in Read here.");
+    }
+    if (toolName === "Edit") {
+      const oldText = String(toolInput.old_string || "");
+      const isLargeEdit = Boolean(toolInput.replace_all) || oldText.length > LARGE_EDIT_CHARS || fileSize !== null && fileSize > LARGE_FILE_BYTES;
+      if (!isLargeEdit) {
+        process.exit(0);
+      }
+      const target = filePath ? `Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file with path="${filePath}"` : "Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file";
+      block(target, "For large or repeated edits: locate anchors/checksums first, then call edit_file once with batched edits.");
+    }
+    if (toolName === "Write") {
+      const pathNote = filePath ? ` with path="${filePath}"` : "";
+      block(`Use mcp__hex-line__write_file${pathNote}`, TOOL_HINTS.Write);
+    }
+    if (toolName === "Grep") {
+      const pathNote = filePath ? ` with path="${filePath}"` : "";
+      block(`Use mcp__hex-line__grep_search${pathNote}`, TOOL_HINTS.Grep);
+    }
   }
   if (toolName === "Bash") {
     const command = (toolInput.command || "").trim();
@@ -381,22 +423,8 @@ function handleSessionStart() {
     } catch {
     }
   }
-  if (styleActive) {
-    process.stdout.write(JSON.stringify({ systemMessage: "hex-line Output Style active." }));
-    process.exit(0);
-  }
-  const seen = /* @__PURE__ */ new Set();
-  const lines = [];
-  for (const hint of Object.values(TOOL_HINTS)) {
-    const tool = hint.split(" ")[0];
-    if (!seen.has(tool)) {
-      seen.add(tool);
-      lines.push(`- ${hint}`);
-    }
-  }
-  lines.push("Exceptions: images, PDFs, notebooks, .claude/settings.json, .claude/settings.local.json \u2192 built-in Read; Glob always OK");
-  lines.push("Bash OK for: npm/node/git/docker/curl, pipes, scripts");
-  const msg = "Hex-line MCP available. Workflow:\n- Discovery: read_file, grep_search, outline, directory_tree\n- Same-file edits: prefer ONE edit_file call per file, carry revision/base_revision\n- Hash edits: edit_file (set_line, replace_lines, insert_after, replace_between)\n- Large rewrites: replace_between instead of reciting old blocks\n- Text rename: bulk_replace (multi-file search-replace)\n- Verify staleness: verify before considering reread\n- Write new: write_file\n" + lines.join("\n");
+  const prefix = styleActive ? "Hex-line MCP available. Output style active.\n" : "Hex-line MCP available.\n";
+  const msg = prefix + "Call hex-line tools directly. Do not use ToolSearch for hex-line tools.\nWorkflow:\n- Discovery: outline for large code files, read_file for targeted reads, grep_search for symbol/text lookup\n- Read cheaply: prefer offset/limit or ranges; avoid full-file Read on large files\n- Edit safely: read/grep first, then one batched edit_file call per file with base_revision when available\n- Verify before reread: use verify to check checksums or revision freshness\n- Multi-file rename/refactor: use bulk_replace\n- New files: use write_file\nExceptions: images, PDFs, notebooks, .claude/settings.json, .claude/settings.local.json use built-in Read. Glob is always OK.";
   process.stdout.write(JSON.stringify({ systemMessage: msg }));
   process.exit(0);
 }

package/dist/server.mjs

@@ -6,7 +6,7 @@ import { dirname as dirname4 } from "node:path";
 import { z as z2 } from "zod";
 
 // ../hex-common/src/runtime/mcp-bootstrap.mjs
-async function createServerRuntime({ name, version: version2, installDir }) {
+async function createServerRuntime({ name, version: version2 }) {
   let McpServer, StdioServerTransport2;
   try {
     ({ McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js"));
@@ -14,11 +14,16 @@ async function createServerRuntime({ name, version: version2, installDir }) {
   } catch {
     process.stderr.write(
       `${name}: @modelcontextprotocol/sdk not found.
-Run: cd ${installDir} && npm install
+Run: npm install @modelcontextprotocol/sdk
 `
     );
     process.exit(1);
   }
+  const shutdown = () => {
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
   return {
     server: new McpServer({ name, version: version2 }),
     StdioServerTransport: StdioServerTransport2
@@ -250,6 +255,8 @@ function listDirectory(dirPath, opts = {}) {
 }
 var MAX_OUTPUT_CHARS = 8e4;
 var MAX_DIFF_CHARS = 3e4;
+var MAX_BULK_OUTPUT_CHARS = 3e4;
+var MAX_PER_FILE_DIFF_LINES = 50;
 function readText(filePath) {
   return readFileSync(filePath, "utf-8").replace(/\r\n/g, "\n");
 }
@@ -340,7 +347,7 @@ function getGraphDB(filePath) {
   try {
     const projectRoot = findProjectRoot(filePath);
     if (!projectRoot) return null;
-    const dbPath = join3(projectRoot, ".codegraph", "index.db");
+    const dbPath = join3(projectRoot, ".hex-skills/codegraph", "index.db");
     if (!existsSync2(dbPath)) return null;
     if (_dbs.has(dbPath)) return _dbs.get(dbPath);
     const require2 = createRequire(import.meta.url);
@@ -454,7 +461,7 @@ function getRelativePath(filePath) {
 function findProjectRoot(filePath) {
   let dir = dirname2(filePath);
   for (let i = 0; i < 10; i++) {
-    if (existsSync2(join3(dir, ".codegraph", "index.db"))) return dir;
+    if (existsSync2(join3(dir, ".hex-skills/codegraph", "index.db"))) return dir;
     const parent = dirname2(dir);
     if (parent === dir) break;
     dir = parent;
@@ -662,6 +669,24 @@ function buildRangeChecksum(snapshot, startLine, endLine) {
 
 // lib/read.mjs
 var DEFAULT_LIMIT = 2e3;
+function parseRangeEntry(entry, total) {
+  if (typeof entry === "string") {
+    const match = entry.trim().match(/^(\d+)(?:-(\d*)?)?$/);
+    if (!match) throw new Error(`Invalid range "${entry}". Use "10", "10-25", or "10-"`);
+    const start2 = Number(match[1]);
+    const end2 = match[2] === void 0 || match[2] === "" ? total : Number(match[2]);
+    return { start: start2, end: end2 };
+  }
+  if (!entry || typeof entry !== "object") {
+    throw new Error("ranges entries must be strings or {start,end} objects");
+  }
+  const start = Number(entry.start ?? 1);
+  const end = entry.end === void 0 || entry.end === null ? total : Number(entry.end);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    throw new Error("ranges entries must contain numeric start/end values");
+  }
+  return { start, end };
+}
 function readFile2(filePath, opts = {}) {
   filePath = normalizePath(filePath);
   const real = validatePath(filePath);
@@ -679,10 +704,13 @@ ${text}
   const total = lines.length;
   let ranges;
   if (opts.ranges && opts.ranges.length > 0) {
-    ranges = opts.ranges.map((r) => ({
-      start: Math.max(1, r.start || 1),
-      end: Math.min(total, r.end || total)
-    }));
+    ranges = opts.ranges.map((entry) => {
+      const parsed = parseRangeEntry(entry, total);
+      return {
+        start: Math.max(1, parsed.start),
+        end: Math.min(total, parsed.end)
+      };
+    });
   } else {
     const startLine = Math.max(1, opts.offset || 1);
     const maxLines = opts.limit && opts.limit > 0 ? opts.limit : DEFAULT_LIMIT;
@@ -712,24 +740,22 @@ ${text}
     range.end = actualEnd;
     parts.push(formatted.join("\n"));
     const cs = rangeChecksum(lineHashes, range.start, actualEnd);
-    parts.push(`
-checksum: ${cs}`);
+    parts.push(`checksum: ${cs}`);
     if (cappedAtLine) break;
   }
   const sizeKB = (stat.size / 1024).toFixed(1);
-  const mtime = stat.mtime;
-  const ago = relativeTime(mtime);
-  let header = `File: ${filePath} (${total} lines, ${sizeKB}KB, ${ago})`;
+  const ago = relativeTime(stat.mtime);
+  let meta = `${total} lines, ${sizeKB}KB, ${ago}`;
   if (ranges.length === 1) {
     const r = ranges[0];
     if (r.start > 1 || r.end < total) {
-      header += ` [showing ${r.start}-${r.end}]`;
+      meta += `, showing ${r.start}-${r.end}`;
     }
     if (r.end < total) {
-      header += ` (${total - r.end} more below)`;
+      meta += `, ${total - r.end} more below`;
     }
   }
-  const db = getGraphDB(real);
+  const db = opts.includeGraph ? getGraphDB(real) : null;
   const relFile = db ? getRelativePath(real) : null;
   let graphLine = "";
   if (db && relFile) {
@@ -743,18 +769,12 @@ checksum: ${cs}`);
 Graph: ${items.join(" | ")}`;
     }
   }
-  let result = `${header}${graphLine}
+  let result = `File: ${filePath}${graphLine}
+meta: ${meta}
 revision: ${snapshot.revision}
 file: ${snapshot.fileChecksum}
 
-\`\`\`
-${parts.join("\n")}
-\`\`\``;
-  if (total > 200 && (!opts.offset || opts.offset <= 1) && !cappedAtLine) {
-    result += `
-
-\u26A1 Tip: This file has ${total} lines. Use outline first, then read_file with offset/limit for 75% fewer tokens.`;
-  }
+${parts.join("\n\n")}`;
   if (cappedAtLine) {
     result += `
 
@@ -787,6 +807,26 @@ function buildErrorSnippet(lines, centerIdx, radius = 5) {
   }).join("\n");
   return { start: start + 1, end, text };
 }
+function stripAnchorOrDiffPrefix(line) {
+  let next = line;
+  next = next.replace(/^\s*(?:>>|  )?[a-z2-7]{2}\.\d+\t/, "");
+  next = next.replace(/^.+:(?:>>|  )[a-z2-7]{2}\.\d+\t/, "");
+  next = next.replace(/^[ +-]\d+\|\s?/, "");
+  return next;
+}
+function sanitizeEditText(text) {
+  const original = String(text ?? "");
+  const hadTrailingNewline = original.endsWith("\n");
+  let lines = original.split("\n");
+  const nonEmpty = lines.filter((line) => line.length > 0);
+  if (nonEmpty.length > 0 && nonEmpty.every((line) => /^\+(?!\+)/.test(line))) {
+    lines = lines.map((line) => line.startsWith("+") && !line.startsWith("++") ? line.slice(1) : line);
+  }
+  lines = lines.map(stripAnchorOrDiffPrefix);
+  let cleaned = lines.join("\n");
+  if (hadTrailingNewline && !cleaned.endsWith("\n")) cleaned += "\n";
+  return cleaned;
+}
 function findLine(lines, lineNum, expectedTag, hashIndex) {
   const idx = lineNum - 1;
   if (idx < 0 || idx >= lines.length) {
@@ -902,6 +942,7 @@ function buildConflictMessage({
   centerIdx,
   changedRanges,
   retryChecksum,
+  remaps,
   details
 }) {
   const safeCenter = Math.max(0, Math.min(lines.length - 1, centerIdx));
@@ -914,6 +955,9 @@ file: ${fileChecksum}`;
 changed_ranges: ${describeChangedRanges(changedRanges)}`;
   if (retryChecksum) msg += `
 retry_checksum: ${retryChecksum}`;
+  if (remaps?.length) msg += `
+remapped_refs:
+${remaps.map(({ from, to }) => `${from} -> ${to}`).join("\n")}`;
   msg += `
 
 ${details}
@@ -948,6 +992,8 @@ function editFile(filePath, edits, opts = {}) {
   const hadTrailingNewline = original.endsWith("\n");
   const hashIndex = currentSnapshot.uniqueTagIndex;
   let autoRebased = false;
+  const remaps = [];
+  const remapKeys = /* @__PURE__ */ new Set();
   const anchored = [];
   for (const e of edits) {
     if (e.set_line || e.replace_lines || e.insert_after || e.replace_between) anchored.push(e);
@@ -1004,12 +1050,24 @@ function editFile(filePath, edits, opts = {}) {
       centerIdx,
       changedRanges: staleRevision && hasBaseSnapshot ? changedRanges : null,
       retryChecksum,
+      remaps,
       details
     });
   };
+  const trackRemap = (ref, idx) => {
+    const actualRef = `${lineTag(fnv1a(lines[idx]))}.${idx + 1}`;
+    const expectedRef = `${ref.tag}.${ref.line}`;
+    if (actualRef === expectedRef) return;
+    const key = `${expectedRef}->${actualRef}`;
+    if (remapKeys.has(key)) return;
+    remapKeys.add(key);
+    remaps.push({ from: expectedRef, to: actualRef });
+  };
   const locateOrConflict = (ref, reason = "stale_anchor") => {
     try {
-      return findLine(lines, ref.line, ref.tag, hashIndex);
+      const idx = findLine(lines, ref.line, ref.tag, hashIndex);
+      trackRemap(ref, idx);
+      return idx;
     } catch (e) {
       if (conflictPolicy !== "conservative" || !staleRevision) throw e;
       const centerIdx = Math.max(0, Math.min(lines.length - 1, ref.line - 1));
@@ -1051,7 +1109,7 @@ function editFile(filePath, edits, opts = {}) {
           lines.splice(idx, 1);
         } else {
           const origLine = [lines[idx]];
-          const raw = String(txt).split("\n");
+          const raw = sanitizeEditText(txt).split("\n");
           const newLines = opts.restoreIndent ? restoreIndent(origLine, raw) : raw;
           lines.splice(idx, 1, ...newLines);
         }
@@ -1063,7 +1121,7 @@ function editFile(filePath, edits, opts = {}) {
         if (typeof idx === "string") return idx;
         const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
         if (conflict) return conflict;
-        let insertLines = e.insert_after.text.split("\n");
+        let insertLines = sanitizeEditText(e.insert_after.text).split("\n");
         if (opts.restoreIndent) insertLines = restoreIndent([lines[idx]], insertLines);
         lines.splice(idx + 1, 0, ...insertLines);
         continue;
@@ -1127,7 +1185,7 @@ Retry with fresh checksum ${actual}, or use set_line with hashes above.`
           lines.splice(si, ei - si + 1);
         } else {
           const origRange = lines.slice(si, ei + 1);
-          let newLines = String(txt).split("\n");
+          let newLines = sanitizeEditText(txt).split("\n");
           if (opts.restoreIndent) newLines = restoreIndent(origRange, newLines);
           lines.splice(si, ei - si + 1, ...newLines);
         }
@@ -1151,7 +1209,7 @@ Retry with fresh checksum ${actual}, or use set_line with hashes above.`
         const conflict = ensureRevisionContext(targetRange.start, targetRange.end, si);
         if (conflict) return conflict;
         const txt = e.replace_between.new_text;
-        let newLines = String(txt ?? "").split("\n");
+        let newLines = sanitizeEditText(txt ?? "").split("\n");
         const sliceStart = boundaryMode === "exclusive" ? si + 1 : si;
         const removeCount = boundaryMode === "exclusive" ? Math.max(0, ei - si - 1) : ei - si + 1;
         const origRange = lines.slice(sliceStart, sliceStart + removeCount);
@@ -1212,6 +1270,11 @@ file: ${nextSnapshot.fileChecksum}`;
   if (autoRebased && staleRevision && hasBaseSnapshot) {
     msg += `
 changed_ranges: ${describeChangedRanges(changedRanges)}`;
+  }
+  if (remaps.length > 0) {
+    msg += `
+remapped_refs:
+${remaps.map(({ from, to }) => `${from} -> ${to}`).join("\n")}`;
   }
   msg += `
 Updated ${filePath} (${content.split("\n").length} lines)`;
@@ -1327,9 +1390,7 @@ async function filesMode(pattern, target, opts) {
   if (code !== 0 && code !== null) throw new Error(`GREP_ERROR: rg exit ${code} \u2014 ${stderr.trim() || "unknown error"}`);
   const lines = stdout.trimEnd().split("\n").filter(Boolean);
   const normalized = lines.map((l) => l.replace(/\\/g, "/"));
-  return `\`\`\`
-${normalized.join("\n")}
-\`\`\``;
+  return normalized.join("\n");
 }
 async function countMode(pattern, target, opts) {
   const realArgs = ["-c"];
@@ -1346,9 +1407,7 @@ async function countMode(pattern, target, opts) {
   if (code !== 0 && code !== null) throw new Error(`GREP_ERROR: rg exit ${code} \u2014 ${stderr.trim() || "unknown error"}`);
   const lines = stdout.trimEnd().split("\n").filter(Boolean);
   const normalized = lines.map((l) => l.replace(/\\/g, "/"));
-  return `\`\`\`
-${normalized.join("\n")}
-\`\`\``;
+  return normalized.join("\n");
 }
 async function contentMode(pattern, target, opts, plain, totalLimit) {
   const realArgs = ["--json"];
@@ -1455,16 +1514,12 @@ async function contentMode(pattern, target, opts, plain, totalLimit) {
       if (totalLimit > 0 && matchCount >= totalLimit) {
         flushGroup();
         formatted.push(`--- total_limit reached (${totalLimit}) ---`);
-        return `\`\`\`
-${formatted.join("\n")}
-\`\`\``;
+        return formatted.join("\n");
       }
     }
   }
   flushGroup();
-  return `\`\`\`
-${formatted.join("\n")}
-\`\`\``;
+  return formatted.join("\n");
 }
 
 // lib/outline.mjs
@@ -1602,6 +1657,26 @@ function extractOutline(rootNode, config, sourceLines) {
   walk(rootNode, 0);
   return { entries, skippedRanges };
 }
+function fallbackOutline(sourceLines) {
+  const entries = [];
+  for (let index = 0; index < sourceLines.length; index++) {
+    const line = sourceLines[index];
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(
+      /^(?:export\s+)?(?:async\s+)?function\s+[\w$]+|^(?:export\s+)?(?:const|let|var)\s+[\w$]+\s*=|^(?:export\s+)?class\s+[\w$]+|^(?:export\s+)?interface\s+[\w$]+|^(?:export\s+)?type\s+[\w$]+\s*=|^(?:export\s+)?enum\s+[\w$]+|^(?:export\s+default\s+)?[\w$]+\s*=>/
+    );
+    if (!match) continue;
+    entries.push({
+      start: index + 1,
+      end: index + 1,
+      depth: 0,
+      text: trimmed.slice(0, 120),
+      name: trimmed.match(/([\w$]+)/)?.[1] || null
+    });
+  }
+  return entries;
+}
 async function outlineFromContent(content, ext) {
   const config = LANG_CONFIGS[ext];
   const grammar = grammarForExtension(ext);
@@ -1618,8 +1693,9 @@ async function outlineFromContent(content, ext) {
   const tree = parser.parse(content);
   return extractOutline(tree.rootNode, config, sourceLines);
 }
-function formatOutline(entries, skippedRanges, sourceLineCount, db, relFile) {
+function formatOutline(entries, skippedRanges, sourceLineCount, db, relFile, note = "") {
   const lines = [];
+  if (note) lines.push(note, "");
   if (skippedRanges.length > 0) {
     const first = skippedRanges[0].start;
     const last = skippedRanges[skippedRanges.length - 1].end;
@@ -1645,11 +1721,13 @@ async function fileOutline(filePath) {
   }
   const content = readUtf8Normalized(real);
   const result = await outlineFromContent(content, ext);
+  const entries = result.entries.length > 0 ? result.entries : fallbackOutline(content.split("\n"));
+  const note = result.entries.length > 0 || entries.length === 0 ? "" : "Fallback outline: heuristic symbols shown because parser returned no structural entries.";
   const db = getGraphDB(real);
   const relFile = db ? getRelativePath(real) : null;
   return `File: ${filePath}
 
-${formatOutline(result.entries, result.skippedRanges, content.split("\n").length, db, relFile)}`;
+${formatOutline(entries, result.skippedRanges, content.split("\n").length, db, relFile, note)}`;
 }
 
 // lib/verify.mjs
@@ -1964,19 +2042,18 @@ function fileInfo(filePath) {
 }
 
 // lib/setup.mjs
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5, mkdirSync } from "node:fs";
-import { resolve as resolve6, dirname as dirname3 } from "node:path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5, mkdirSync, copyFileSync } from "node:fs";
+import { resolve as resolve6, dirname as dirname3, join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+var STABLE_HOOK_DIR = resolve6(homedir(), ".claude", "hex-line");
+var STABLE_HOOK_PATH = join5(STABLE_HOOK_DIR, "hook.mjs").replace(/\\/g, "/");
+var HOOK_COMMAND = `node ${STABLE_HOOK_PATH}`;
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname3(__filename);
-var HOOK_SCRIPT = resolve6(__dirname, "..", "hook.mjs").replace(/\\/g, "/");
-var HOOK_COMMAND = `node ${HOOK_SCRIPT}`;
-var HOOK_SIGNATURE = "hex-line-mcp/hook.mjs";
-var NPX_MARKERS = ["_npx", "npx-cache", ".npm/_npx"];
-function isEphemeralInstall(scriptPath) {
-  return NPX_MARKERS.some((m) => scriptPath.includes(m));
-}
+var SOURCE_HOOK = resolve6(__dirname, "..", "hook.mjs");
+var DIST_HOOK = resolve6(__dirname, "hook.mjs");
+var HOOK_SIGNATURE = "hex-line";
 var CLAUDE_HOOKS = {
   SessionStart: {
     matcher: "*",
@@ -2038,7 +2115,7 @@ function writeHooksToFile(settingsPath, label) {
     return `Claude (${label}): already configured`;
   }
   writeJson(settingsPath, config);
-  return `Claude (${label}): hooks -> ${HOOK_SCRIPT} OK`;
+  return `Claude (${label}): hooks -> ${STABLE_HOOK_PATH} OK`;
 }
 function cleanLocalHooks() {
   const localPath = resolve6(process.cwd(), ".claude/settings.local.json");
@@ -2084,10 +2161,14 @@ function installOutputStyle() {
   return msg;
 }
 function setupClaude() {
-  if (isEphemeralInstall(HOOK_SCRIPT)) {
-    return "Claude: SKIPPED \u2014 hook.mjs is in npx cache (ephemeral). Install permanently: npm i -g @levnikolaevich/hex-line-mcp, then re-run setup_hooks.";
-  }
   const results = [];
+  const hookSource = existsSync5(DIST_HOOK) ? DIST_HOOK : SOURCE_HOOK;
+  if (!existsSync5(hookSource)) {
+    return "Claude: FAILED \u2014 hook.mjs not found. Reinstall @levnikolaevich/hex-line-mcp.";
+  }
+  mkdirSync(STABLE_HOOK_DIR, { recursive: true });
+  copyFileSync(hookSource, STABLE_HOOK_PATH);
+  results.push(`hook.mjs -> ${STABLE_HOOK_PATH}`);
   const globalPath = resolve6(homedir(), ".claude/settings.json");
   results.push(writeHooksToFile(globalPath, "global"));
   results.push(cleanLocalHooks());
@@ -2265,8 +2346,8 @@ Summary: ${summary}`);
 }
 
 // lib/bulk-replace.mjs
-import { writeFileSync as writeFileSync3, readdirSync as readdirSync3 } from "node:fs";
-import { resolve as resolve7, relative as relative3, join as join5 } from "node:path";
+import { writeFileSync as writeFileSync3, readdirSync as readdirSync3, renameSync, unlinkSync } from "node:fs";
+import { resolve as resolve7, relative as relative3, join as join6 } from "node:path";
 var ignoreMod;
 try {
   ignoreMod = await import("ignore");
@@ -2282,7 +2363,7 @@ function walkFiles(dir, rootDir, ig) {
   }
   for (const e of entries) {
     if (e.name === ".git" || e.name === "node_modules") continue;
-    const full = join5(dir, e.name);
+    const full = join6(dir, e.name);
     const rel = relative3(rootDir, full).replace(/\\/g, "/");
     if (ig && ig.ignores(rel)) continue;
     if (e.isDirectory()) {
@@ -2294,21 +2375,21 @@ function walkFiles(dir, rootDir, ig) {
   return results;
 }
 function globMatch(filename, pattern) {
-  const re = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, ".*").replace(/\?/g, ".");
+  const re = pattern.replace(/\./g, "\\.").replace(/\{([^}]+)\}/g, (_, alts) => "(" + alts.split(",").join("|") + ")").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, ".*").replace(/\?/g, ".");
   return new RegExp("^" + re + "$").test(filename);
 }
 function loadGitignore2(rootDir) {
   if (!ignoreMod) return null;
   const ig = (ignoreMod.default || ignoreMod)();
   try {
-    const content = readText(join5(rootDir, ".gitignore"));
+    const content = readText(join6(rootDir, ".gitignore"));
     ig.add(content);
   } catch {
   }
   return ig;
 }
 function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
-  const { dryRun = false, maxFiles = 100 } = opts;
+  const { dryRun = false, maxFiles = 100, format = "compact" } = opts;
   const abs = resolve7(normalizePath(rootDir));
   const ig = loadGitignore2(abs);
   const allFiles = walkFiles(abs, abs, ig);
@@ -2321,55 +2402,92 @@ function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
     return `TOO_MANY_FILES: Found ${files.length} files, max_files is ${maxFiles}. Use more specific glob or increase max_files.`;
   }
   const results = [];
-  let changed = 0, skipped = 0, errors = 0;
-  const MAX_OUTPUT2 = MAX_OUTPUT_CHARS;
-  let totalChars = 0;
+  let changed = 0, skipped = 0, errors = 0, totalReplacements = 0;
   for (const file of files) {
     try {
       const original = readText(file);
       let content = original;
+      let replacementCount = 0;
       for (const { old: oldText, new: newText } of replacements) {
-        content = content.split(oldText).join(newText);
+        if (oldText === newText) continue;
+        const parts = content.split(oldText);
+        replacementCount += parts.length - 1;
+        content = parts.join(newText);
       }
       if (content === original) {
         skipped++;
         continue;
       }
-      const diff = simpleDiff(original.split("\n"), content.split("\n"));
       if (!dryRun) {
-        writeFileSync3(file, content, "utf-8");
+        const tempPath = `${file}.hexline-tmp-${process.pid}`;
+        try {
+          writeFileSync3(tempPath, content, "utf-8");
+          renameSync(tempPath, file);
+        } catch (error) {
+          try {
+            unlinkSync(tempPath);
+          } catch {
+          }
+          throw error;
+        }
       }
-      const relPath = file.replace(abs, "").replace(/^[/\\]/, "");
-      results.push(`--- ${relPath}
-${diff || "(no visible diff)"}`);
+      const relPath = relative3(abs, file).replace(/\\/g, "/");
+      totalReplacements += replacementCount;
       changed++;
-      totalChars += results[results.length - 1].length;
-      if (totalChars > MAX_OUTPUT2) {
-        const remaining = files.length - files.indexOf(file) - 1;
-        if (remaining > 0) results.push(`OUTPUT_CAPPED: ${remaining} more files not shown. Output exceeded ${MAX_OUTPUT2} chars.`);
-        break;
+      if (format === "full") {
+        const diff = simpleDiff(original.split("\n"), content.split("\n"));
+        let diffText = diff || "(no visible diff)";
+        const diffLines3 = diffText.split("\n");
+        if (diffLines3.length > MAX_PER_FILE_DIFF_LINES) {
+          const omitted = diffLines3.length - MAX_PER_FILE_DIFF_LINES;
+          diffText = diffLines3.slice(0, MAX_PER_FILE_DIFF_LINES).join("\n") + `
+--- ${omitted} lines omitted ---`;
+        }
+        results.push(`--- ${relPath}: ${replacementCount} replacements
+${diffText}`);
+      } else {
+        results.push(`--- ${relPath}: ${replacementCount} replacements`);
       }
     } catch (e) {
       results.push(`ERROR: ${file}: ${e.message}`);
       errors++;
     }
   }
-  const header = `Bulk replace: ${changed} files changed, ${skipped} skipped, ${errors} errors (dry_run: ${dryRun})`;
-  return results.length ? `${header}
+  const header = `Bulk replace: ${changed} files changed (${totalReplacements} replacements), ${skipped} skipped, ${errors} errors (dry_run: ${dryRun})`;
+  let output = results.length ? `${header}
 
 ${results.join("\n\n")}` : header;
+  if (output.length > MAX_BULK_OUTPUT_CHARS) {
+    output = output.slice(0, MAX_BULK_OUTPUT_CHARS) + `
+OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
+  }
+  return output;
 }
 
 // server.mjs
-var version = true ? "1.3.6" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.5.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
-  version,
-  installDir: "mcp/hex-line-mcp"
+  version
 });
 var replacementPairsSchema = z2.array(
   z2.object({ old: z2.string().min(1), new: z2.string() })
 ).min(1);
+var readRangeSchema = z2.union([
+  z2.string(),
+  z2.object({
+    start: flexNum().optional(),
+    end: flexNum().optional()
+  })
+]);
+function parseReadRanges(rawRanges) {
+  if (!rawRanges) return void 0;
+  const parsed = Array.isArray(rawRanges) ? rawRanges : JSON.parse(rawRanges);
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error("ranges must be a non-empty array");
+  }
+  return parsed;
+}
 function coerceEdit(e) {
   if (!e || typeof e !== "object" || Array.isArray(e)) return e;
   if (e.set_line || e.replace_lines || e.insert_after || e.replace_between || e.replace) return e;
@@ -2390,23 +2508,26 @@ function coerceEdit(e) {
 }
 server.registerTool("read_file", {
   title: "Read File",
-  description: "Read a file with hash-annotated lines, range checksums, and current revision. Use offset/limit for targeted reads; use outline first for large code files.",
+  description: "Read file lines with hashes, checksums, and revision metadata.",
   inputSchema: z2.object({
     path: z2.string().optional().describe("File or directory path"),
     paths: z2.array(z2.string()).optional().describe("Array of file paths to read (batch mode)"),
     offset: flexNum().describe("Start line (1-indexed, default: 1)"),
     limit: flexNum().describe("Max lines (default: 2000, 0 = all)"),
+    ranges: z2.union([z2.string(), z2.array(readRangeSchema)]).optional().describe('Line ranges, e.g. ["10-25", {"start":40,"end":55}]'),
+    include_graph: flexBool().describe("Include graph annotations"),
     plain: flexBool().describe("Omit hashes (lineNum|content)")
   }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
 }, async (rawParams) => {
-  const { path: p, paths: multi, offset, limit, plain } = coerceParams(rawParams);
+  const { path: p, paths: multi, offset, limit, ranges: rawRanges, include_graph, plain } = coerceParams(rawParams);
   try {
+    const ranges = parseReadRanges(rawRanges);
     if (multi && multi.length > 0 && !p) {
       const results = [];
       for (const fp of multi) {
         try {
-          results.push(readFile2(fp, { offset, limit, plain }));
+          results.push(readFile2(fp, { offset, limit, ranges, includeGraph: include_graph, plain }));
         } catch (e) {
           results.push(`File: ${fp}
 
@@ -2416,14 +2537,14 @@ ERROR: ${e.message}`);
       return { content: [{ type: "text", text: results.join("\n\n---\n\n") }] };
     }
     if (!p) throw new Error("Either 'path' or 'paths' is required");
-    return { content: [{ type: "text", text: readFile2(p, { offset, limit, plain }) }] };
+    return { content: [{ type: "text", text: readFile2(p, { offset, limit, ranges, includeGraph: include_graph, plain }) }] };
   } catch (e) {
     return { content: [{ type: "text", text: e.message }], isError: true };
   }
 });
 server.registerTool("edit_file", {
   title: "Edit File",
-  description: "Apply revision-aware partial edits to one file. Prefer one batched call per file. Supports set_line, replace_lines, insert_after, and replace_between. For text rename/refactor use bulk_replace.",
+  description: "Apply verified partial edits to one file.",
   inputSchema: z2.object({
     path: z2.string().describe("File to edit"),
     edits: z2.union([z2.string(), z2.array(z2.any())]).describe(
@@ -2482,7 +2603,7 @@ server.registerTool("write_file", {
 });
 server.registerTool("grep_search", {
   title: "Search Files",
-  description: "Search file contents with ripgrep. Returns hash-annotated matches with checksums. Modes: content (default), files, count. Use checksums with set_line/replace_lines. Prefer over shell grep/rg.",
+  description: "Search file contents with ripgrep and return edit-ready matches.",
   inputSchema: z2.object({
     pattern: z2.string().describe("Search pattern (regex by default, literal if literal:true)"),
     path: z2.string().optional().describe("Search dir/file (default: cwd)"),
@@ -2559,19 +2680,20 @@ server.registerTool("outline", {
 });
 server.registerTool("verify", {
   title: "Verify Checksums",
-  description: "Check whether held checksums and optional base_revision are still current, without rereading the file.",
+  description: "Verify held checksums without rereading the file.",
   inputSchema: z2.object({
     path: z2.string().describe("File path"),
-    checksums: z2.string().describe('JSON array of checksum strings, e.g. ["1-50:f7e2a1b0", "51-100:abcd1234"]'),
+    checksums: z2.array(z2.string()).describe('Checksum strings, e.g. ["1-50:f7e2a1b0", "51-100:abcd1234"]'),
     base_revision: z2.string().optional().describe("Optional prior revision to compare against latest state.")
   }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
 }, async (rawParams) => {
   const { path: p, checksums, base_revision } = coerceParams(rawParams);
   try {
-    const parsed = JSON.parse(checksums);
-    if (!Array.isArray(parsed)) throw new Error("checksums must be a JSON array of strings");
-    return { content: [{ type: "text", text: verifyChecksums(p, parsed, { baseRevision: base_revision }) }] };
+    if (!Array.isArray(checksums) || checksums.length === 0) {
+      throw new Error("checksums must be a non-empty array of strings");
+    }
+    return { content: [{ type: "text", text: verifyChecksums(p, checksums, { baseRevision: base_revision }) }] };
   } catch (e) {
     return { content: [{ type: "text", text: e.message }], isError: true };
   }
@@ -2645,13 +2767,14 @@ server.registerTool("changes", {
 });
 server.registerTool("bulk_replace", {
   title: "Bulk Replace",
-  description: "Search-and-replace across multiple files. Finds files by glob, applies ordered text replacements, returns per-file diffs. Use dry_run:true to preview. For single-file rename, set glob to the filename.",
+  description: "Search-and-replace across multiple files with compact or full diff output.",
   inputSchema: z2.object({
     replacements: z2.union([z2.string(), replacementPairsSchema]).describe('JSON array of {old, new} pairs: [{"old":"foo","new":"bar"}]'),
     glob: z2.string().optional().describe('File glob (default: "**/*.{md,mjs,json,yml,ts,js}")'),
     path: z2.string().optional().describe("Root directory (default: cwd)"),
     dry_run: flexBool().describe("Preview without writing (default: false)"),
-    max_files: flexNum().describe("Max files to process (default: 100)")
+    max_files: flexNum().describe("Max files to process (default: 100)"),
+    format: z2.enum(["compact", "full"]).optional().describe('"compact" (default) = summary only, "full" = include capped diffs')
   }),
   annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false }
 }, async (rawParams) => {
@@ -2669,7 +2792,7 @@ server.registerTool("bulk_replace", {
       params.path || process.cwd(),
       params.glob || "**/*.{md,mjs,json,yml,ts,js}",
       replacements,
-      { dryRun: params.dry_run || false, maxFiles: params.max_files || 100 }
+      { dryRun: params.dry_run || false, maxFiles: params.max_files || 100, format: params.format }
     );
     return { content: [{ type: "text", text: result }] };
   } catch (e) {

package/output-style.md

@@ -1,31 +1,33 @@
 ---
 name: hex-line
-description: hex-line MCP tool preferences + explanatory coding style with insights
+description: hex-line MCP tool preferences with compact coding style
 keep-coding-instructions: true
 ---
 
 # MCP Tool Preferences
 
-**PREFER** hex-line MCP for code files — hash-annotated reads enable safe edits:
+**PREFER** hex-line MCP for code files. Hash-annotated reads and verified edits keep context cheap and safe.
 
 | Instead of | Use | Why |
 |-----------|-----|-----|
 | Read | `mcp__hex-line__read_file` | Hash-annotated, revision-aware |
 | Edit | `mcp__hex-line__edit_file` | Hash-verified anchors + conservative auto-rebase |
-| Write | `mcp__hex-line__write_file` | Consistent workflow |
-| Grep | `mcp__hex-line__grep_search` | Hash-annotated matches |
+| Write | `mcp__hex-line__write_file` | No prior Read needed |
+| Grep | `mcp__hex-line__grep_search` | Edit-ready matches |
 | Edit (text rename) | `mcp__hex-line__bulk_replace` | Multi-file text rename/refactor |
+| Bash `find`/`tree` | `mcp__hex-line__directory_tree` | Pattern search, gitignore-aware |
 
 ## Efficient File Reading
 
-For UNFAMILIAR code files >100 lines, PREFER:
-1. `outline` first (10-20 lines of structure)
-2. `read_file` with offset/limit for the specific section you need
+For unfamiliar code files >100 lines, prefer:
+1. `outline` first
+2. `read_file` with `offset`/`limit` or `ranges`
+3. `paths` or `ranges` when batching several targets
 
-Avoid reading a large file in full — outline+targeted read saves 75% tokens.
+Avoid reading a large file in full. Prefer compact, targeted reads.
 
 Bash OK for: npm/node/git/docker/curl, pipes, compound commands.
-**Built-in OK for:** images, PDFs, notebooks, Glob (always), `.claude/settings.json` and `.claude/settings.local.json`.
+**Built-in OK for:** images, PDFs, notebooks, Glob (always), `.claude/settings.json`, `.claude/settings.local.json`.
 
 ## Edit Workflow
 
@@ -33,24 +35,24 @@ Prefer:
 1. collect all known hunks for one file
 2. send one `edit_file` call with batched edits
 3. carry `revision` from `read_file` into `base_revision` on follow-up edits
-4. use `replace_between` for large block rewrites
-5. use `verify` before rereading a file after staleness
+4. use `set_line`, `replace_lines`, `insert_after`, `replace_between` based on scope
+5. use `verify` before rereading after staleness
 
 Avoid:
 - chained same-file `edit_file` calls when all edits are already known
 - full-file rewrites for local changes
 - using `bulk_replace` for structural block rewrites
 
-# Explanatory Style
+# Response Style
 
-Provide educational insights about the codebase alongside task completion. When providing insights, you may exceed typical length constraints, but remain focused and relevant.
+Keep responses compact and operational. Explain only what is needed to complete the task or justify a non-obvious decision.
 
-## Insights
-
-Before and after writing code, provide brief educational explanations about implementation choices using:
-
-"`\u2736 Insight \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`
-[2-3 key educational points]
-`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`"
+Prefer:
+- short progress updates
+- direct tool calls without discovery chatter
+- concise summaries of edits and verification
 
-Focus on insights specific to the codebase or the code just written, not general programming concepts.
+Avoid:
+- mandatory educational blocks
+- long prose around tool usage
+- repeating obvious implementation details

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.3.6",
+  "version": "1.5.0",
   "mcpName": "io.github.levnikolaevich/hex-line-mcp",
   "type": "module",
   "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 11 tools: read, edit, write, grep, outline, verify, directory_tree, file_info, setup_hooks, changes, bulk_replace.",
@@ -28,7 +28,7 @@
   "_dep_notes": {
     "web-tree-sitter": "Pinned ^0.25.0: v0.26 ABI incompatible with tree-sitter-wasms 0.1.x (built with tree-sitter-cli 0.20.8). Language.load() silently fails.",
     "zod": "Pinned ^3.25.0: zod 4 breaks zod-to-json-schema (used by MCP SDK internally). Tool parameter descriptions not sent to clients. Revisit when MCP SDK switches to z.toJSONSchema().",
-    "better-sqlite3": "Optional. Used only by lib/graph-enrich.mjs for readonly access to hex-graph .codegraph/index.db. Graceful fallback if absent."
+    "better-sqlite3": "Optional. Used only by lib/graph-enrich.mjs for readonly access to hex-graph .hex-skills/codegraph/index.db. Graceful fallback if absent."
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",