@bigknoxy/hashpilot 4.6.3

package/src/mcp/server.ts

@@ -0,0 +1,325 @@
+/**
+ * MCP server over stdio (#25).
+ *
+ * The protocol surface is hand-written rather than taken from an SDK: MCP's
+ * stdio transport is newline-delimited JSON-RPC 2.0 and the four methods we
+ * need are small, while a dependency here would land in every install of a tool
+ * whose whole pitch is that it drops into any agent without ceremony.
+ *
+ * Tools are not declared here. They come from `OPERATIONS` in
+ * `src/core/operations.ts`, the same list the CLI is checked against, so the
+ * MCP surface cannot quietly drift from the documented commands.
+ */
+
+import { OPERATIONS, getOperation, inputSchemaFor } from "../core/operations";
+import { API_VERSION, setCommand, takeWarnings } from "../core/envelope";
+// Single source of truth for the version. Bun inlines this JSON import at
+// build time, so any bundle carries the real published version instead of a
+// stale env-var fallback (#156).
+import pkg from "../../package.json" with { type: "json" };
+
+/** The package version, echoed back in `initialize`'s `serverInfo`. */
+const SERVER_VERSION: string = pkg.version;
+
+/** The MCP revision we implement. Echoed back in `initialize`. */
+export const PROTOCOL_VERSION = "2024-11-05";
+
+/* ── JSON-RPC types ──────────────────────────────────────────────────── */
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  /** Absent for notifications, which take no response. */
+  id?: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+/** JSON-RPC reserved codes. Tool failures do NOT use these — see `callTool`. */
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+
+/* ── Method handlers ─────────────────────────────────────────────────── */
+
+function listTools() {
+  return {
+    tools: OPERATIONS.map((op) => ({
+      name: op.name,
+      description: `${op.summary}\n\n${op.description}`,
+      inputSchema: inputSchemaFor(op),
+      annotations: {
+        readOnlyHint: !op.mutates,
+        destructiveHint: op.mutates,
+        title: op.summary,
+      },
+    })),
+  };
+}
+
+/**
+ * Reject a call whose arguments cannot satisfy the operation before running it.
+ * Only presence and coarse shape are checked; the handlers coerce the rest.
+ * Returns a message, or null when the arguments are acceptable.
+ */
+function validateArgs(op: ReturnType<typeof getOperation>, args: Record<string, unknown>): string | null {
+  if (!op) return null;
+  const missing = op.params
+    .filter((p) => p.required)
+    .filter((p) => {
+      const v = args[p.name];
+      // An empty string is a legitimate value (a deletion, #40); only
+      // absence is missing.
+      return v === undefined || v === null;
+    })
+    .map((p) => p.name);
+  if (missing.length) return `missing required parameter(s): ${missing.join(", ")}`;
+
+  for (const p of op.params) {
+    const v = args[p.name];
+    if (v === undefined || v === null) continue;
+    if (p.type === "string[]" && !Array.isArray(v) && typeof v !== "string") {
+      return `parameter "${p.name}" must be an array of strings`;
+    }
+    // `Number("")` and `Number([])` are both 0, so a NaN test alone lets an
+    // empty string or an array through as a number. The handler then coerces it
+    // back to undefined and the call returns a green result for a nonsense
+    // argument — the same silent-success failure `findFailure` exists to stop.
+    if (p.type === "number" && !isNumeric(v)) {
+      return `parameter "${p.name}" must be a number`;
+    }
+  }
+  return null;
+}
+
+/** True only for a real number, or a string that is entirely one. */
+function isNumeric(v: unknown): boolean {
+  if (typeof v === "number") return Number.isFinite(v);
+  if (typeof v !== "string" || v.trim() === "") return false;
+  return Number.isFinite(Number(v));
+}
+
+/**
+ * Run one tool call.
+ *
+ * A failed *edit* is reported as `isError: true` on a successful JSON-RPC
+ * result, not as a JSON-RPC error: the distinction MCP draws is that protocol
+ * errors are the host's problem while tool errors are the model's to read and
+ * act on. The payload carries the envelope's `code` and `recovery` verbatim,
+ * which is the whole point — a stale anchor should reach the model as
+ * "re-read the file and retry", not as a stack trace.
+ */
+export async function callTool(name: string, rawArgs: unknown): Promise<Record<string, unknown>> {
+  // Scopes the envelope's `command` and clears any warnings left by a prior
+  // call, so `warnings` reports only what this tool call produced.
+  setCommand(name);
+  const op = getOperation(name);
+  if (!op) {
+    return errorResult(name, "UNKNOWN_TOOL", `No such tool: ${name}`, "Call tools/list to see the available tools.");
+  }
+
+  const args = (rawArgs && typeof rawArgs === "object" ? rawArgs : {}) as Record<string, unknown>;
+  const invalid = validateArgs(op, args);
+  if (invalid) {
+    return errorResult(name, "INVALID_ARGUMENTS", invalid, "Check the tool's inputSchema and call it again.");
+  }
+
+  try {
+    const data = await op.handler(args);
+    const failure = findFailure(data);
+    if (failure) {
+      return errorResult(
+        name,
+        String(failure.errorCode || failure.code || "EDIT_FAILED"),
+        String(failure.error || failure.message || "the edit did not apply"),
+        typeof failure.recovery === "string" ? failure.recovery : undefined,
+        data as Record<string, unknown>
+      );
+    }
+    return okResult(name, data);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const code = (err as { errorCode?: string })?.errorCode || "INTERNAL_ERROR";
+    return errorResult(name, code, message);
+  }
+}
+
+/**
+ * Find the payload that reports failure, or null when the call succeeded.
+ *
+ * `routeEdit` reports routing at the top level and the edit's own outcome one
+ * level down under `result`, so a check of only the outer `success` reads a
+ * failed edit as a success — which would hand the model a green result for an
+ * edit that never applied. Both levels are inspected, innermost first, because
+ * the inner object carries the specific `errorCode` worth surfacing.
+ */
+function findFailure(data: unknown): Record<string, unknown> | null {
+  if (!data || typeof data !== "object") return null;
+  const d = data as Record<string, unknown>;
+  const inner = findFailure(d.result);
+  if (inner) return inner;
+  return d.success === false ? d : null;
+}
+
+/**
+ * MCP results carry text content. The text is the JSON envelope: models read it
+ * directly, and a host that wants structure gets the same object back under
+ * `structuredContent`.
+ */
+function okResult(command: string, data: unknown): Record<string, unknown> {
+  // The full five-field envelope, identical to the CLI's: an adapter written
+  // against docs/ADAPTER-CONTRACT.md must not have to special-case MCP (#104).
+  const payload = {
+    apiVersion: API_VERSION,
+    ok: true,
+    command,
+    data: data ?? null,
+    error: null,
+    warnings: takeWarnings(),
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    structuredContent: payload,
+    isError: false,
+  };
+}
+
+function errorResult(
+  command: string,
+  code: string,
+  message: string,
+  recovery?: string,
+  details?: unknown
+): Record<string, unknown> {
+  const payload = {
+    apiVersion: API_VERSION,
+    ok: false,
+    command,
+    data: details ?? null,
+    error: { code, message, ...(recovery ? { recovery } : {}), ...(details ? { details } : {}) },
+    warnings: takeWarnings(),
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    structuredContent: payload,
+    isError: true,
+  };
+}
+
+/**
+ * Dispatch one request. Returns null for notifications, which JSON-RPC forbids
+ * answering — `notifications/initialized` is the one every host sends.
+ */
+export async function handleRequest(req: JsonRpcRequest): Promise<JsonRpcResponse | null> {
+  const isNotification = req.id === undefined || req.id === null;
+  const id = req.id as string | number;
+
+  try {
+    switch (req.method) {
+      case "initialize":
+        return isNotification ? null : {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { tools: { listChanged: false } },
+            serverInfo: { name: "hashpilot", version: SERVER_VERSION },
+          },
+        };
+
+      case "notifications/initialized":
+      case "notifications/cancelled":
+        return null;
+
+      case "ping":
+        return isNotification ? null : { jsonrpc: "2.0", id, result: {} };
+
+      case "tools/list":
+        return isNotification ? null : { jsonrpc: "2.0", id, result: listTools() };
+
+      case "tools/call": {
+        const name = String(req.params?.name || "");
+        const result = await callTool(name, req.params?.arguments);
+        return isNotification ? null : { jsonrpc: "2.0", id, result };
+      }
+
+      default:
+        if (isNotification) return null;
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: { code: METHOD_NOT_FOUND, message: `Method not found: ${req.method}` },
+        };
+    }
+  } catch (err) {
+    if (isNotification) return null;
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: { code: INTERNAL_ERROR, message: err instanceof Error ? err.message : String(err) },
+    };
+  }
+}
+
+/** Parse and dispatch one newline-delimited message. Returns the line to write back, or null. */
+export async function handleLine(line: string): Promise<string | null> {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  let req: JsonRpcRequest;
+  try {
+    req = JSON.parse(trimmed);
+  } catch {
+    // No id is recoverable from unparseable input, so per JSON-RPC the id is null.
+    return JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: PARSE_ERROR, message: "Invalid JSON" } });
+  }
+
+  if (!req || typeof req.method !== "string") {
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id: req?.id ?? null,
+      error: { code: INVALID_REQUEST, message: "Missing method" },
+    });
+  }
+
+  const res = await handleRequest(req);
+  return res ? JSON.stringify(res) : null;
+}
+
+/**
+ * Run the stdio loop until stdin closes.
+ *
+ * Requests are handled strictly in order. Concurrency would be free wall-clock
+ * here, but two edits to one file interleaving inside one process would
+ * deadlock on the advisory lock (it is not re-entrant), and an agent's edits
+ * are usually sequentially dependent anyway.
+ *
+ * Nothing may be written to stdout but protocol frames — a stray log line
+ * corrupts the stream — so diagnostics go to stderr.
+ */
+export async function runStdioServer(): Promise<void> {
+  let buffer = "";
+  const decoder = new TextDecoder();
+
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += decoder.decode(chunk as Uint8Array, { stream: true });
+    let nl: number;
+    while ((nl = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + 1);
+      const out = await handleLine(line);
+      if (out !== null) process.stdout.write(out + "\n");
+    }
+  }
+
+  // A final frame with no trailing newline still deserves an answer.
+  const out = await handleLine(buffer);
+  if (out !== null) process.stdout.write(out + "\n");
+}

package/templates/claude-section.md

@@ -0,0 +1,12 @@
+## Install HashPilot
+`curl -fsSL https://raw.githubusercontent.com/bigknoxy/HashPilot/main/scripts/install.sh | bash` — installs `hashpilot` CLI on PATH; injects the section below into `~/.claude/CLAUDE.md`.
+
+## HashPilot Claude — Structured Editing Integration
+Active at user scope; `hashpilot` is on PATH.
+- **Preferred:** `claude mcp add hashpilot -- hashpilot mcp --stdio`. Tools mirror the CLI 1:1 (`rename_symbol`, `replace_hash`, `route_edit`, `verify_changes`, plus read/search tools); JSON avoids shell-quoting. Other hosts: `docs/INTEGRATION-MCP.md`. CLI below is the fallback when MCP is unavailable.
+- **Use when:** editing existing files, renaming symbols, replacing function bodies, managing imports, batch reading, verifying changes. **Skip when:** creating/deleting/moving files, one-off edits, other filesystem ops — use direct Edit/Write.
+- **Edit hierarchy** (top preferred): `hashpilot ast <subcommand>` (syntax-aware, best) → `hashpilot replace-hash` (hash-anchored, safe) → direct Edit/Write (fallback only).
+- **Batched ops:** `/hashpilot-read <paths>` (→ `read-many`), `/hashpilot-search <pattern>` (→ `grep-many`), `/hashpilot-verify [files]` (→ `verify-changes`).
+- **Introspection:** `hashpilot route <file> <op> [--policy <json>]`; `hashpilot config`.
+- **Output** (apiVersion 1): `{ apiVersion, ok, command, data, error, warnings }` — payload in `data`; failures carry `error.code` (+`error.recovery` when actionable); `ok` matches exit code; `warnings` covers route fallbacks/relocated anchors/corrupt telemetry. See `docs/ADAPTER-CONTRACT.md`.
+- **Status/control:** `/hashpilot-status`; `HASHPILOT_DISABLE=1` bypasses HashPilot entirely.

package/templates/opencode-agent.md

@@ -0,0 +1,106 @@
+---
+name: HashPilot
+description: Structured editing agent that uses HashPilot's hash-anchored and AST-aware editing to make precise, low-retry file changes. Prefers syntax-aware edits for TypeScript/TSX, hash-anchored edits for everything else, and verifies changes after editing.
+model: opencode/big-pickle
+small_model: github-copilot/gpt-5-mini
+mode: subagent
+temperature: 0.1
+tools:
+  bash: true
+  write: true
+  edit: true
+  read: true
+  grep: true
+  glob: true
+  list: true
+  patch: true
+  todowrite: true
+  todoread: true
+permissions:
+  edit: allow
+  bash: allow
+---
+
+You are the HashPilot editing agent. Make precise, minimal file edits using hashpilot commands. Never guess line numbers.
+
+## When to use this agent (delegate here)
+
+- Editing existing files in any language (TS/JS/Python/Go/Rust → AST; others → hash)
+- Renaming symbols, replacing function bodies, or managing imports
+- Making batch edits across multiple files
+- When precision matters (avoiding line-counting errors)
+- When you need stale-anchor detection (conflict safety)
+
+## When NOT to use this agent (do it yourself)
+
+- Creating new files → use write/edit directly
+- Deleting files or directories → use bash
+- Renaming/moving files → use bash
+- Simple single-line edits in non-critical files → just edit directly
+- Exploratory single-file reads → read directly (less overhead)
+- File system operations (cp, mv, rm) → use bash
+
+## Route hierarchy (always follow this order)
+
+1. **AST** — symbol ops in .ts/.tsx/.js/.py/.go/.rs (rename, replace-body, add/remove-import, insert)
+2. **Hash** — replace-hash for content changes in any file
+3. **Diff** — search+replace fallback for unsupported cases
+
+## Decision-first: determine your approach
+
+**Q1: What file type?** .ts/.tsx/.js/.py/.go/.rs → `ast`. Everything else → `replace-hash`.
+
+**Q2: Should I search first?** Need symbol defs? → `grep-many`. Need references? → `symbol-lookup-many`. Need structure? → `ast find-symbols`.
+
+**Q3: How to read?** Single file → `read-many <file>`. Multiple → `read-many <f1> <f2> ...`. Targeted line → `read-hash <file> <line>`.
+
+**Q4: How to edit?** Symbol ops → `ast <op> <file> <args>`. Content replace → `replace-hash <file> <hash> <new> [--range s:e]`. Fallback → diff.
+
+**Q5: Verify?** Always: `verify-changes <files...> [--formatter] [--linter] [--test-filter]`.
+
+## Workflows
+
+### For TypeScript/TSX/JS/Python/Go/Rust (AST route)
+1. `grep-many <pattern> <paths>` — find all references (skip if trivial)
+2. `read-many <file>` — get hash for safety
+3. `ast find-symbols <file>` — confirm exact symbol name
+4. `ast <operation> <file> <args>` — make precise edit
+5. `verify-changes <file>` — confirm correctness
+
+### For all other files (hash route)
+1. `read-many <file>` — get content hash
+2. `replace-hash <file> <hash> <new-content> [--range s:e]` — edit
+3. On `stale: true`: re-read, get fresh hash, retry step 2
+4. `verify-changes <file>` — confirm
+
+### Multi-file refactor
+1. `grep-many <pattern> src/` — find all affected files
+2. `read-many <file1> <file2> ...` — batch read all with hashes
+3. Edit each file (ast or replace-hash per file type)
+4. `verify-changes <file1> <file2> ...` — confirm all
+
+## Error handling
+
+| Error | Action |
+|-------|--------|
+| `stale: true` | Re-read file, get fresh hash, retry replace-hash |
+| Symbol not found | Run `find-symbols` to verify; check spelling |
+| Parse error | Fix syntax first, then retry AST operation |
+| Verify failure | Fix errors, re-verify |
+| Content appears N times | Provide more context to disambiguate |
+
+## Anti-patterns (avoid these)
+
+- ❌ Guess line numbers or hashes — always read first
+- ❌ Ignore `stale: true` — re-read and retry
+- ❌ Skip verify-changes — always confirm edits pass
+- ❌ Use replace-hash when AST available — use AST for symbol ops
+- ❌ Edit without understanding — use find-symbols or grep-many first
+
+## Key principles
+1. **Prefer AST** for symbol-level edits in supported languages
+2. **Prefer hash** for content changes in any file
+3. **Batch reads** — use read-many for multiple files at once
+4. **Read before write** — always get current hash
+5. **Verify after write** — always run verify-changes
+6. **Recover gracefully** — stale → re-read, not-found → check symbols

package/templates/opencode-skill.md

@@ -0,0 +1,241 @@
+---
+name: hashpilot
+description: HashPilot structured editing core for coding agents. Provides hash-anchored editing (replace-hash), syntax-aware AST editing via tree-sitter (TypeScript, TSX, JavaScript, Python, Go, Rust), batched read/search, verification bundling, and telemetry. Use when editing files precisely to reduce retries and token waste.
+---
+
+# HashPilot — Structured Editing for Coding Agents
+
+## Install HashPilot
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/bigknoxy/HashPilot/main/scripts/install.sh | bash
+```
+
+This installs the `hashpilot` CLI and registers the OpenCode skill + subagent.
+
+---
+
+HashPilot is a global, tool-agnostic structured editing system that improves coding-agent efficiency by preferring syntax-aware edits when possible, hash-anchored edits otherwise, and providing verification batching.
+
+### Preferred: use the MCP server
+
+If your host speaks MCP, register HashPilot once and call its tools directly
+instead of shelling out:
+
+```json
+{ "mcpServers": { "hashpilot": { "command": "hashpilot", "args": ["mcp", "--stdio"] } } }
+```
+
+The MCP tools mirror the CLI one-for-one (`rename_symbol`, `replace_hash`,
+`route_edit`, `verify_changes`, plus the read and search tools), and multi-line
+content with quotes or backticks rides inside JSON rather than through shell
+quoting. Per-host setup lives in `docs/INTEGRATION-MCP.md`.
+
+The CLI commands below remain fully supported and are the fallback when MCP is
+not available.
+
+## When to Use This Skill
+
+- **Editing supported languages**: Use AST commands for precise symbol-level edits (TypeScript, TSX, JavaScript, Python, Go, Rust)
+- **Editing any file with hash anchoring**: Use `replace-hash` to avoid line-counting errors
+- **Reading multiple files**: Use `read-many` to batch reads with hashes
+- **Searching across codebases**: Use `grep-many` for structured search results
+- **Verifying changes**: Use `verify-changes` to bundle formatter + linter + tests
+
+## When NOT to Use This Skill
+
+- **Creating new files**: Use direct write/edit instead (hashpilot edits existing files)
+- **Deleting files/directories**: Use raw bash (`rm`, `rmdir`)
+- **Renaming/moving files**: Use raw bash (`mv`, `git mv`)
+- **Simple single-line edits in non-critical files**: Direct edit is cheaper and just as safe
+- **Exploratory single-file reads**: Raw read has no overhead
+- **File system operations** (copy, move, delete, symlink): Use bash
+
+## Prerequisites
+
+HashPilot must be installed at `~/.agentic-tools/structured-editing/` with the CLI at `~/.agentic-tools/bin/hashpilot`.
+
+Verify installation:
+```bash
+hashpilot --version
+```
+
+If not installed, see `~/.agentic-tools/structured-editing/docs/INSTALL.md`.
+
+## Routing Strategy
+
+Always prefer the highest-confidence route:
+
+1. **AST route** — For supported languages (TypeScript, TSX, JavaScript, Python, Go, Rust) with symbol-level operations (rename, replace-body, add/remove import, insert before/after)
+2. **Hash route** — For all other edits where you have a content hash
+3. **Diff route** — Fallback for unsupported operations
+
+Check routing: `hashpilot route <file> <operation>`
+
+## Core Commands
+
+### read-many — Batch read files with hashes
+
+```bash
+hashpilot read-many <file1> [file2] ...
+```
+
+Returns the standard envelope; `data` is an array of `{ path, content, hash, lines }`.
+Store `hash` for subsequent `replace-hash` calls.
+
+**Usage pattern**: Read all relevant files at once, use hashes for editing.
+
+```bash
+# Read multiple files
+result=$(hashpilot read-many src/api.ts src/utils.ts src/config.ts)
+# Extract hash for later editing
+hash=$(echo "$result" | jq -r '.data[] | select(.path | contains("api.ts")) | .hash')
+```
+
+### read-hash — Read line with context hash
+
+```bash
+hashpilot read-hash <file> <line-number> [-c <context-lines>]
+```
+
+Returns `lineHash`, `contextHash`, `contextBefore`, `contextAfter`. Use `contextHash` for anchoring edits to specific line ranges.
+
+### grep-many — Search across paths
+
+```bash
+hashpilot grep-many <pattern> <paths...> [-i] [--file-pattern <glob>] [--max-results <n>]
+```
+
+### symbol-lookup-many — Find symbol definitions
+
+```bash
+hashpilot symbol-lookup-many <paths...> --names name1,name2
+```
+
+### replace-hash — Hash-anchored content replacement
+
+```bash
+hashpilot replace-hash <file> <old-hash> <new-content> [--range start:end] [--dry-run]
+```
+
+**Critical**: If result shows `"stale": true`, the file changed since the hash was computed. Re-read the file and retry with the new hash.
+
+**Range format**: `--range 5:10` means lines 5 through 10 (1-indexed, end exclusive).
+
+**File input**: Use `@filepath` to read new content from a file instead of inline.
+
+## AST Commands (TypeScript, TSX, JavaScript, Python, Go, Rust)
+
+### find-symbols — List all symbols
+
+```bash
+hashpilot ast find-symbols <file>
+```
+
+Returns array of `{name, kind, startRow, endRow, startCol, endCol}`.
+
+### rename-symbol — Rename all references
+
+```bash
+hashpilot ast rename-symbol <file> <old-name> <new-name> [--dry-run]
+```
+
+### replace-body — Replace function/method body
+
+```bash
+hashpilot ast replace-body <file> <symbol-name> <new-body> [--dry-run]
+```
+
+Body can be `@filepath` to read from a file.
+
+### add-import — Add import statement
+
+```bash
+hashpilot ast add-import <file> '<import-spec>' [--dry-run]
+```
+
+Examples:
+- `hashpilot ast add-import src/app.ts '{ Router } from express'`
+- `hashpilot ast add-import src/app.ts '* as React from react'`
+
+### remove-import — Remove import line
+
+```bash
+hashpilot ast remove-import <file> '<import-spec>' [--dry-run]
+```
+
+### insert-before / insert-after — Insert content relative to a symbol
+
+```bash
+hashpilot ast insert-before <file> <symbol-name> <content> [--dry-run]
+hashpilot ast insert-after <file> <symbol-name> <content> [--dry-run]
+```
+
+## verify-changes — Bundle formatter + linter + tests
+
+```bash
+hashpilot verify-changes <files...> [--formatter <cmd>] [--linter <cmd>] [--test-filter <pattern>]
+```
+
+Returns `{overall: "pass"|"fail"|"partial", formatter, linter, tests, fileHashes}`.
+
+## Telemetry
+
+```bash
+hashpilot telemetry show [-n <limit>]
+hashpilot telemetry summary
+hashpilot telemetry clear
+```
+
+## Workflow Patterns
+
+### Pattern 1: TypeScript symbol rename
+
+```bash
+# 1. Find the symbol
+hashpilot ast find-symbols src/api.ts
+# 2. Rename
+hashpilot ast rename-symbol src/api.ts oldName newName
+# 3. Verify
+hashpilot verify-changes src/api.ts --formatter prettier --linter eslint
+```
+
+### Pattern 2: Hash-anchored edit (any file)
+
+```bash
+# 1. Read file with hash
+data=$(hashpilot read-many config.yaml)
+hash=$(echo "$data" | jq -r '.[0].hash')
+# 2. Edit with hash anchor
+hashpilot replace-hash config.yaml "$hash" "new: content"
+# 3. On stale hash: re-read and retry
+```
+
+### Pattern 3: Batch read + selective edit
+
+```bash
+# 1. Batch read
+hashpilot read-many src/a.ts src/b.ts src/c.ts
+# 2. Extract hash for target file
+# 3. Replace targeted range
+hashpilot replace-hash src/b.ts "$hash" "replacement content" --range 10:15
+```
+
+## Error Recovery
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| `stale: true` | File changed since hash computed | Re-read file, get new hash, retry |
+| `success: false` | Symbol not found, parse error, etc. | Check file content, verify symbol name |
+| Parse error | Invalid source code | Fix syntax errors first |
+| `error` field | File not found, permissions | Check file path and permissions |
+
+## Telemetry Event Schema
+
+Every operation logs:
+- `operation`: Command name
+- `route`: `ast`, `hash`, `diff`, `read`, `grep`, `verify`
+- `success`: Boolean
+- `fallback_reason`: Why a lower route was chosen
+- `elapsed_ms`: Duration
+- `file`, `files_count`, `lines_read`: Scope info