fallow 3.31.0 → 3.32.0

package/skills/fallow/references/mcp.md

@@ -14,7 +14,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `code_execute` | composition | free | - | `code`, `timeout_ms`, `max_output_bytes` | Bounded read-only Code Mode for composing multiple fallow analysis calls in one JavaScript snippet. The snippet receives `{ fallow, root }`, returns JSON-serializable data, and can call read-only helpers such as `fallow.projectInfo`, `fallow.audit`, `fallow.checkHealth`, and `fallow.run(tool, params)` for the same allowlist. `fallow.all(requests)` fans out independent calls in one go: pass `[{ tool, params }, ...]` and get back a positionally aligned array of `{ ok: true, value }` or `{ ok: false, error }`, so one failing element never hides the rest. Host calls are memoized for the duration of one snippet, so repeating the same tool with the same params (key order does not matter) is served from cache, spends no `max_host_calls` slot and no output budget, and is reported in `calls[]` with `cache_hit: true`; a call refused before dispatch (unknown tool, malformed params) spends no slot either, and `limits.max_rejected_host_calls` bounds how many of those the response records. Similar-code is excluded because Code Mode is capped at 30 seconds; use standalone `find_similar_code` and `inspect_similar_code`, which have dedicated 15-minute timeouts. Mutating fix tools are not exposed, and a host call that passes `save_baseline`, `save_regression_baseline` or `save_snapshot` is refused with the name of the standalone tool to call. The sandbox has no filesystem, network, imports, `process`, `require`, `Deno`, `Bun`, or shell access, and no dynamic code compilation: `eval`, `Function`, and the async and generator function constructors are removed, including the `constructor` route reachable through function prototypes. Params: `code`, optional `root`, `timeout_ms` (capped at 30000), and `max_output_bytes` (capped at 4000000). `max_output_bytes` bounds two separate things: the total fallow JSON host calls read, shared across a `fallow.all` fan-out rather than granted per element, and the serialized snippet result. An oversized result is refused with `ok:false`, `truncated:true`, `result_bytes`, and a short `result_preview` in place of the value, never returned whole, so return a projection rather than a whole report. |
 | `analyze` | analysis | free | `fallow dead-code --format json --quiet` | `issue_types`, `production`, `workspace`, `baseline`, `group_by`, `file` | Full dead code analysis (unused files/exports/types/dependencies/members + circular dependencies + re-export cycles (barrel files that form a structural loop, silently breaking re-exports) + package cycles (workspace packages that import each other in a loop) + boundary violations + rule-pack policy violations (banned calls, imports, and catalogue-derived effects declared via the `rulePacks` config key) + stale suppressions). Private type leaks are an opt-in API hygiene check via `issue_types: ["private-type-leaks"]`. Deprecated exports that still have consumers are an opt-in migration sweep via `issue_types: ["deprecated-exports-in-use"]`. Set `boundary_violations: true` as a convenience alias for `issue_types: ["boundary-violations"]`. Set `group_by` to `"owner"`, `"directory"`, `"package"`, or `"section"` to partition results. The `section` mode reads GitLab CODEOWNERS `[Section]` headers and emits `owners` metadata per group |
 | `check_changed` | analysis | free | `fallow dead-code --changed-since <ref> --format json --quiet` | `since`, `baseline`, `fail_on_regression` | Incremental analysis of files changed since a git ref |
-| `security_candidates` | analysis | free | `fallow security --format json --quiet` | `gate`, `surface`, `changed_since`, `paths` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, severity, evidence, trace, optional `reachability`, blind-spot counters, and optional `unresolved_callee_diagnostics` samples for dynamic callee follow-up. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` (`source_kind`/`sink`/`boundary`), where URL-category sinks may include `url_shape` (`fixed-origin-dynamic-path` or `dynamic-origin`), an optional `taint_flow` source-to-sink triple, and a stable `finding_id` (equal to the SARIF fingerprint) for cross-run correlation; there is no `impact` field (deciding exploitability is the agent's job). Set `surface: true` to include top-level `attack_surface[]` entries with defensive-boundary prompts for a verifier. Set `gate` to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires `changed_since`. `reachability.untrusted_source_trace` is module-level import context only and does not prove value flow; `reachability.taint_confidence` tiers each reachable candidate as `arg-level` (sink argument traces to a same-module source read, strong) or `module-level` (only the module is import-reachable from a source, weak), so tier from this field instead of the evidence text. Verify trace, reachability context, severity, and evidence before editing code. Supports `root`, `config`, `workspace`, `paths`, `changed_since`, `changed_workspaces`, `surface`, `gate`, `no_cache`, and `threads`; `paths` forwards repeated `fallow security --file` filters for finding anchors, trace hops, untrusted-source reachability trace hops, and unresolved-callee diagnostics. See <https://docs.fallow.tools/cli/security-agent-verification> for the verifier packet and verdict recipe. Inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
+| `security_candidates` | analysis | free | `fallow security --format json --quiet` | `gate`, `surface`, `changed_since`, `paths` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, severity, evidence, trace, optional `reachability`, blind-spot counters, and optional `unresolved_callee_diagnostics` samples for dynamic callee follow-up. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` (`source_kind`/`sink`/`boundary`), where URL-category sinks may include `url_shape` (`fixed-origin-dynamic-path` or `dynamic-origin`), an optional `taint_flow` source-to-sink triple, and a stable `finding_id` (equal to the SARIF fingerprint) for cross-run correlation; there is no `impact` field (deciding exploitability is the agent's job). Set `surface: true` to include top-level `attack_surface[]` entries with defensive-boundary prompts for a verifier. Set `gate` to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires `changed_since`. `reachability.untrusted_source_trace` is module-level import context only and does not prove value flow; `reachability.taint_confidence` tiers each reachable candidate as `arg-level` (sink argument traces to a same-module source read, strong) or `module-level` (only the module is import-reachable from a source, weak), so tier from this field instead of the evidence text. Verify trace, reachability context, severity, and evidence before editing code. Supports `root`, `config`, `workspace`, `paths`, `changed_since`, `changed_workspaces`, `surface`, `gate`, `no_cache`, and `threads`; `paths` forwards repeated `fallow security --file` filters for finding anchors, trace hops, untrusted-source reachability trace hops, and unresolved-callee diagnostics. See <https://fallow.tools/docs/cli/security-agent-verification/> for the verifier packet and verdict recipe. Inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
 | `find_similar_code` | analysis | free | `fallow similar-code --format json --quiet` | `threshold`, `min_lines`, `top`, `changed_since`, `paths` | Find unverified semantically similar function candidates with the exact pinned local model. Discovery is read-only and never authorizes or performs model setup. Scoped output materializes the exact admitted files once in `generation.scope.paths` as provenance. Ask the user to run `fallow similar-code setup --local` when setup is missing. Cold local inference has a dedicated 15-minute subprocess window. |
 | `inspect_similar_code` | trace | free | `fallow similar-code inspect <candidate-id> --candidates <report.json> --format json --quiet` | `candidate_id`, `snapshot` | Inspect one exact unverified candidate without rerunning provider retrieval or global ranking. Pass `candidate_id` plus a bounded typed snapshot containing the unchanged discovery `schema_version`, `generation`, selected `candidate`, `completion`, and `diagnostics`. Current source is re-extracted and both endpoint hashes must still match, so stale source fails closed. Keep candidate worthiness, behavioral equivalence, and refactor safety as separate verdicts, and abstain when evidence is incomplete. |
 | `inspect_target` | analysis | free | `fallow inspect --format json --quiet` | `target`, `production`, `include_churn` | Compose one evidence bundle for a file or exported symbol. File targets use `target: { type: "file", file }`; symbol targets use `target: { type: "symbol", file, export_name }`. Returns `kind: "inspect_target"`, normalized target identity, `trace_file`, optional `trace_export`, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, and security candidates scoped to the file. Set `include_churn: true` to add target-level git churn from the health hotspot subsystem. Churn is off by default, and unavailable git history or analysis failures remain explicit section states. Evidence sections carry `status` and `scope`; symbol targets warn when supporting evidence is file-scoped. Supports `root`, `config`, `production`, `workspace`, `include_churn`, `no_cache`, and `threads`; `production` applies to trace, dead-code, and health evidence only. Raise `FALLOW_TIMEOUT_SECS` for large repos. |
@@ -50,14 +50,20 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `trace_error` | trace | free | `fallow trace-error - --format json --quiet` | `trace` | Resolve a runtime stack trace's frames against the project graph |
 | `impact_closure` | trace | free | `fallow dead-code --impact-closure <path> --format json --quiet` | `path` | Trace the transitive affected-but-not-in-diff set and coordination gaps for one file. Supports `root`, `config`, `production`, `workspace`, `no_cache`, and `threads`. Use as review-planning evidence for a file contract, not proof that affected files are wrong |
 | `trace_dependency` | trace | free | `fallow dead-code --trace-dependency <package> --format json --quiet` | `package_name` | Trace where a dependency is imported (`fallow dead-code --trace-dependency PACKAGE --format json`). Required `package_name`. Returns importing files, type-only importers, total import count, `used_in_scripts` (true when invoked from package.json scripts or CI configs), and `is_used` (combined import + script signal; mirrors the unused-deps detector so build tools like `microbundle` or `vitest` are not falsely flagged as unused). Use before removing a dependency or moving between `dependencies` and `devDependencies` |
-| `trace_clone` | trace | free | `fallow dupes --trace <file:line> --format json --quiet` | `file`, `line`, `fingerprint`, `near`, `min_occurrences` | Deep-dive a duplicate-code clone group (`fallow dupes --trace <spec> --format json`). Address by exactly one of: `file` + `line` (a source location), or `fingerprint` (a `dup:<id>` from a prior `find_dupes` `clone_groups[].fingerprint`, usually `dup:<8hex>` and widened only on rare report collisions). Returns the matched clone instance plus every clone group containing it; each traced group carries its `fingerprint`, an extract-function `suggestion` with estimated savings, and a best-effort `suggested_name` (omitted when no confident name). Supports `mode`, `near`, `min_tokens`, `min_lines`, `min_occurrences`, `threshold`, `skip_local`, `cross_language`, `ignore_imports`. Use the same `near` value as the originating `find_dupes` call. Use to consolidate duplication when you need exact sibling locations and a refactor target |
+| `trace_clone` | trace | free | `fallow dupes --trace <file:line> --format json --quiet` | `file`, `line`, `fingerprint`, `near`, `min_occurrences` | Deep-dive a duplicate-code clone group (`fallow dupes --trace <spec> --format json`). Address by exactly one of: `file` + `line` (a source location), or `fingerprint` (a `dup:<id>` from a prior `find_dupes` `clone_groups[].fingerprint`, usually `dup:<8hex>` and widened only on rare report collisions). Returns the matched clone instance plus every clone group containing it; each traced group carries its `fingerprint`, an extract-function `suggestion` with estimated savings, and a best-effort `suggested_name` (omitted when no confident name). Supports `mode`, `near`, `min_tokens`, `min_lines`, `min_occurrences`, `threshold`, `skip_local`, `ignore_symlinks`, `cross_language`, `ignore_imports`. Use the same `near` value as the originating `find_dupes` call. Use to consolidate duplication when you need exact sibling locations and a refactor target |
 <!-- generated:mcp-tools:end -->
 
 Tool hints: `fix_apply` changes source files and declares `destructiveHint: true`. `analyze`, `check_changed`, `find_dupes` and `check_health` write a baseline, regression baseline or snapshot file when you pass `save_baseline`, `save_regression_baseline` or `save_snapshot`. They declare `readOnlyHint: false` and `destructiveHint: false`, so a host can ask for approval before it runs them. Every other tool declares `readOnlyHint: true`.
 
 ## Resource catalogue
 
-Resources are the server's read-only reference channel: compile-time material an agent can list (`resources/list`, `resources/templates/list`) and read (`resources/read`) with no subprocess and no analysis run, cacheable by URI (your client reads them through its own resource tool). Each content item carries the server version in `_meta.fallow_version`; the payload itself is the plain document, so the schema resources are valid strict JSON Schema. Unknown URIs return a structured error whose `data` lists the known URIs (or the nearest issue types); the numeric code is `-32002` on protocol versions before 2026-07-28 and `-32602` from then on, so key on `data`. Every payload is JSON and carries `fallow_version`, so cache by URI and invalidate when the server version changes. The catalogue is static (no `subscribe`, no `listChanged`). Read `fallow://explain/{issue_type}` instead of calling `fallow_explain` when you only need the reference document; `issue_type` accepts the bare id (`unused-export`), the namespaced rule id (`security/sql-injection`), or the CLI filter spelling (`unused-exports`). An unknown URI or issue type returns a structured `resource_not_found` error listing the known URIs or the nearest issue types.
+Resources contain read-only, compile-time reference documents. Use your client's resource tool to list them (`resources/list`, `resources/templates/list`) and read them (`resources/read`). These reads start no subprocess or analysis. The catalogue is static (no `subscribe`, no `listChanged`).
+
+Every payload is JSON. Each content item carries the server version in `_meta.fallow_version`. The payload itself is the plain document, so schema resources remain valid strict JSON Schema. Cache by URI and invalidate the cache when the server version changes.
+
+An unknown URI or issue type returns a structured `resource_not_found` error. Its `data` lists the known URIs or the nearest issue types. The numeric code is `-32002` on protocol versions before 2026-07-28 and `-32602` from then on, so key on `data`.
+
+Read `fallow://explain/{issue_type}` when you need only the reference document. `fallow_explain` provides the tool equivalent. `issue_type` accepts the bare id (`unused-export`), the namespaced rule id (`security/sql-injection`), or the CLI filter spelling (`unused-exports`).
 
 <!-- generated:mcp-resources:start -->
 | Resource | Name | Kind | MIME | Description |
@@ -138,8 +144,14 @@ An entry in `not_found` has no cloud data. Absence is not evidence that the code
 
 Most tools accept `root`, `config`, `no_cache`, and `threads` params. Exceptions: `impact` takes only `root`; `code_execute` takes `code`, optional `root`, `timeout_ms`, and `max_output_bytes`. Similar-code file scope is named `paths` on both standalone MCP tools and forwards repeated CLI `--file` flags. MCP subprocesses default to 120 seconds, except similar-code discovery and inspection which default to 15 minutes for cold local inference. `FALLOW_TIMEOUT_SECS` overrides either default. Code Mode does not expose similar-code because its 30-second cap cannot satisfy that contract.
 
-All JSON responses include structured `actions` arrays on every finding (dead code, health, duplication), enabling programmatic fix application or suppression.
+Every dead-code, health, and duplication finding in JSON responses includes a structured `actions` array for programmatic fixes or suppression.
 
 `health.thresholdOverrides[]` lets projects keep known legacy functions visible as configured local ceilings instead of hiding them with suppressions. Each entry has `files` globs, optional exact `functions`, one or more of `maxCyclomatic`, `maxCognitive`, `maxCrap`, or `maxUnitSize`, and optional `reason`. Health JSON may include top-level `threshold_overrides[]` entries with `active`, `stale`, `insufficient`, or `no_match` status, and complexity findings that use an override carry `effective_thresholds` plus `threshold_source: "override"`. Each entry also names its `dimension` (`complexity` or `crap`), so one configured override yields one entry per dimension it participates in: group on `override_index` to count configured overrides. `insufficient` means the raised ceiling is still exceeded. An entry's `outstanding[]` lists every dimension the matched unit still breaches after the override applied, which is how an `active` override can sit next to a surviving finding.
 
-`dead-code`, `health`, `dupes`, bare `fallow`, and `audit` JSON output also carry a top-level `next_steps` array of read-only follow-up commands computed from the run's findings: each entry is `{ id, command, reason }`. The `command` is runnable as-is (never a placeholder, never `fix` or any other mutating command); the stable kebab-case `id` (`setup`, `impact-report`, `trace-unused-export`, `trace-deprecated-export`, `trace-clone`, `complexity-breakdown`, `scope-workspaces`, `audit-changed`) maps to a verification step you should run BEFORE acting, for example tracing an export before deleting it. A leading `setup` step (command: `fallow schema`) appears only on unconfigured, non-CI projects with findings and doubles as an onboarding trigger; it disappears after setup or `fallow init --decline`. An at-most-weekly `impact-report` step (command: `fallow impact`) carries the local value digest when impact tracking has non-zero results; it may ride a clean run. When running via MCP, dispatch on the `id` to the matching tool / `code_execute` host call (`trace_export`, `trace_clone`, `check_health` with `complexity_breakdown: true`, `audit`) rather than shelling out the CLI string. The array is deduplicated, capped at three, and omitted when empty; set `FALLOW_SUGGESTIONS=off` to suppress it.
+`dead-code`, `health`, `dupes`, bare `fallow`, and `audit` JSON output may include a top-level `next_steps` array of read-only follow-up commands computed from the run's findings. Each entry is `{ id, command, reason }`. The `command` is runnable as-is (never a placeholder, never `fix` or any other mutating command); the stable kebab-case `id` (`setup`, `impact-report`, `trace-unused-export`, `trace-deprecated-export`, `trace-clone`, `complexity-breakdown`, `scope-workspaces`, `audit-changed`) maps to a verification step to run before acting, for example tracing an export before deleting it.
+
+A leading `setup` step (command: `fallow schema`) appears only on unconfigured, non-CI projects with findings and doubles as an onboarding trigger; it disappears after setup or `fallow init --decline`.
+
+An at-most-weekly `impact-report` step (command: `fallow impact`) carries the local value digest when impact tracking has non-zero results; it may appear in a clean run.
+
+When running via MCP, dispatch on the `id` to the matching tool or `code_execute` host call (`trace_export`, `trace_clone`, `check_health` with `complexity_breakdown: true`, `audit`) rather than shelling out the CLI string. The array is deduplicated, capped at three, and omitted when empty; set `FALLOW_SUGGESTIONS=off` to suppress it.

package/skills/fallow/references/node-bindings.md

@@ -1,6 +1,6 @@
 # Node.js Bindings
 
-When embedding fallow inside a Node.js process (editor extensions, long-running servers, custom tooling), prefer the NAPI bindings over spawning the CLI. Same analysis engine, same JSON envelopes, no subprocess or JSON parsing overhead.
+To embed fallow in a Node.js process, use the NAPI bindings. They use the same analysis engine and JSON envelopes as the CLI without spawning the CLI or parsing its JSON output. Examples include editor extensions, long-running servers, and custom tooling.
 
 ```bash
 npm install @fallow-cli/fallow-node
@@ -15,8 +15,14 @@ const similarCode = await detectSimilarCode({ root: process.cwd(), files: ['src/
 const health = await computeHealth({ root: process.cwd(), score: true, ownershipEmails: 'handle' });
 ```
 
-Eight async functions: `detectDeadCode`, `detectCircularDependencies`, `detectBoundaryViolations`, `detectDuplication`, `detectSimilarCode`, `detectFeatureFlags`, `computeComplexity`, `computeHealth`. Each returns the same JSON envelope the CLI emits for `--format json`. `detectSimilarCode` returns a precisely typed `SimilarCodeReport`, including generation provenance, embedding semantics, effective `generation.scope.paths`, completion, skips, cache accounting, diagnostics, and read-only candidate actions. Treat the materialized scope as provenance and preserve the raw report when a candidate may be inspected later. The Node binding exposes discovery only. Use CLI `similar-code inspect --candidates <report.json>` or MCP `inspect_similar_code` with the exact typed candidate snapshot so global retrieval and ranking are not repeated. Its loader resolves and verifies the exact-version local companion; it never downloads the model or authorizes setup. Rejected promises throw a `FallowNodeError` with `message`, `exitCode`, and optional `code`, `help`, `context` fields that mirror the CLI's structured error surface.
+The async functions are `detectDeadCode`, `detectCircularDependencies`, `detectBoundaryViolations`, `detectDuplication`, `detectSimilarCode`, `detectFeatureFlags`, `computeComplexity`, and `computeHealth`. Each returns the same JSON envelope the CLI emits for `--format json`.
+
+`detectSimilarCode` returns a precisely typed `SimilarCodeReport` with generation provenance, embedding semantics, effective `generation.scope.paths`, completion, skips, cache accounting, diagnostics, and read-only candidate actions. Treat the materialized scope as provenance. Preserve the raw report when a candidate may be inspected later.
+
+`detectSimilarCode` exposes discovery only. Use CLI `similar-code inspect --candidates <report.json>` or MCP `inspect_similar_code` with the exact typed candidate snapshot. This avoids repeating global retrieval and ranking. The loader resolves and verifies the exact-version local companion. It never downloads the model or authorizes setup.
+
+Rejected promises throw a `FallowNodeError` with `message`, `exitCode`, and optional `code`, `help`, `context` fields. These fields match the CLI's structured errors.
 
 Enum-like fields take lowercase CLI-style literals (`"mild"`, `"cyclomatic"`, `"handle"`, `"low"`). Write-path commands (`fix`, `init`, `hooks install`, `hooks uninstall`, `license activate`, `coverage setup`) are not exposed; use the CLI for those.
 
-See <https://docs.fallow.tools/integrations/node-bindings> for the full field reference.
+See <https://fallow.tools/docs/integrations/node-bindings/> for the full field reference.

package/skills/fallow/references/patterns.md

@@ -66,7 +66,7 @@ fallow dead-code --format json --quiet
 
 ## PR Dead Code Check
 
-Check if a pull request introduces new dead code.
+Report dead-code findings in files changed by a pull request.
 
 ### Step 1: Analyze changed files
 
@@ -74,7 +74,7 @@ Check if a pull request introduces new dead code.
 fallow dead-code --format json --quiet --changed-since main --fail-on-issues
 ```
 
-Exit code 1 if the PR introduces new dead code. Exit code 0 if clean.
+With `--fail-on-issues`, reported warn-severity and error-severity findings exit 1. Existing findings in changed files can also fail this check. Use `fallow audit --gate new-only` when the gate should fail only on introduced findings.
 
 ### Step 2: If issues found, show specifics
 
@@ -82,7 +82,7 @@ Exit code 1 if the PR introduces new dead code. Exit code 0 if clean.
 fallow dead-code --format json --quiet --changed-since main
 ```
 
-Parse the JSON to list specific files and exports that became unused.
+Parse the JSON to list reported files and exports. This command does not distinguish introduced findings from inherited ones.
 
 ---
 
@@ -446,7 +446,7 @@ Creates `.fallowrc.json` with mapped settings:
   hidden, but matching files remain in the module graph; leading `!` exceptions
   are preserved; multi-source findings stay visible unless every source owner
   matches)
-- knip `ignoreDependencies` → fallow `ignoreDependencies`
+- knip `ignoreDependencies` → fallow `ignoreDependencies` (a regex such as `@org/.+` becomes the glob `@org/*` when the glob matches the same packages; other regexes are skipped with a warning)
 - knip `ignoreExportsUsedInFile` → fallow `ignoreExportsUsedInFile` (boolean and `{ type, interface }` object form both supported; fallow groups type aliases and interfaces under one issue, so the two type-kind fields behave identically)
 - Unmappable fields generate warnings with suggestions
 
@@ -614,7 +614,7 @@ export const dynamicallyUsed = createHandler();
 
 ### If the trace shows it's NOT used
 
-The export is genuinely unused. Consider removing it or marking it as intentionally kept:
+The trace found no static use. Check dynamic imports, reflection, and external callers before removal. If the export must remain, mark it as intentionally kept:
 
 ```typescript
 // fallow-ignore-next-line unused-export
@@ -766,7 +766,7 @@ Manual files:
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fallow-gate.sh"
+            "command": "d=\"$(pwd)\"; until [ -f \"$d/.claude/hooks/fallow-gate.sh\" ] || [ -e \"$d/.git\" ] || [ \"$d\" = / ]; do d=\"$(dirname \"$d\")\"; done; if [ -f \"$d/.claude/hooks/fallow-gate.sh\" ]; then cd \"$d\" && exec ./.claude/hooks/fallow-gate.sh; fi; exec \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fallow-gate.sh"
           }
         ]
       }
@@ -780,19 +780,44 @@ Manual files:
 Prefer `fallow hooks install --target agent` to install this file. The script is written and maintained by fallow itself; the canonical source is [`crates/cli/src/setup_hooks/fallow-gate.sh`](https://github.com/fallow-rs/fallow/blob/main/crates/cli/src/setup_hooks/fallow-gate.sh).
 
 Behavior you can rely on:
+- The handler walks up from the session directory to the nearest directory that holds `.claude/hooks/fallow-gate.sh` and runs the audit there, so a session in a package directory audits the install root. The walk stops at the first `.git` entry. When it finds no script, the handler runs the script under `$CLAUDE_PROJECT_DIR` from the session directory.
 - Runs only when the intercepted command is a `git commit` or `git push`, including invocations that pass git-level options before the subcommand (`git -c user.name=x commit`, `git --no-pager commit`, `git -C dir push`, `git --git-dir=/x push`); anything else exits 0. Set `FALLOW_GATE_DEBUG=1` to log skipped commands to stderr.
 - Resolves `fallow` from PATH first, then `npx --no-install fallow` as a fallback. Skips with a stderr notice if neither is available or if `jq` is missing.
-- Enforces a version floor via `FALLOW_GATE_MIN_VERSION` (default `2.85.0`). Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
+- Enforces a version floor via `FALLOW_GATE_MIN_VERSION`. The installed gate script holds the default floor (currently `2.85.0`). Fallow maintainers raise that default by hand; `fallow hooks install` does not set it to the installed version. Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
 - Runs `fallow audit --format json --quiet --explain --gate-marker agent` and, on verdict=`fail`, writes the full JSON envelope to stderr preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable. The gate marker lets local Impact record blocked-then-cleared agent gate events when Impact is enabled.
 - On runtime error (`{"error": true, ...}`) or unexpected non-zero exit, fails open with a one-line stderr notice; warn verdicts pass through silently.
 
-Codex fallback (add to repo root `AGENTS.md`):
+### `.codex/hooks.json`
+
+Codex reads the same PreToolUse shape and runs the same gate script from `.codex/hooks/fallow-gate.sh`. Codex runs hook commands from the session directory, so the handler walks up to the nearest directory that holds the gate script (the install root) and runs it there. The walk stops at the first `.git` entry, so a nested worktree does not reach the gate of the checkout around it:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "d=\"$(pwd)\"; until [ -f \"$d/.codex/hooks/fallow-gate.sh\" ] || [ -e \"$d/.git\" ] || [ \"$d\" = / ]; do d=\"$(dirname \"$d\")\"; done; if [ -f \"$d/.codex/hooks/fallow-gate.sh\" ]; then cd \"$d\" && exec ./.codex/hooks/fallow-gate.sh; fi; exit 0"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Codex loads project hooks only when the project `.codex/` layer is trusted, and it asks you to review each new or changed hook in `/hooks` before it runs.
+
+Excerpt of the `AGENTS.md` routing block (written for Codex, also read by other agents; the full text is `AGENTS_BLOCK_BODY` in `crates/cli/src/setup_hooks.rs`):
 
 ```md
-Before any `git commit` or `git push`, run `fallow audit --format json --quiet --explain --gate-marker agent`. If the verdict is `fail`, fix the reported findings before retrying. Treat JSON runtime errors like `{ "error": true, ... }` as non-blocking.
+Fallow checks the changed code before each `git commit` and `git push`. In Claude Code and Codex, a PreToolUse hook from `fallow agent install` runs this check and blocks the command when the verdict is `fail`. Other agents run the check themselves: `fallow audit --format json --quiet --explain --gate-marker agent`.
 ```
 
-Keep `fallow audit` in CI alongside this local gate. The hook only runs for Claude Code, not for human pushes or other agents, so it is a reinforcement layer rather than a replacement for server-side enforcement.
+Keep `fallow audit` in CI alongside this local gate. The hooks run only for Claude Code and Codex, not for human pushes or other agents, so they are a reinforcement layer rather than a replacement for server-side enforcement.
 
 ### Remove the hook
 
@@ -800,10 +825,10 @@ Keep `fallow audit` in CI alongside this local gate. The hook only runs for Clau
 fallow hooks uninstall --target agent
 ```
 
-Removes the fallow-gate handler from `.claude/settings.json` (preserving any other handlers in the same matcher group), deletes `.claude/hooks/fallow-gate.sh` if it still carries the `# Generated by fallow setup-hooks.` marker, and strips the managed block from `AGENTS.md`. Idempotent: a second run reports `unchanged` / `not present` and exits 0.
+Removes the fallow-gate handler from `.claude/settings.json` and `.codex/hooks.json` (preserving any other handlers in the same matcher group, and deleting `.codex/hooks.json` when nothing else is left in it), deletes each `fallow-gate.sh` that still carries the `# Generated by fallow setup-hooks.` marker, and strips the managed block from `AGENTS.md`. Idempotent: a second run reports `unchanged` / `not present` and exits 0.
 
 Use `--force` to remove a hook script that the user has edited (the marker is no longer present). Use `--dry-run` to preview without touching files.
 
 ### Distinguish from `fallow hooks install --target git`
 
-`fallow hooks install --target git` is a different target: it scaffolds a shell-level Git pre-commit hook under `.git/hooks/` that runs `fallow` on changed files. That is the *human* enforcement path. `fallow hooks install --target agent` is the *agent* enforcement path, targeting `.claude/` and `AGENTS.md`. Both can live in the same repo: git hooks catch human commits, the agent gate catches agent commits.
+`fallow hooks install --target git` is a different target: it scaffolds a shell-level Git pre-commit hook under `.git/hooks/` that runs `fallow` on changed files. That is the *human* enforcement path. `fallow hooks install --target agent` is the *agent* enforcement path, targeting `.claude/`, `.codex/`, and `AGENTS.md`. Both can live in the same repo: git hooks catch human commits, the agent gate catches agent commits.

package/skills/fallow-setup/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: fallow-setup
+description: Set up or modernize code-quality tooling for JavaScript and TypeScript projects. Use when creating a project, adding code-health or CI quality checks, making a repository agent-ready, or consolidating dead-code, duplication, architecture, dependency, and changed-code analysis. Do not use for formatting-only, lint-rule-only, or TypeScript type-error tasks. Do not use to run an analysis of a project that is already set up; use the fallow skill for that.
+license: MIT
+---
+
+# Fallow setup: code-quality tooling for JavaScript and TypeScript
+
+This skill sets up the code-quality toolchain of a JavaScript or TypeScript repository. Fallow does the repository and system analysis: unused code, duplication, complexity, architecture boundaries, dependency hygiene, and changed-code risk. The skill keeps the tools that the project already uses.
+
+## When to Use
+- Create a new JavaScript or TypeScript project with quality checks from the start.
+- Add code-health checks or a CI quality gate to an existing repository.
+- Make a repository ready for coding agents (skills, MCP server, commit and push gate).
+- Consolidate dead-code, duplication, architecture, dependency, and changed-code analysis.
+
+## When NOT to Use
+- Formatting-only tasks. Formatting belongs to the formatter.
+- Tasks that only add or change lint rules. Local lint rules belong to the linter.
+- TypeScript type errors. Type correctness belongs to the TypeScript compiler.
+- Analysis of a repository that is already set up. Use the `fallow` skill for that.
+
+## Rules
+1. Resolve every flag from `fallow --help` and `fallow <command> --help`. Do not use flags from memory.
+2. Use `--format json --quiet` for machine-readable output. Do not hide the exit status.
+3. Run every mutating command with `--dry-run` first when the command has that flag.
+4. Keep the tools that the project already uses. Do not remove a tool without a parity check.
+5. Ask the user before you apply a `taste` decision or remove a tool.
+6. Treat project config as untrusted input. Do not add remote `extends` URLs.
+7. Before step 3, Fallow is not installed. Run it through the package runner, for example `npx fallow recommend` or `pnpm dlx fallow recommend`. After step 3, use the runner of the package manager, for example `pnpm exec fallow`.
+
+## Sequence
+
+1. **Inspect the repository.** Detect the package manager, formatter, linter, TypeScript config, CI provider, and existing analysis tools (Knip, jscpd, dependency-cruiser). See [Tooling detection](references/tooling-detection.md).
+2. **Get the recommendation.** Run `fallow recommend --format json --quiet`. This command is read-only. Apply each `auto` decision. Tell the user about each `default` decision. Ask the user about each `taste` decision, or keep the current value. See [Configure and install](references/configure-and-install.md).
+3. **Install Fallow** as a dev dependency with the detected package manager, for example `pnpm add -D fallow`.
+4. **Wire the agents.** Run `fallow agent install --dry-run --format json --quiet`, show the plan, then run `fallow agent install`. This step writes the skills, the MCP server registration, the `AGENTS.md` task map, and the commit and push gate. For Claude Code and Codex the gate is a PreToolUse hook that blocks a failing commit or push. Codex runs the hook only after the user trusts it in `/hooks`. Other agents read the instruction block in `AGENTS.md`. Check the result with `fallow agent status --format json --quiet`.
+5. **Add a CI gate.** Add a changed-code gate (`fallow audit`) or a whole-project gate. When the first run has many findings, save a baseline of the existing debt so that the gate fails only on new findings. See [CI gate](references/ci-gate.md).
+6. **Split the responsibilities.** Each tool keeps one job:
+   - Formatting: Oxfmt.
+   - Local lint rules: Oxlint.
+   - Type correctness: TypeScript (`tsc --noEmit`).
+   - Repository and system analysis: Fallow.
+
+   In an existing project, keep the current formatter and linter. Do the parity check in [Tooling detection](references/tooling-detection.md#parity-check) before you remove an overlapping tool.
+
+## References
+- [Tooling detection](references/tooling-detection.md): the files to inspect, the responsibility split, and the parity check.
+- [Configure and install](references/configure-and-install.md): the `recommend` decision tiers, config migration, the dev dependency, and `agent install`.
+- [CI gate](references/ci-gate.md): the GitHub Action, the GitLab template, the CLI gate, and baselines.

package/skills/fallow-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Fallow Setup"
+  short_description: "Set up JS and TS code-quality tooling"
+  default_prompt: "Use $fallow-setup to set up code-quality tooling, agent wiring, and a CI quality gate for this repository."

package/skills/fallow-setup/references/ci-gate.md

@@ -0,0 +1,61 @@
+# CI gate
+
+Add one gate to the CI provider that the project already uses. Exit code 0 means that the gate passed. Exit code 1 means that the gate found error-severity findings or that the audit result is `fail`. Exit code 2 means invalid input or an execution error. Do not force a successful exit status, because that hides the gate result.
+
+## Select the gate
+
+| Gate | Command | Fails on | Baseline |
+|---|---|---|---|
+| Changed-code gate | `fallow audit` | Findings that the change introduces in the changed files | Not necessary |
+| Whole-project gate | `fallow` | Every error-severity finding in the project | Necessary when the first run has many findings |
+
+Start with the changed-code gate. `fallow audit` uses `--gate new-only` by default, so findings that existed before the change do not fail it. The audit needs the git history of the base ref. In CI, fetch the full history.
+
+## GitHub Actions
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: fallow-rs/fallow@v3
+  with:
+    command: audit
+```
+
+The Action installs the Fallow version that `package.json` names. To start in report-only mode, add `fail-on-issues: false`. Remove it when the team accepts the gate.
+
+## GitLab CI
+
+```yaml
+include:
+  - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/v<version>/ci/gitlab-ci.yml'
+
+fallow:
+  extends: .fallow
+  variables:
+    FALLOW_COMMAND: "audit"
+```
+
+Replace `<version>` with the installed Fallow version. When the runners cannot reach `raw.githubusercontent.com`, run `fallow ci-template gitlab --vendor` and include the vendored files locally.
+
+## Other CI providers
+
+Run the CLI directly after the dependencies are installed:
+
+```bash
+npx fallow audit --base origin/main --format json --quiet
+```
+
+Use the runner of the detected package manager, for example `pnpm exec fallow`.
+
+## Baselines
+
+A whole-project gate on an existing project often reports a large backlog on the first run. Save a baseline of that backlog, so that the gate fails only on new findings:
+
+```bash
+fallow dead-code --format json --quiet --save-baseline fallow-baselines/dead-code.json
+fallow health --format json --quiet --save-baseline fallow-baselines/health.json
+fallow dupes --format json --quiet --save-baseline fallow-baselines/dupes.json
+```
+
+Commit the baseline files. Pass each file to the matching command with `--baseline <path>`. `fallow audit` uses `--dead-code-baseline`, `--health-baseline`, and `--dupes-baseline` instead. `--fail-on-baseline-growth` makes a committed baseline shrink-only. Tell the user how many findings the baseline contains, and suggest that the team removes them by category.

package/skills/fallow-setup/references/configure-and-install.md

@@ -0,0 +1,56 @@
+# Configure and install
+
+## Recommendation
+
+`fallow recommend --format json --quiet` inspects the project and changes nothing. It always exits 0. The envelope has `kind: "recommendation"` and these fields:
+
+| Field | Content |
+|---|---|
+| `detected` | The project facts: monorepo layout, TypeScript, test framework, UI framework, Storybook, package manager |
+| `proposed_config` | A safe starting config |
+| `decisions[]` | One entry per setting: `setting`, `value`, `rationale`, `kind`, `question` |
+| `config_schema_command` | The command that prints the config JSON Schema |
+
+Use `kind` to decide what to do with each decision:
+
+| `kind` | Meaning | Action |
+|---|---|---|
+| `auto` | Fallow decided the value from the detection | Apply it. |
+| `default` | A disclosed default that the user can change | Apply it and tell the user the `rationale` in one line. |
+| `taste` | A subjective choice | Keep the current value, or ask the user. `question` has a `header`, a `question`, and `options[]` with a `label` and a `description`. Show these options as they are. |
+
+When the project has no Fallow config, write `proposed_config` plus the answers to `.fallowrc.json`. When the project has a config, change only the settings that the user approved. Validate the keys with `fallow config-schema`. Check the loaded config with `fallow config --format json --quiet`.
+
+When the project has a Knip, jscpd, or stylelint config, preview the migration with `fallow migrate --dry-run`. Merge the result with the recommendation. Do not delete the old config in this step. The [parity check](tooling-detection.md#parity-check) decides when it can go.
+
+## Dev dependency
+
+Install Fallow as a dev dependency with the detected package manager:
+
+| Package manager | Command |
+|---|---|
+| npm | `npm install --save-dev fallow` |
+| pnpm | `pnpm add -D fallow` |
+| Yarn | `yarn add -D fallow` |
+| Bun | `bun add -d fallow` |
+
+A dev dependency pins one Fallow version for every developer, every agent, and CI. Add scripts to `package.json` when the project uses scripts for its other checks, for example `"fallow": "fallow"` and `"fallow:audit": "fallow audit"`.
+
+## Agent wiring
+
+`fallow agent install` wires Fallow into Claude Code, Codex, and Cursor in one pass. It detects the harnesses from the project, the home directory, and the session environment. `--harness` selects them explicitly.
+
+1. Run `fallow agent install --dry-run --format json --quiet`. Each entry in `steps[]` has a `step`, a `status`, and a `path`. Show the plan to the user.
+2. Run `fallow agent install`. Add `--without <step>` to skip a step. The steps are `guide`, `skill`, `mcp`, and `hooks`.
+3. Run `fallow agent status --format json --quiet`. Check only the entries of the harnesses that step 1 selected. Status also lists the other harnesses (for example `.cursor/mcp.json` in a Claude-only project) as `absent`, which is correct. Act on `next_actions[]` for a `stale` entry of a selected harness.
+
+The steps write these items:
+
+| Step | Result |
+|---|---|
+| `guide` | The task map in `AGENTS.md`, and an `@AGENTS.md` import in `CLAUDE.md` for Claude Code |
+| `skill` | The Fallow skills under `.claude/skills/` and `.agents/skills/` |
+| `mcp` | The MCP server registration for each harness |
+| `hooks` | The commit and push gate: a PreToolUse hook for Claude Code (`.claude/settings.json`) and for Codex (`.codex/hooks.json`), plus a routing block in `AGENTS.md` |
+
+Exit code 2 means that a step is `refused` or `failed`. Read the `reason` of that step. `skill_name_taken` means that a skill with the same name exists and Fallow did not write it. Do not pass `--force` without the approval of the user.

package/skills/fallow-setup/references/tooling-detection.md

@@ -0,0 +1,44 @@
+# Tooling detection
+
+Inspect the repository before you change it. Record what you find, because the later steps use it.
+
+## Files to inspect
+
+| Tool area | Signals |
+|---|---|
+| Package manager | `packageManager` in `package.json`; the lockfile: `pnpm-lock.yaml`, `yarn.lock`, `bun.lock` or `bun.lockb`, `package-lock.json` |
+| Formatter | `.oxfmtrc.json`, `.prettierrc*`, `prettier.config.*`, `biome.json`, `biome.jsonc`, a `format` script in `package.json` |
+| Linter | `.oxlintrc.json`, `eslint.config.*`, `.eslintrc*`, `biome.json`, a `lint` script in `package.json` |
+| TypeScript | `tsconfig.json`, `tsconfig.*.json`, a `typecheck` script, `typescript` in `devDependencies` |
+| CI | `.github/workflows/*.yml`, `.gitlab-ci.yml`, other CI config files |
+| Existing analysis | `knip.json`, `knip.jsonc`, `.knip.json`, `.knip.jsonc`, a `knip` field in `package.json`; `.jscpd.json`; `.dependency-cruiser.*` |
+| Existing Fallow | `fallow config --path` prints the config path, or exits 3 when there is no config |
+| Agent harnesses | `CLAUDE.md`, `.claude/`, `.codex/`, `.cursor/` (`AGENTS.md` alone does not name a harness) |
+
+`fallow doctor --format json --quiet` checks the project root, the config, the workspaces, and the installed dependencies. It changes nothing. Run it when the project layout is not clear.
+
+## Responsibility split
+
+Give each tool one job. Do not configure two tools for the same job.
+
+| Job | Tool | Command |
+|---|---|---|
+| Formatting | Oxfmt | `oxfmt` |
+| Local lint rules | Oxlint | `oxlint` |
+| Type correctness | TypeScript | `tsc --noEmit` |
+| Repository and system analysis | Fallow | `fallow`, `fallow audit` |
+
+Repository and system analysis covers unused files, exports, types, and dependencies, duplication, complexity, circular dependencies, architecture boundaries, and changed-code risk.
+
+For a new project, use the tools in this table. For an existing project, keep the current formatter, linter, and type check. Add Fallow for the system analysis.
+
+## Parity check
+
+Do this check before you remove a tool whose job overlaps with Fallow, for example Knip, jscpd, or dependency-cruiser. When a step fails, keep the tool and tell the user why.
+
+1. Ask the user for approval to replace the tool.
+2. Migrate the config when Fallow can read it: `fallow migrate --dry-run` for Knip, jscpd, and stylelint. When the project has no Fallow config, review the preview, then run `fallow migrate`. When a Fallow config exists, `fallow migrate` refuses to write. Merge the settings from the preview into that config by hand. Fallow cannot migrate a dependency-cruiser config. Write the rules again as `boundaries` in the Fallow config (`fallow config-schema` gives the format).
+3. Run the old tool and Fallow on the same commit. Compare the findings by category.
+4. Explain each finding that only one tool reports. A finding that Fallow does not report must have a reason, for example a framework entry point that Fallow detects.
+5. Move each CI step and each `package.json` script of the old tool to Fallow.
+6. Remove the old tool and its config in a separate commit, so that the user can revert it.