fallow 3.18.0 → 3.19.0

package/README.md

@@ -89,7 +89,7 @@ The bundled `fallow-mcp` server lives in `node_modules/.bin/` when installed as
 }
 ```
 
-Swap `npx` for `pnpm exec` or `yarn` to match your package manager; a globally installed `fallow-mcp` works as `"command": "fallow-mcp"` directly. See the [MCP integration guide](https://docs.fallow.tools/integrations/mcp).
+Swap `npx` for `pnpm exec` or `yarn` to match your package manager; a globally installed `fallow-mcp` works as `"command": "fallow-mcp"` directly. See the [MCP integration guide](https://docs.fallow.tools/integrations/mcp). `npx fallow agent install` writes this registration for you, together with the skill, an `AGENTS.md` task map, and the commit/push gate, for every harness it detects (Claude Code, Codex, Cursor); `--dry-run` shows the plan first.
 
 The package also ships a version-matched agent skill under `skills/fallow`, and `fallow/capabilities.json` mirrors `fallow schema` for tools that need CLI and issue-surface metadata without spawning the binary. TanStack Intent discovers both from `node_modules`:
 

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -906,6 +906,36 @@
       "description": "Inspect the optional TypeScript semantic companion",
       "flags": []
     },
+    {
+      "name": "similar-code",
+      "description": "Find semantically similar functions with a pinned local model (opt-in)",
+      "flags": [
+        {
+          "name": "--threshold",
+          "type": "string",
+          "required": false,
+          "description": "Minimum cosine similarity retained as an unverified candidate"
+        },
+        {
+          "name": "--min-lines",
+          "type": "string",
+          "required": false,
+          "description": "Minimum source lines per extracted function"
+        },
+        {
+          "name": "--top",
+          "type": "string",
+          "required": false,
+          "description": "Cap displayed candidates after bounded full-corpus comparison"
+        },
+        {
+          "name": "--file",
+          "type": "string",
+          "required": false,
+          "description": "Report pairs touching one of these project-relative files"
+        }
+      ]
+    },
     {
       "name": "inspect",
       "description": "Inspect one file or exported symbol as a bundled evidence query",
@@ -1075,6 +1105,11 @@
       "description": "Install or remove fallow-managed Git and agent hooks",
       "flags": []
     },
+    {
+      "name": "agent",
+      "description": "Wire fallow into the coding-agent harnesses used by this project in one pass (AGENTS.md task map, skill, MCP server, commit/push gate), or show and remove what was installed. `fallow init --agents` and `fallow hooks install --target agent` remain the single-piece commands underneath",
+      "flags": []
+    },
     {
       "name": "ci",
       "description": "CI helpers for PR/MR feedback envelopes",
@@ -6475,7 +6510,7 @@
   },
   "mcp_tools": {
     "server": "fallow-mcp",
-    "note": "key_params is a curated subset; the live MCP input schemas (list_tools) are authoritative for the full parameter list. cli_command is the nearest CLI fallback, not a full MCP input-schema projection",
+    "note": "key_params is a curated subset; the live MCP input schemas (tools/list) are authoritative for the full parameter list. cli_command is the nearest CLI fallback, not a full MCP input-schema projection",
     "tools": [
       {
         "name": "code_execute",
@@ -6537,6 +6572,35 @@
         "license_note": null,
         "read_only": true
       },
+      {
+        "name": "find_similar_code",
+        "kind": "analysis",
+        "description": "Find unverified semantically similar function candidates with the exact pinned local model",
+        "cli_command": "fallow similar-code --format json --quiet",
+        "key_params": [
+          "threshold",
+          "min_lines",
+          "top",
+          "changed_since",
+          "paths"
+        ],
+        "license": "free",
+        "license_note": null,
+        "read_only": true
+      },
+      {
+        "name": "inspect_similar_code",
+        "kind": "trace",
+        "description": "Inspect one exact candidate snapshot without rerunning retrieval or global ranking",
+        "cli_command": "fallow similar-code inspect <candidate-id> --candidates <report.json> --format json --quiet",
+        "key_params": [
+          "candidate_id",
+          "snapshot"
+        ],
+        "license": "free",
+        "license_note": null,
+        "read_only": true
+      },
       {
         "name": "inspect_target",
         "kind": "analysis",
@@ -6672,7 +6736,7 @@
       {
         "name": "get_token_blast_radius",
         "kind": "analysis",
-        "description": "Design-token blast radius for Tailwind v4 @theme tokens AND CSS-in-JS defineVars/createTheme-family token definitions: per token, a consumer_count (static lower bound) and a capped located consumers[] sample tagged theme-var/css-var/utility/apply (Tailwind) or js-member (CSS-in-JS cross-module member access); descriptive context for sizing a token change, never a deletion gate",
+        "description": "Design-token blast radius for Tailwind v4 @theme tokens AND CSS-in-JS defineVars/createTheme-family token definitions: per token, a consumer_count (static lower bound) and a capped located consumers[] sample tagged theme-var/css-var/utility/apply (Tailwind), js-member (CSS-in-JS member access), or js-call (StyleX theme-group and Panda token calls); descriptive context for sizing a token change, never a deletion gate",
         "cli_command": "fallow health --css --format json --quiet",
         "key_params": [],
         "license": "free",
@@ -6934,8 +6998,78 @@
       }
     ]
   },
+  "mcp_resources": {
+    "server": "fallow-mcp",
+    "note": "Read-only reference material served in-process by fallow-mcp; every JSON payload carries fallow_version. Rows with template: true are RFC 6570 URI templates listed under resources/templates/list; the catalogue is static, so the server declares neither subscribe nor listChanged",
+    "resources": [
+      {
+        "uri": "fallow://tools",
+        "name": "tools",
+        "title": "Tool manifest",
+        "description": "MCP tool manifest: name, kind, one-line description, nearest CLI fallback, key params, license, and read-only flag for every tool",
+        "mime_type": "application/json",
+        "template": false
+      },
+      {
+        "uri": "fallow://issue-types",
+        "name": "issue-types",
+        "title": "Issue type registry",
+        "description": "Every issue type with its command, category, config key, zero-config default severity, opt-in flag, fixable flag, docs URL, and explain resource URI",
+        "mime_type": "application/json",
+        "template": false
+      },
+      {
+        "uri": "fallow://explain",
+        "name": "explain",
+        "title": "Explain index",
+        "description": "Index of every explainable issue type with its one-line summary and the fallow://explain/{issue_type} URI to read",
+        "mime_type": "application/json",
+        "template": false
+      },
+      {
+        "uri": "fallow://task-matrix",
+        "name": "task-matrix",
+        "title": "Agent task matrix",
+        "description": "Agent task-to-command matrix: which read-only fallow command to run before deleting, refactoring, committing, or scoping work",
+        "mime_type": "application/json",
+        "template": false
+      },
+      {
+        "uri": "fallow://schema/config",
+        "name": "schema-config",
+        "title": "Config JSON Schema",
+        "description": "JSON Schema of the fallow config file (same document as fallow config-schema)",
+        "mime_type": "application/json",
+        "template": false
+      },
+      {
+        "uri": "fallow://schema/plugin",
+        "name": "schema-plugin",
+        "title": "Plugin JSON Schema",
+        "description": "JSON Schema of a user-authored external plugin (same document as fallow plugin-schema)",
+        "mime_type": "application/json",
+        "template": false
+      },
+      {
+        "uri": "fallow://schema/rule-pack",
+        "name": "schema-rule-pack",
+        "title": "Rule pack JSON Schema",
+        "description": "JSON Schema of a declarative rule pack (same document as fallow rule-pack-schema)",
+        "mime_type": "application/json",
+        "template": false
+      },
+      {
+        "uri": "fallow://explain/{issue_type}",
+        "name": "explain-issue-type",
+        "title": "Explain one issue type",
+        "description": "Explain document for one issue type (same payload as fallow explain <issue-type> --format json): name, summary, rationale, example, fix guidance, docs URL. issue_type accepts the bare id (unused-export), the namespaced id (fallow/unused-export), or the CLI filter spelling; see fallow://explain for the index",
+        "mime_type": "application/json",
+        "template": true
+      }
+    ]
+  },
   "plugins": {
-    "count": 123,
+    "count": 124,
     "note": "Built-in framework plugins, auto-activated when their enabler dependency is present; run fallow list --plugins for the set active in a specific project",
     "names": [
       "nextjs",
@@ -7043,6 +7177,7 @@
       "lint-staged",
       "lefthook",
       "simple-git-hooks",
+      "size-limit",
       "svgo",
       "svgr",
       "graphql-codegen",

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "fallow",
-  "version": "3.18.0",
+  "version": "3.19.0",
+  "mcpName": "io.github.fallow-rs/fallow",
   "description": "Codebase intelligence for TypeScript and JavaScript. Free static analysis of code and styles, optional paid runtime intelligence (Fallow Runtime). Quality, risk, architecture, dependencies, duplication, and design-system drift for humans, CI, and the agents writing your code. Zero-config framework support.",
   "license": "MIT",
   "repository": {
@@ -87,14 +88,14 @@
     "@tanstack/intent": "0.3.6"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.18.0",
-    "@fallow-cli/darwin-x64": "3.18.0",
-    "@fallow-cli/linux-x64-gnu": "3.18.0",
-    "@fallow-cli/linux-arm64-gnu": "3.18.0",
-    "@fallow-cli/linux-x64-musl": "3.18.0",
-    "@fallow-cli/linux-arm64-musl": "3.18.0",
-    "@fallow-cli/win32-arm64-msvc": "3.18.0",
-    "@fallow-cli/win32-x64-msvc": "3.18.0",
-    "fallow-type-aware": "3.18.0"
+    "@fallow-cli/darwin-arm64": "3.19.0",
+    "@fallow-cli/darwin-x64": "3.19.0",
+    "@fallow-cli/linux-x64-gnu": "3.19.0",
+    "@fallow-cli/linux-arm64-gnu": "3.19.0",
+    "@fallow-cli/linux-x64-musl": "3.19.0",
+    "@fallow-cli/linux-arm64-musl": "3.19.0",
+    "@fallow-cli/win32-arm64-msvc": "3.19.0",
+    "@fallow-cli/win32-x64-msvc": "3.19.0",
+    "fallow-type-aware": "3.19.0"
   }
 }

package/schema.json

@@ -143,6 +143,15 @@
         "minCorpusSizeForTokenCache": 5000
       }
     },
+    "similarCode": {
+      "description": "Configures the explicit local `similar-code` candidate workflow:\n`threshold` (0.80, model-specific cosine floor), `minLines` (3), and\nadditional `ignore` globs. Provider identity, setup, executables,\nendpoints, credentials, and consent cannot be set by project config.",
+      "$ref": "#/$defs/SimilarCodeConfig",
+      "default": {
+        "threshold": 0.8,
+        "minLines": 3,
+        "ignore": []
+      }
+    },
     "health": {
       "description": "Sets complexity and health thresholds for `fallow health` (also applied in combined `fallow` and `fallow audit`): `maxCyclomatic` (20), `maxCognitive` (15), `maxCrap` (30.0, findings at or above this are reported), `crapRefactorBand` (5, cyclomatic band below `maxCyclomatic` where a secondary refactor action is added), `maxUnitSize` (max function lines before a large-function finding, 60), `coverage`/`coverageRoot` (Istanbul coverage path and path-prefix strip for accurate CRAP), `ignore` globs (remove files from findings AND the health score), `thresholdOverrides` (per-file/per-function ceilings via `files`/`functions`/`maxCyclomatic`/`maxCognitive`/`maxCrap`/`maxUnitSize`/`reason`), `ownership` (`botPatterns` and `emailMode` for `--ownership`), and `suggestInlineSuppression` (true, emit `suppress-line` action hints in JSON). Raise thresholds to relax which functions are flagged, wire `coverage` for real CRAP scores, or exempt generated/test files via `ignore` (drops them from the score too) or `thresholdOverrides` (keeps them visible under a higher ceiling). The four `max*` thresholds govern findings only and never move `health_score`: its penalties use fixed calibration so grades stay comparable across projects, and `ignore` is the lever that removes files from the score.",
       "$ref": "#/$defs/HealthConfig",
@@ -986,6 +995,36 @@
         }
       }
     },
+    "SimilarCodeConfig": {
+      "description": "Project-owned tuning for the explicit `fallow similar-code` workflow.\n\nProvider identity, executable discovery, model setup, credentials, and\nconsent are intentionally absent. Project configuration cannot select code\ndestinations or authorize model downloads.",
+      "type": "object",
+      "properties": {
+        "threshold": {
+          "description": "Minimum model-specific cosine similarity retained as an unverified\ncandidate. It is not a probability or refactor-safety verdict.",
+          "type": "number",
+          "format": "double",
+          "minimum": 0.0,
+          "maximum": 1.0,
+          "default": 0.8
+        },
+        "minLines": {
+          "description": "Minimum source line count for a function to enter model inference.",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 1,
+          "default": 3
+        },
+        "ignore": {
+          "description": "Additional project-root-relative globs excluded only from similar-code\nextraction. Global `ignorePatterns` remain authoritative first.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        }
+      },
+      "additionalProperties": false
+    },
     "HealthConfig": {
       "description": "Configuration for complexity health metrics (`fallow health`).",
       "type": "object",

package/scripts/lazy-verify.js

@@ -29,7 +29,7 @@ const { verifyInstalledSync, SKIP_ENV } = require("./verify-binary");
 // Bumped to 2 when SHA-256 + platformPkgDir binding landed (closes the
 // cross-install reuse gap in the shared $XDG fallback cache). v1 sentinels
 // without these fields are invalidated automatically.
-const SENTINEL_SCHEMA_VERSION = 2;
+const SENTINEL_SCHEMA_VERSION = 3;
 const VERIFY_LOG_ENV = "FALLOW_VERIFY_LOG";
 
 // One-shot warning state: each warning class fires once per process,
@@ -66,11 +66,10 @@ function emitVerifyLog(env, payload) {
 }
 
 function binaryTargetsForPlatform(platform) {
-  // Platform packages ship one binary: the multicall `fallow`. The bundled
-  // lsp/mcp launchers spawn `fallow lsp-server` / `fallow mcp-server`, so there
-  // is only one binary to sentinel-track and verify.
+  // Track every executable the multicall CLI may launch without another
+  // wrapper verification boundary.
   const ext = platform === "win32" ? ".exe" : "";
-  return [`fallow${ext}`];
+  return [`fallow${ext}`, `fallow-similar-code${ext}`];
 }
 
 function statMtimeMs(absPath) {

package/scripts/lazy-verify.test.js

@@ -31,8 +31,8 @@ function packageNameForPlatform(platform) {
 }
 
 function binaryNames(platform) {
-  // Platform packages ship a single multicall `fallow` binary.
-  return [platform === "win32" ? "fallow.exe" : "fallow"];
+  const ext = platform === "win32" ? ".exe" : "";
+  return [`fallow${ext}`, `fallow-similar-code${ext}`];
 }
 
 function computeDigestsForDir(dir, platform) {
@@ -123,7 +123,7 @@ test("ensureVerified verifies on cache miss and writes the sentinel", (t) => {
   assert.equal(sentinel.schemaVersion, SENTINEL_SCHEMA_VERSION);
   assert.equal(sentinel.packageVersion, "2.81.0");
   assert.equal(sentinel.packageName, "@fallow-cli/test-platform");
-  assert.equal(Object.keys(sentinel.binaries).length, 1);
+  assert.equal(Object.keys(sentinel.binaries).length, 2);
 });
 
 test("ensureVerified verifies and caches a win32 executable on any host", (t) => {
@@ -139,7 +139,7 @@ test("ensureVerified verifies and caches a win32 executable on any host", (t) =>
   assert.equal(verified.ok, true);
   assert.equal(verified.cached, false);
   const sentinel = JSON.parse(fs.readFileSync(verified.sentinelPath, "utf8"));
-  assert.deepEqual(Object.keys(sentinel.binaries), ["fallow.exe"]);
+  assert.deepEqual(Object.keys(sentinel.binaries), ["fallow.exe", "fallow-similar-code.exe"]);
 
   const cached = ensureVerified({
     ...input,
@@ -194,7 +194,11 @@ test("ensureVerified invalidates sentinel on mtime drift", (t) => {
   );
   assert.equal(result.ok, true);
   assert.equal(result.cached, false);
-  assert.equal(verifyCallCount, 1, "verify should rerun for the single binary");
+  assert.equal(
+    verifyCallCount,
+    binaryNames(DEFAULT_PLATFORM).length,
+    "verify should rerun for every shipped binary",
+  );
 });
 
 test("ensureVerified invalidates sentinel on packageVersion drift", (t) => {

package/scripts/verify-binary.js

@@ -293,15 +293,16 @@ function binaryTargetsForPlatform(platformId) {
   // and tests can synthesize a Windows verify without running on Windows.
   const isWindows = typeof platformId === "string" && platformId.startsWith("win32");
   const ext = isWindows ? ".exe" : "";
-  // Platform packages ship ONE binary now: the multicall `fallow` (CLI + LSP +
-  // MCP in one engine). The bundled `fallow-lsp` / `fallow-mcp` launchers live
-  // in the wrapper and spawn `fallow lsp-server` / `fallow mcp-server`. The
-  // authoritative digest is the `fallowDigests.fallow` field the release
-  // pipeline embeds for every bundled package; the `asset` below is only the
-  // legacy GitHub-release fallback for pre-embedded-digest packages, which
-  // never shipped this bundled binary, so it is inert for bundled installs and
-  // fails closed (digest-mismatch) in the impossible case it is ever reached.
-  return [{ binary: `fallow${ext}`, asset: `fallow-${platformId}${ext}` }];
+  // The platform package ships the multicall CLI plus the local-only
+  // similar-code provider. Both are signed and digest-pinned. Verifying them
+  // together keeps the Rust sibling lookup free of project or PATH overrides.
+  return [
+    { binary: `fallow${ext}`, asset: `fallow-${platformId}${ext}` },
+    {
+      binary: `fallow-similar-code${ext}`,
+      asset: `fallow-similar-code-${platformId}${ext}`,
+    },
+  ];
 }
 
 function isSkipRequested() {

package/scripts/verify-binary.test.js

@@ -253,7 +253,7 @@ function makePlatformDir(privateKey, options) {
   const opts = options || {};
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-vbtest-"));
   const ext = extForPlatformId(opts.platformId);
-  for (const base of ["fallow"]) {
+  for (const base of ["fallow", "fallow-similar-code"]) {
     const binaryPath = path.join(dir, `${base}${ext}`);
     const content = Buffer.from(`mock ${base} contents`);
     fs.writeFileSync(binaryPath, content);
@@ -395,7 +395,7 @@ test("verifyInstalled resolves a global npm install from the fallow package dire
   );
 
   const ext = process.platform === "win32" ? ".exe" : "";
-  for (const base of ["fallow"]) {
+  for (const base of ["fallow", "fallow-similar-code"]) {
     const binaryPath = path.join(platformDir, `${base}${ext}`);
     const content = Buffer.from(`global install ${base}`);
     fs.writeFileSync(binaryPath, content);
@@ -509,7 +509,7 @@ test("verifyInstalled honors FALLOW_SKIP_BINARY_VERIFY", async (t) => {
 function computeDigestsForDir(dir, platformId) {
   const ext = extForPlatformId(platformId);
   const out = {};
-  for (const base of ["fallow"]) {
+  for (const base of ["fallow", "fallow-similar-code"]) {
     const fileName = `${base}${ext}`;
     const full = path.join(dir, fileName);
     out[fileName] =
@@ -595,7 +595,7 @@ test("verifyInstalled falls back to the provider when the embedded digest is mis
     },
   });
   assert.equal(result.ok, true);
-  assert.equal(providerCalls, 1);
+  assert.equal(providerCalls, 2);
 });
 
 test("verifyInstalled falls back to the provider when fallowDigests is partial / malformed", async (t) => {
@@ -619,8 +619,8 @@ test("verifyInstalled falls back to the provider when fallowDigests is partial /
     },
   });
   assert.equal(result.ok, true);
-  // One call for the single shipped binary because its entry fails to normalize.
-  assert.equal(providerCalls, 1);
+  // Both shipped binaries fall back because their embedded entries are absent or malformed.
+  assert.equal(providerCalls, 2);
 });
 
 test("verifyInstalled returns digest-mismatch when the embedded digest disagrees with the binary", async (t) => {

package/skills/fallow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fallow
-description: Codebase intelligence for TypeScript and JavaScript. Static analysis of code and styles reports changed-code risk, cleanup opportunities, duplication, circular dependencies, complexity hotspots, architecture boundaries, design-system drift, feature flags, and opt-in security candidates. Runtime coverage can merge production execution data for hot-path review, cold-path deletion confidence, and stale-flag evidence. Broad framework plugin coverage, zero configuration, sub-second static analysis. Use when asked to audit PR risk, find unused code or dependencies, detect duplicates, check styling consistency, inspect architecture boundaries, merge runtime coverage, auto-fix supported issues, or run fallow.
+description: Codebase intelligence for TypeScript and JavaScript. Static analysis reports changed-code risk, cleanup opportunities, duplication, circular dependencies, complexity hotspots, architecture boundaries, design-system drift, feature flags, and opt-in security candidates. Optional local similar-code discovery finds functions that may implement the same intent despite different syntax. Runtime coverage can merge production execution data. Use when asked to audit PR risk, find unused code or dependencies, compare semantically similar functions, detect duplicates, inspect architecture boundaries, merge runtime coverage, auto-fix supported issues, or run fallow.
 license: MIT
 ---
 
@@ -11,6 +11,7 @@ Codebase intelligence for TypeScript and JavaScript. The static layer analyzes c
 ## When to Use
 - Find cleanup opportunities: unused files, exports, types, members, dependencies, or stale flags.
 - Detect code duplication, circular dependencies, architecture boundary issues, and complexity hotspots.
+- Find functions that may implement the same intent despite different names, syntax, or control flow (`fallow similar-code`).
 - Check styling consistency, CSS dead surface, and design-token drift.
 - Audit changed code before a commit, PR, release, or refactor.
 - Set up CI quality gates, duplication thresholds, and regression baselines.
@@ -31,7 +32,6 @@ Codebase intelligence for TypeScript and JavaScript. The static layer analyzes c
 - Projects that are not JavaScript or TypeScript
 
 ## Prerequisites
-
 Fallow must be installed. If not available, install it:
 
 ```bash
@@ -41,7 +41,6 @@ cargo install fallow-cli   # build from source
 ```
 
 ## Agent Rules
-
 1. **Always use `--format json --quiet`** for machine-readable output and parse stdout as JSON. Compact JSON is the default; never depend on whitespace or add `--pretty` in agent pipelines. Keep stderr separate so diagnostics remain visible; never merge it into the JSON stream with `2>&1`.
 2. **Preserve and interpret the exit status.** Codes 0 and 1 are successful analysis outcomes: 0 is clean and 1 means findings. Treat every other code according to `fallow schema.exit_codes`. Do not force a successful status, because that hides validation, license, setup, network, and security-gate outcomes.
 3. **Use `--explain`** to include a `_meta` object in JSON output with metric definitions, ranges, and interpretation hints. In human format, `--explain` prints a `Description:` line under each section header.
@@ -55,6 +54,8 @@ cargo install fallow-cli   # build from source
 11. **Never enable telemetry on the user's behalf**. Fallow's product telemetry is opt-in and off by default; only the user may run `fallow telemetry enable`. You MAY set `FALLOW_AGENT_SOURCE=<allowlisted-value>` (for example `claude_code`, `codex`, `cursor`, `windsurf`, `gemini`, `cline`) so that, IF the user has already enabled telemetry, your integration is correctly attributed. Setting `FALLOW_AGENT_SOURCE` never enables telemetry by itself and uploads no codebase content.
 12. **Use type-aware analysis only for Fallow-owned project questions**. Reach for `--type-aware` to prove exact symbol use, preserve TypeScript class contracts, guard class-member cleanup, find cross-file private type leaks, suggest targeted tests, or inspect public-signature coupling. Keep `tsc --noEmit` responsible for compiler correctness and Oxlint responsible for local typed lint rules. Treat partial or unavailable semantic results as retained findings, never as deletion proof. Unknown external consumers of a published library remain outside checker-visible evidence, so preserve declared public API unless every relevant consumer project is explicitly in scope.
 13. **Use `fallow impact statusline` only for a user-facing status surface**. It intentionally emits one plain-text, path-free line and ignores `--format`. It starts no analysis, never enables Impact, and compares only whole-project scans. Do not parse this line as JSON.
+14. **Treat similar-code output as discovery only**. Never describe its score as a probability, finding, proof of equivalent behavior, or safe-refactor decision. Agents must not authorize setup. Inspect a candidate before judging it: save discovery as `similar-code.json`, inspect with `--candidates similar-code.json`, and pass the unchanged file to `fallow similar-code review`. Over MCP use `find_similar_code` with `paths:` and `inspect_similar_code` with a typed `snapshot`; it fails closed on stale source. Keep `candidate_worthy`, `behaviorally_equivalent`, and `refactor_safe` separate, use `needs-human-review`, and abstain when evidence is incomplete. Only `completion.status: "complete"` makes an empty result conclusive. Follow [the complete workflow to compare semantically similar functions](references/similar-code.md).
+
 ## Onboarding And Insight
 Offer setup only after a human-requested analysis shows findings and all signals match: `fallow config --path` exits 3, not CI, not a pipeline format, `fallow impact --format json --quiet` has `onboarding_declined: false`, and no offer happened this session. Ask after showing value. Choices: guard commits and PRs, baseline the existing backlog and clean by category, add AGENTS.md guidance, or keep as-is. On decline, run `fallow init --decline --quiet` and stay silent for this project. Mutate only after consent. For guards, inspect `fallow hooks status --format json --quiet`, then use `fallow hooks install --target agent` and `fallow hooks install --target git`; for large backlogs, pair the gate with `--save-baseline` / new-only guidance. Offer `fallow impact enable` as local-only value tracking, never as telemetry; also offer it once on already-configured projects when `fallow impact status --format json` has `enabled: false` and `explicit_decision: false`, and record a no with `fallow impact disable --quiet`. Surface value on clear events: if the agent gate blocked a commit or push and a later retry succeeded, mention what was contained; when `next_steps` carries id `impact-report`, run its command and relay the non-zero numbers to the user in one line. On request, summarize non-zero Impact counts. Ask about telemetry only after such a win, only if `fallow telemetry status --format json` has `explicit_decision: false`, and never run `fallow telemetry enable`.
 ## Task Cheat Sheet
@@ -79,7 +80,6 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 <!-- generated:task-matrix:end -->
 
 ## Commands
-
 <!-- generated:commands:start -->
 | Command | Purpose | Key Flags |
 |---|---|---|
@@ -87,11 +87,13 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 | `dead-code` | Dead code analysis (`check` is an alias) | `--unused-exports`, `--changed-since`, `--changed-workspaces`, `--production`, `--file`, `--include-entry-exports`, `--stale-suppressions`, `--ci`, `--group-by`, `--summary`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline` |
 | `watch` | Watch for changes and re-run analysis | `--no-clear` |
 | `type-aware` | Inspect the optional TypeScript semantic companion |  |
+| `similar-code` | Find semantically similar functions with a pinned local model (opt-in) | `--threshold`, `--min-lines`, `--top`, `--file` |
 | `inspect` | Compose one evidence bundle for a file or exported symbol | `--file <path>`, `--symbol <file>:<export>` |
 | `trace` | Trace a symbol's call chain (best-effort, syntactic; OFF the ranked path) | `symbol`, `--callers`, `--callees`, `--depth` |
 | `fix` | Auto-remove unused exports/deps | `--dry-run`, `--yes` (required in non-TTY) |
 | `init` | Generate config file, AGENTS.md agent guide, or pre-commit hook | `--toml`, `--agents`, `--hooks`, `--branch` |
 | `hooks` | Inspect, install, or remove fallow-managed Git and agent hooks | `status`, `install --target git`, `install --target agent`, `uninstall --target git`, `uninstall --target agent` |
+| `agent` | Wire fallow into Claude Code, Codex, or Cursor in one pass: AGENTS.md task map, skill, MCP server, commit/push gate; `status` and `uninstall` cover the same surfaces | `install --harness auto\|claude\|codex\|cursor`, `install --dry-run`, `install --approve`, `install --without <guide\|skill\|mcp\|hooks>`, `status`, `uninstall` |
 | `ci` | CI helpers for PR/MR feedback envelopes |  |
 | `ci reconcile-review` | Resolve stale review threads on a PR/MR by joining a typed review envelope (`--format review-github` / `review-gitlab`) against the provider's existing comments + threads. Posts an idempotent "Resolved in `<sha>`" follow-up per stale fingerprint, marker keyed on (fingerprint, short-sha) so re-runs on the same commit don't duplicate. Provider mutations are fail-fast; JSON can include `apply_hint`, `failed_fingerprints`, and `unapplied_fingerprints` when `apply_errors` is non-empty. | `--provider`, `--pr` (GH) / `--mr` (GL), `--repo` / `--project-id`, `--api-url`, `--envelope`, `--dry-run` |
 | `config-schema` | Print the JSON Schema for fallow configuration files |  |
@@ -122,14 +124,13 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 | `telemetry` | Manage opt-in, off-by-default product telemetry (never collects code, paths, or names). Agents must not enable it; only the user may | `status`, `enable`, `disable`, `inspect --example` |
 | `coverage` | Runtime coverage setup, focused analysis, and cloud inventory workflow helper | `setup`, `setup --yes`, `setup --non-interactive`, `analyze --runtime-coverage <path>`, `analyze --cloud --repo owner/repo`, `upload-inventory` |
 | `coverage upload-source-maps` | Upload build source maps from CI so bundled runtime coverage resolves to original source paths. Retries 429 `Retry-After` and transient gateway failures. Use `FALLOW_CA_BUNDLE` for complete custom PEM trust bundles. | `--dir dist`, `--git-sha <sha>`, `--repo <name>`, `--strip-path=false`, `--dry-run` |
-| `setup-hooks` | Install or remove a Claude Code PreToolUse hook that gates `git commit` / `git push` on `fallow audit`, so the agent cleans findings before the command runs | `--agent`, `--dry-run`, `--force`, `--user`, `--gitignore-claude`, `--uninstall` |
+| `setup-hooks` | Deprecated (removed in the next major): use `agent install` or `hooks install --target agent`; still installs the Claude Code PreToolUse gate with a stderr warning | `--agent`, `--dry-run`, `--force`, `--user`, `--gitignore-claude`, `--uninstall` |
 | `viz` | Render the codebase as a self-contained interactive HTML map (treemap + import graph, four lenses: dead code, duplication, boundaries, complexity, with click-through detail panels), or emit the import graph as text. Read-only. | `--out <path>`, `--no-open`, `--viz-format html\|dot\|mermaid`, `--root`, `--config`, `--production`, `--no-cache` |
 
 Run `fallow <command> --help` for the full flag list per command (see also references/cli-reference.md).
 <!-- generated:commands:end -->
 
 ## Issue Types
-
 <!-- generated:issue-types:start -->
 | Type | Filter flag | Fixable | Suppress comment | Description |
 |---|---|---|---|---|
@@ -204,13 +205,16 @@ Runtime-coverage verdicts and the full security sink catalogue are listed by `fa
 
 Fallow ships an MCP server (`fallow-mcp`) that exposes these same analyses as agent tools. When the server is connected, its tools are already in your context with typed params and structured JSON returns, and each maps to a CLI fallback command. Prefer them when you want JSON without shelling out, or `code_execute` (Code Mode) to compose several read-only analyses in one sandboxed snippet (no single-call CLI equivalent). Otherwise use the CLI.
 
-Full tool catalogue, key params, runtime source-map confidence tiers, shared timeouts, and the `next_steps` dispatch mapping: **[references/mcp.md](references/mcp.md)**.
+The server also serves read-only reference resources (no subprocess, no analysis run, cacheable by URI; your client reads them through its own resource tool): `fallow://tools`, `fallow://issue-types`, `fallow://explain/{issue_type}`, `fallow://task-matrix`, and the config, plugin, and rule-pack JSON Schemas. Every payload is JSON and carries `fallow_version`.
+
+Full tool catalogue, resource catalogue, key params, runtime source-map confidence tiers, shared timeouts, and the `next_steps` dispatch mapping: **[references/mcp.md](references/mcp.md)**.
 
 ## References
 - [CLI Reference](references/cli-reference.md): complete command and flag specifications, plus configuration field details
-- [MCP Tools](references/mcp.md): MCP server tool catalogue, CLI fallbacks, params, and agent dispatch guidance
+- [MCP Tools](references/mcp.md): MCP server tool and resource catalogues, CLI fallbacks, params, and agent dispatch guidance
 - [Gotchas](references/gotchas.md): common pitfalls, edge cases, and correct usage patterns
 - [Patterns](references/patterns.md): workflow recipes for CI, monorepos, migration, and incremental adoption
+- [Similar Code](references/similar-code.md): snapshot-stable discovery, inspection, and verdict workflow
 - [Node Bindings](references/node-bindings.md): embed the analysis engine in a Node.js process via NAPI
 
 ## Common Workflows