fallow 2.69.0 → 2.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.69.0",
+  "version": "2.70.0",
   "description": "Codebase intelligence for TypeScript and JavaScript. Finds unused code, duplication, circular dependencies, complexity hotspots, and architecture drift. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, 94 framework plugins.",
   "license": "MIT",
   "repository": {
@@ -55,13 +55,13 @@
     "@tanstack/intent": "0.0.36"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.69.0",
-    "@fallow-cli/darwin-x64": "2.69.0",
-    "@fallow-cli/linux-x64-gnu": "2.69.0",
-    "@fallow-cli/linux-arm64-gnu": "2.69.0",
-    "@fallow-cli/linux-x64-musl": "2.69.0",
-    "@fallow-cli/linux-arm64-musl": "2.69.0",
-    "@fallow-cli/win32-arm64-msvc": "2.69.0",
-    "@fallow-cli/win32-x64-msvc": "2.69.0"
+    "@fallow-cli/darwin-arm64": "2.70.0",
+    "@fallow-cli/darwin-x64": "2.70.0",
+    "@fallow-cli/linux-x64-gnu": "2.70.0",
+    "@fallow-cli/linux-arm64-gnu": "2.70.0",
+    "@fallow-cli/linux-x64-musl": "2.70.0",
+    "@fallow-cli/linux-arm64-musl": "2.70.0",
+    "@fallow-cli/win32-arm64-msvc": "2.70.0",
+    "@fallow-cli/win32-x64-msvc": "2.70.0"
   }
 }

package/schema.json

@@ -148,7 +148,8 @@
         "boundary-violation": "error",
         "coverage-gaps": "off",
         "feature-flags": "off",
-        "stale-suppressions": "warn"
+        "stale-suppressions": "warn",
+        "unused-catalog-entries": "warn"
       }
     },
     "boundaries": {
@@ -873,6 +874,10 @@
         "stale-suppressions": {
           "$ref": "#/$defs/Severity",
           "default": "warn"
+        },
+        "unused-catalog-entries": {
+          "$ref": "#/$defs/Severity",
+          "default": "warn"
         }
       }
     },
@@ -1317,6 +1322,16 @@
               "type": "null"
             }
           ]
+        },
+        "unused-catalog-entries": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       }
     },

package/skills/fallow/references/cli-reference.md

@@ -15,6 +15,7 @@ Complete command and flag specifications for all fallow CLI commands.
 - [`health`: Function Complexity Analysis](#health-function-complexity-analysis)
 - [`audit`: Changed-File Quality Gate](#audit-changed-file-quality-gate)
 - [`flags`: Feature Flag Detection](#flags-feature-flag-detection)
+- [`explain`: Rule Explanation](#explain-rule-explanation)
 - [`schema`: CLI Introspection](#schema-cli-introspection)
 - [`config-schema`: Config JSON Schema](#config-schema-config-json-schema)
 - [`plugin-schema`: Plugin JSON Schema](#plugin-schema-plugin-json-schema)
@@ -36,7 +37,7 @@ Analyzes the project for unused files, exports, dependencies, types, members, an
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
-| `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality` | `human` | Output format |
+| `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality\|pr-comment-github\|pr-comment-gitlab\|review-github\|review-gitlab` | `human` | Output format |
 | `--quiet` | bool | `false` | Suppress progress bars and timing on stderr |
 | `--changed-since` | string | — | Only analyze files changed since a git ref (e.g., `main`, `HEAD~3`) |
 | `--production` | bool | `false` | Exclude test/dev files, only start/build scripts (applies to every analysis) |
@@ -61,6 +62,7 @@ Analyzes the project for unused files, exports, dependencies, types, members, an
 | `--unused-files` | Unused files |
 | `--unused-exports` | Unused exports |
 | `--unused-types` | Unused types |
+| `--private-type-leaks` | Opt-in API hygiene check (default `off`) for exported signatures that reference same-file private types. Storybook `*.stories.*` story files and framework routing convention files (Next.js App + Pages Router, Gatsby, Remix v2, TanStack Router, Expo Router) are skipped to avoid noise. Enable via this flag or `private-type-leaks: "warn"` / `"error"` in [`rules`](#rules-configuration). |
 | `--unused-deps` | Unused dependencies, devDependencies, optionalDependencies, type-only production deps, and test-only production deps |
 | `--unused-enum-members` | Unused enum members |
 | `--unused-class-members` | Unused class members |
@@ -128,11 +130,13 @@ fallow dead-code --format json --quiet --include-entry-exports
 
 Finds code duplication and clones across the project.
 
+By default, `fallow dupes` skips generated framework output matching `**/.next/**`, `**/.nuxt/**`, `**/.svelte-kit/**`, `**/.turbo/**`, `**/.parcel-cache/**`, `**/.vite/**`, `**/.cache/**`, `**/out/**`, and `**/storybook-static/**`. These defaults merge with `duplicates.ignore`. Set `duplicates.ignoreDefaults = false` to opt out and use only your configured ignore list. If the reported duplication percentage drops after upgrading, this generated-output filtering is the expected reason.
+
 ### Flags
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
-| `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality` | `human` | Output format |
+| `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality\|pr-comment-github\|pr-comment-gitlab\|review-github\|review-gitlab` | `human` | Output format |
 | `--quiet` | bool | `false` | Suppress progress bars |
 | `--top` | number | — | Show only the N largest clone groups (sorted by line count descending). Summary stats reflect the full project. |
 | `--mode` | `strict\|mild\|weak\|semantic` | `mild` | Detection mode |
@@ -142,12 +146,14 @@ Finds code duplication and clones across the project.
 | `--skip-local` | bool | `false` | Only report cross-directory duplicates |
 | `--cross-language` | bool | `false` | Strip type annotations for TS↔JS matching |
 | `--ignore-imports` | bool | `false` | Exclude import declarations from clone detection |
+| `--explain-skipped` | bool | `false` | Human/markdown only: show per-pattern counts for files skipped by default duplicates ignores |
 | `--trace` | `FILE:LINE` | — | Trace all clones at a specific location |
 | `--changed-since` | string | — | Only report duplication in files changed since a git ref |
 | `--baseline` | path | — | Compare against baseline |
 | `--save-baseline` | path | — | Save results as baseline |
 | `--workspace` | string | — | Scope to one or more workspaces. Comma-separated values, globs (`apps/*`, `@scope/*`), and `!`-prefixed negation (`!apps/legacy`) supported. Matched against package name AND workspace path relative to repo root. |
 | `--changed-workspaces` | string (git ref) | — | Git-derived monorepo CI scoping: scope to workspaces containing any file changed since `REF`. Mutually exclusive with `--workspace`. Missing ref is a hard error. |
+| `--group-by` | `owner\|directory\|package\|section` | — | Partition the report into per-group sections. Each clone group is attributed to its **largest owner** (most instances; alphabetical tiebreak): a group split 2 src / 1 lib appears under `src`. JSON adds `grouped_by` plus a `groups` array; each bucket carries dedup-aware `stats`, `clone_groups` (every group tagged with `primary_owner` and per-instance `owner`), and `clone_families`. SARIF results carry `properties.group`, CodeClimate issues a top-level `group` field. Compact and markdown fall back to ungrouped with a stderr note. |
 
 ### Detection Modes
 
@@ -244,16 +250,16 @@ Creates a config file in the project root.
 | Flag | Type | Description |
 |------|------|-------------|
 | `--toml` | bool | Create `fallow.toml` instead of `.fallowrc.json` |
-| `--hooks` | bool | Scaffold a pre-commit git hook that runs `fallow dead-code --changed-since` on staged files |
-| `--branch` | string | Base branch for the pre-commit hook (default: auto-detected or `main`). Only used with `--hooks` |
+| `--hooks` | bool | Scaffold a pre-commit git hook that runs `fallow audit --base <ref> --quiet`. Alias for `fallow hooks install --target git` |
+| `--branch` | string | Fallback base branch for the pre-commit hook when no upstream is set (default: `main`). Only used with `--hooks` |
 
 ### Examples
 
 ```bash
 fallow init              # creates .fallowrc.json with $schema
 fallow init --toml       # creates fallow.toml
-fallow init --hooks      # scaffold a pre-commit git hook (auto-detects base branch)
-fallow init --hooks --branch develop  # hook using custom base branch
+fallow hooks install --target git
+fallow hooks install --target git --branch develop  # fallback base branch when no upstream is set
 ```
 
 ---
@@ -296,38 +302,41 @@ fallow migrate --from knip.jsonc
 
 Analyzes function complexity across the project using cyclomatic and cognitive complexity metrics. By default all sections are included (health score, complexity findings, file scores, hotspots, and refactoring targets). Use `--complexity`, `--file-scores`, `--hotspots`, `--targets`, or `--score` to show only specific sections.
 
+Angular templates contribute synthetic `<template>` complexity findings whenever they use `@if`/`@for`/`@switch`/`@case`/`@defer (when ...)`/`@let` blocks, legacy structural directives (`*ngIf`, `*ngFor`), bound attributes (`[x]`, `(x)`, `bind-x`, `on-x`), or `{{ }}` interpolations. Both standalone external `.html` files referenced via `templateUrl` AND inline `@Component({ template: \`...\` })` literals are scanned. Inline-template findings anchor at the host `.ts` file's `@Component` decorator line and emit a `suppress-line` action with `// fallow-ignore-next-line complexity` (place the comment directly above the `@Component` decorator). External-template findings emit a `suppress-file` action with `<!-- fallow-ignore-file complexity -->` (place at the top of the `.html` file; HTML cannot express line-level comments). Tagged template literals containing `${...}` interpolations and `template:` properties bound to a variable are skipped (out of scope for the first cut).
+
 ### Flags
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
-| `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality\|badge` | `human` | Output format |
+| `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality\|pr-comment-github\|pr-comment-gitlab\|review-github\|review-gitlab\|badge` | `human` | Output format |
 | `--quiet` | bool | `false` | Suppress progress bars |
 | `--max-cyclomatic` | number | `20` | Fail if any function exceeds this cyclomatic complexity |
 | `--max-cognitive` | number | `15` | Fail if any function exceeds this cognitive complexity |
 | `--max-crap` | number | `30.0` | Fail if any function has CRAP score >= threshold. CRAP combines complexity with coverage (`CC^2 * (1 - cov/100)^3 + CC`). Pair with `--coverage` for accurate per-function CRAP; without Istanbul data fallow estimates coverage from the module graph. |
 | `--top` | number | — | Only show the top N most complex functions (and file scores/hotspots/targets) |
-| `--sort` | `cyclomatic\|cognitive\|lines` | `cyclomatic` | Sort order for complexity findings |
+| `--sort` | `cyclomatic\|cognitive\|lines\|severity` | `cyclomatic` | Sort order for complexity findings |
 | `--complexity` | bool | `false` | Show only function complexity findings. When no section flags are set, all sections are shown by default. |
 | `--file-scores` | bool | `false` | Show only per-file maintainability index (LOC, fan-in, fan-out, dead code ratio, complexity density). Runs the full analysis pipeline. When no section flags are set, all sections are shown by default. |
 | `--hotspots` | bool | `false` | Show only hotspots: files that are both complex and frequently changing. Combines git churn history with complexity data. Requires a git repository. When no section flags are set, all sections are shown by default. |
 | `--targets` | bool | `false` | Show only refactoring targets: ranked recommendations based on complexity, coupling, churn, and dead code signals. Categories: churn+complexity, circular dep, high impact, dead code, complexity, coupling. When no section flags are set, all sections are shown by default. |
 | `--effort` | `low\|medium\|high` | — | Filter refactoring targets by effort level. Implies `--targets`. |
-| `--score` | bool | `false` | Show only the project health score (0-100) with letter grade (A/B/C/D/F). The score is included by default when no section flags are set. JSON includes `health_score` object with `score`, `grade`, and `penalties` breakdown. |
+| `--score` | bool | `false` | Show only the project health score (0-100) with letter grade (A/B/C/D/F). The score is included by default when no section flags are set. JSON includes `health_score` object with `score`, `grade`, and `penalties` breakdown. As of v2.55.0, plain `--score` skips the churn-backed hotspot penalty so it does not run a `git log` shell-out per invocation; pass `--hotspots` (or `--targets` with `--score`) to include the hotspot penalty. Snapshot (`--save-snapshot`) and trend (`--trend`) flows still trigger hotspot vital signs so saved data stays complete. |
 | `--min-score` | number | — | Fail if health score is below this threshold (exit code 1). Implies `--score`. CI quality gate. |
 | `--since` | string | `6m` | Git history window for hotspot analysis. Accepts durations (`6m`, `90d`, `1y`, `2w`) or ISO dates (`2025-06-01`). |
 | `--min-commits` | number | `3` | Minimum number of commits for a file to be included in hotspot ranking. |
 | `--ownership` | bool | `false` | Attach ownership signals to hotspot entries: bus factor (Avelino truck factor), contributor count, top contributor with stale-days, recent contributors (top-3), `suggested_reviewers`, declared CODEOWNERS owner, ownership drift, unowned-hotspot detection. Human output gains a project-level summary line. JSON adds `low-bus-factor`, `unowned-hotspot`, `ownership-drift` action types. Test files get a `[test]` tag. Implies `--hotspots`. Requires git. |
 | `--ownership-emails` | `raw\|handle\|hash` | `handle` | Privacy mode for author emails. `handle` shows the local-part only (default, with GitHub noreply unwrap). `hash` emits stable `xxh3:` pseudonyms. `raw` shows full addresses. Use `hash` in regulated environments. Implies `--ownership`. Configure default via `health.ownership.emailMode`. |
 | `--changed-since` | string | — | Only analyze files changed since a git ref |
-| `--workspace` | string | — | Scope to one or more workspaces. Comma-separated values, globs (`apps/*`, `@scope/*`), and `!`-prefixed negation (`!apps/legacy`) supported. Matched against package name AND workspace path relative to repo root. |
-| `--baseline` | path | — | Compare against a saved baseline |
-| `--save-baseline` | path | — | Save current results as a baseline |
+| `--workspace` | string | — | Scope to one or more workspaces. Comma-separated values, globs (`apps/*`, `@scope/*`), and `!`-prefixed negation (`!apps/legacy`) supported. Matched against package name AND workspace path relative to repo root. Vital signs, health score, hotspots, file scores, findings, and `summary.files_analyzed` are all recomputed against the scoped subset. |
+| `--group-by` | `owner\|directory\|package\|section` | — | Partition the report into per-group sections. JSON adds `grouped_by` plus a `groups` array; each group contains its own `vital_signs`, `health_score`, `findings`, `file_scores`, `hotspots`, `large_functions`, and `targets` recomputed against the group's files. The top-level metrics stay project-wide so consumers that ignore grouping still see the project headline. Human output adds a per-group score / files / hot / p90 summary block (sorted worst-first when `--score`). SARIF results carry `properties.group` and CodeClimate issues carry a top-level `group` field so GitHub Code Scanning / GitLab Code Quality can partition per team / package. Compact, markdown, and badge fall back to ungrouped output with a stderr note. |
+| `--baseline` | path | — | Compare against a saved baseline. When set, the JSON `actions` array on each finding omits `suppress-line` (the baseline already suppresses) and the report root carries an `actions_meta: { suppression_hints_omitted: true, reason: "baseline-active" }` breadcrumb. |
+| `--save-baseline` | path | — | Save current results as a baseline. Same `suppress-line` omission as `--baseline`. |
 | `--save-snapshot` | path (optional) | `.fallow/snapshots/<timestamp>.json` | Save vital signs snapshot for trend tracking. Forces file-scores + hotspot computation. |
 | `--trend` | bool | `false` | Compare current metrics against the most recent saved snapshot. Reads from `.fallow/snapshots/` and shows per-metric deltas with directional indicators (improving/declining/stable). Implies `--score`. |
 | `--coverage-gaps` | bool | `false` | Show runtime files and exports that no test dependency path reaches. Opt-in (default off). Configure severity via the `coverage-gaps` rule (`error`/`warn`/`off`). |
-| `--coverage` | path | none | Path to Istanbul-format coverage data (`coverage-final.json`) for accurate per-function CRAP scores. Uses `CC^2 * (1-cov/100)^3 + CC` instead of static binary model. |
-| `--coverage-root` | path | none | Rebase file paths in coverage data by stripping this prefix and prepending the project root. For CI/Docker environments where coverage was generated with different absolute paths. |
-| `--runtime-coverage` | path | none | Merge runtime runtime-coverage input into the health report (paid feature). Accepts a V8 coverage directory (`NODE_V8_COVERAGE=...`), a single V8 coverage JSON file, or an Istanbul `coverage-final.json`. Requires an active license; start one with `fallow license activate --trial --email <addr>`. JSON output gains a `runtime_coverage` object with a top-level report verdict, per-finding `verdict` (`safe_to_delete` / `review_required` / `low_traffic` / `coverage_unavailable` / `active`), stable content-hash IDs (`fallow:prod:<hash>`), evidence block, and percentile-ranked hot paths. On protocol-0.3+ sidecars the `summary` also carries an optional `capture_quality` block (`window_seconds`, `instances_observed`, `lazy_parse_warning`, `untracked_ratio_percent`) that flags short-window captures where lazy-parsed scripts may not appear. |
+| `--coverage` | path | none | Path to Istanbul-format coverage data (`coverage-final.json`) for accurate per-function CRAP scores. Uses `CC^2 * (1-cov/100)^3 + CC` instead of static binary model. Relative paths resolve against `--root`. |
+| `--coverage-root` | path | none | Absolute prefix to strip from file paths in coverage data before prepending the project root. For CI/Docker environments where coverage was generated with different absolute paths. |
+| `--runtime-coverage` | path | none | Merge runtime-coverage input into the health report. Accepts a V8 coverage directory (`NODE_V8_COVERAGE=...`), a single V8 coverage JSON file, or an Istanbul `coverage-final.json`. One local capture is free and does not require a license; continuous/cloud or multi-capture runtime monitoring requires an active license or trial (`fallow license activate --trial --email <addr>`). JSON output gains a `runtime_coverage` object with a top-level report verdict, per-finding `verdict` (`safe_to_delete` / `review_required` / `low_traffic` / `coverage_unavailable` / `active`), stable content-hash IDs (`fallow:prod:<hash>`), evidence block, and percentile-ranked hot paths. On protocol-0.3+ sidecars the `summary` also carries an optional `capture_quality` block (`window_seconds`, `instances_observed`, `lazy_parse_warning`, `untracked_ratio_percent`) that flags short-window captures where lazy-parsed scripts may not appear. |
 | `--min-invocations-hot` | number | `100` | Invocation threshold for hot-path classification. Takes effect only when `--runtime-coverage` is set. |
 | `--min-observation-volume` | number | `5000` | Minimum total trace volume before the sidecar may emit high-confidence `safe_to_delete` / `review_required` verdicts. Below this, confidence is capped at `medium`. |
 | `--low-traffic-threshold` | number | `0.001` | Fraction of total trace count below which an invoked function is classified `low_traffic` rather than `active`. Expressed as a decimal (0.001 = 0.1%). |
@@ -415,7 +424,7 @@ fallow health --format json --quiet --trend
 ```json
 {
   "schema_version": 3,
-  "version": "2.47.0",
+  "version": "2.69.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -569,17 +578,23 @@ All `health` JSON output includes a `vital_signs` object with project-wide metri
     "dead_file_pct": 3.2,
     "dead_export_pct": 8.1,
     "avg_cyclomatic": 4.5,
+    "critical_complexity_pct": 1.2,
     "p90_cyclomatic": 12,
     "maintainability_avg": 88.5,
+    "maintainability_low_pct": 4.1,
     "hotspot_count": 7,
+    "hotspot_top_pct_count": 3,
     "circular_dep_count": 2,
+    "circular_deps_per_k_files": 4.1,
     "unused_dep_count": 3,
+    "unused_deps_per_k_files": 6.2,
     "unit_size_profile": {
       "low_risk": 82.1,
       "medium_risk": 11.4,
       "high_risk": 4.3,
       "very_high_risk": 2.2
     },
+    "functions_over_60_loc_per_k": 22.0,
     "unit_interfacing_profile": {
       "low_risk": 95.6,
       "medium_risk": 3.8,
@@ -592,13 +607,14 @@ All `health` JSON output includes a `vital_signs` object with project-wide metri
 }
 ```
 
-Fields are `null` when the corresponding data source is not available (e.g., `hotspot_count` is null without `--hotspots` or when git is not available). The `unit_size_profile` and `unit_interfacing_profile` are risk distribution histograms (low risk / medium risk / high risk / very high risk as percentages). `p95_fan_in` is the 95th percentile of incoming dependencies. `coupling_high_pct` is the percentage of files above the effective coupling threshold.
+Fields are `null` when the corresponding data source is not available (e.g., `hotspot_count` is null without `--hotspots` or when git is not available). Health score formula v2 also uses scale-invariant density/tail fields: `critical_complexity_pct`, `hotspot_top_pct_count`, `maintainability_low_pct`, `unused_deps_per_k_files`, `circular_deps_per_k_files`, and `functions_over_60_loc_per_k`. The `unit_size_profile` and `unit_interfacing_profile` are risk distribution histograms (low risk / medium risk / high risk / very high risk as percentages). `p95_fan_in` is the 95th percentile of incoming dependencies. `coupling_high_pct` is the percentage of files above the effective coupling threshold.
 
 With `--score`, the JSON output includes a `health_score` object:
 
 ```json
 {
   "health_score": {
+    "formula_version": 2,
     "score": 76.9,
     "grade": "B",
     "penalties": {
@@ -607,7 +623,6 @@ With `--score`, the JSON output includes a `health_score` object:
       "complexity": 0.0,
       "p90_complexity": 0.0,
       "maintainability": 0.0,
-      "hotspots": 0.0,
       "unused_deps": 10.0,
       "circular_deps": 4.0,
       "unit_size": 0.0,
@@ -618,7 +633,7 @@ With `--score`, the JSON output includes a `health_score` object:
 }
 ```
 
-Score is reproducible: `100 - sum(penalties) == score`. Penalty fields are absent when the pipeline didn't run. `--score` automatically runs duplication analysis. Grades: A (>= 85), B (70-84), C (55-69), D (40-54), F (< 40).
+Score is reproducible: `100 - sum(penalties) == score`. `formula_version` identifies the scoring formula; version 2 uses scale-invariant density and tail metrics for monorepo-safe scoring. Penalty fields are absent when the pipeline didn't run. `--score` automatically runs duplication analysis; add `--hotspots` (or combine `--score --targets`) when the score should include the churn-backed hotspot penalty. Grades: A (>= 85), B (70-84), C (55-69), D (40-54), F (< 40).
 
 ### Health Trend
 
@@ -661,7 +676,7 @@ With `--trend`, the JSON output includes a `health_trend` object comparing curre
 }
 ```
 
-Metrics tracked: `score`, `dead_file_pct`, `dead_export_pct`, `avg_cyclomatic`, `maintainability_avg`, `unused_dep_count`, `circular_dep_count`, `hotspot_count`, `unit_size_very_high_pct`, `p95_fan_in`, `duplication_pct`. Each metric includes `direction` (`improving`, `declining`, `stable`). Percentage metrics include `previous_count`/`current_count` with raw numerator/denominator. `--trend` requires at least one saved snapshot in `.fallow/snapshots/`. When comparing against a snapshot from an older schema version (current: v5), the trend output warns that score deltas may reflect formula changes.
+Metrics tracked: `score`, `dead_file_pct`, `dead_export_pct`, `avg_cyclomatic`, `maintainability_avg`, `unused_dep_count`, `circular_dep_count`, `hotspot_count`, `unit_size_very_high_pct`, `p95_fan_in`, `duplication_pct`. Each metric includes `direction` (`improving`, `declining`, `stable`). Percentage metrics include `previous_count`/`current_count` with raw numerator/denominator. `--trend` requires at least one saved snapshot in `.fallow/snapshots/`. When comparing against a snapshot from an older schema version (current: v8), the trend output warns that score deltas may reflect formula changes.
 
 ### Vital Signs Snapshots
 
@@ -669,17 +684,23 @@ Metrics tracked: `score`, `dead_file_pct`, `dead_export_pct`, `avg_cyclomatic`,
 
 ```json
 {
-  "schema_version": 5,
+  "snapshot_schema_version": 8,
   "timestamp": "2025-12-01T10:30:00Z",
   "vital_signs": {
     "dead_file_pct": 3.2,
     "dead_export_pct": 8.1,
     "avg_cyclomatic": 4.5,
+    "critical_complexity_pct": 1.2,
     "p90_cyclomatic": 12,
     "maintainability_avg": 88.5,
+    "maintainability_low_pct": 4.1,
     "hotspot_count": 7,
+    "hotspot_top_pct_count": 3,
     "circular_dep_count": 2,
-    "unused_dep_count": 3
+    "circular_deps_per_k_files": 4.1,
+    "unused_dep_count": 3,
+    "unused_deps_per_k_files": 6.2,
+    "functions_over_60_loc_per_k": 22.0
   },
   "counts": {
     "total_files": 482,
@@ -695,19 +716,20 @@ Metrics tracked: `score`, `dead_file_pct`, `dead_export_pct`, `avg_cyclomatic`,
 }
 ```
 
-The snapshot `schema_version` is independent of the report `schema_version`. Default path: `.fallow/snapshots/<timestamp>.json`. The `--save-snapshot` flag forces file-scores and hotspot computation to populate all vital signs fields.
+The snapshot `snapshot_schema_version` is independent of the report `schema_version`. Default path: `.fallow/snapshots/<timestamp>.json`. The `--save-snapshot` flag forces file-scores and hotspot computation to populate all vital signs fields.
 
 ---
 
 ## `audit`: Changed-File Quality Gate
 
-Audits changed files for dead code, complexity, and duplication. Returns a verdict (pass/warn/fail). Purpose-built for PR quality gates and reviewing AI-generated code. Auto-detects the base branch if `--base` is not set.
+Audits changed files for dead code, complexity, and duplication. Returns a verdict (pass/warn/fail). Purpose-built for PR quality gates and reviewing AI-generated code. Auto-detects the base branch if `--base` is not set. Defaults to `--gate new-only`, which fails only on findings introduced by the current changeset and reports inherited findings as context.
 
 ### Flags
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
 | `--base` | string | auto-detect | Git ref to compare against (alias for `--changed-since`) |
+| `--gate` | `new-only\|all` | `new-only` | Which findings affect the verdict. `new-only` gates only introduced findings; `all` gates every finding in changed files and skips the extra base-snapshot attribution pass. |
 | `--production` | bool | false | Exclude test/story/dev files (applies to dead-code, health, and dupes) |
 | `--production-dead-code` | bool | false | Per-analysis production mode for the dead-code sub-analysis only |
 | `--production-health` | bool | false | Per-analysis production mode for the health sub-analysis only |
@@ -721,6 +743,8 @@ Audits changed files for dead code, complexity, and duplication. Returns a verdi
 | `--health-baseline` | path | — | Baseline file (produced by `fallow health --save-baseline`). Pre-existing complexity findings are excluded from the verdict. |
 | `--dupes-baseline` | path | — | Baseline file (produced by `fallow dupes --save-baseline`). Pre-existing clone groups are excluded from the verdict. |
 | `--max-crap` | number | `30.0` | Forwarded to the health sub-analysis. Functions meeting or exceeding this CRAP score cause audit to fail. Same formula as `health --max-crap`. Pair with coverage data for accurate per-function CRAP. |
+| `--coverage` | path | none | Path to Istanbul-format coverage data (`coverage-final.json`) for accurate per-function CRAP scores in the health sub-analysis. Same format and semantics as `health --coverage`. Also configurable via `FALLOW_COVERAGE`. Relative paths resolve against `--root`. |
+| `--coverage-root` | path | none | Absolute prefix to strip from file paths in coverage data before prepending the project root. Use when coverage was generated under a different checkout root in CI / Docker (e.g., `/home/runner/work/myapp` on GitHub Actions). |
 | `--fail-on-regression` | bool | false | Fail if issues increased beyond tolerance vs regression baseline |
 | `--tolerance` | string | `0` | Allowed increase before regression fails (`N` or `N%`) |
 | `--regression-baseline` | path | `.fallow/regression-baseline.json` | Path to the regression baseline file |
@@ -735,6 +759,19 @@ Audits changed files for dead code, complexity, and duplication. Returns a verdi
 | fail | 1 | Error-severity issues found |
 | error | 2 | Runtime error (invalid ref, not a git repo) |
 
+With `--gate new-only`, inherited error-severity findings can be present in the JSON output while the verdict remains `pass`; check the `attribution` object and per-finding `introduced` booleans.
+
+### JSON contract: which fields are severity-aware
+
+| Field | Severity-aware? | What it counts |
+|-------|-----------------|----------------|
+| `verdict` | **yes** | Overall outcome honoring per-rule severity (`pass` / `warn` / `fail`) |
+| `attribution.*_introduced` | no | Findings introduced by the changeset under `gate: new-only`, ignoring severity |
+| `summary.*` | no | All findings in changed files, ignoring severity |
+| Per-finding `introduced` | no | Whether each finding was introduced by the changeset |
+
+For CI gating and any "did this PR pass?" question, read `verdict` (or exit code). Counting introduced findings ignores severity and breaks projects with `unused-exports: warn`. For agent triage, read `verdict` first, then `attribution` for new-vs-inherited counts, then the per-category finding arrays for actionable details.
+
 ### Examples
 
 ```bash
@@ -747,6 +784,9 @@ fallow audit --format json --quiet --base main
 # Audit last 3 commits
 fallow audit --format json --quiet --base HEAD~3
 
+# Strict mode: fail on inherited findings too
+fallow audit --format json --quiet --gate all
+
 # Production code only in a monorepo workspace
 fallow audit --format json --quiet --production --workspace @app/api
 
@@ -770,7 +810,7 @@ fallow audit \
 ```json
 {
   "schema_version": 3,
-  "version": "2.47.0",
+  "version": "2.69.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -784,10 +824,19 @@ fallow audit \
     "max_cyclomatic": 28,
     "duplication_clone_groups": 0
   },
+  "attribution": {
+    "gate": "new-only",
+    "dead_code_introduced": 2,
+    "dead_code_inherited": 0,
+    "complexity_introduced": 1,
+    "complexity_inherited": 0,
+    "duplication_introduced": 0,
+    "duplication_inherited": 0
+  },
   "dead_code": {
     "schema_version": 3,
     "total_issues": 2,
-    "unused_exports": [...]
+    "unused_exports": [{ "path": "src/api.ts", "export_name": "oldApi", "introduced": true, "actions": [...] }]
   },
   "complexity": {
     "findings": [...]
@@ -798,7 +847,9 @@ fallow audit \
 }
 ```
 
-The `verdict` field is always present and is the primary decision signal. Dead code, complexity, and duplication sections follow their respective schemas from the individual commands. Thresholds for complexity are inherited from `fallow health` config (defaults: cyclomatic 20, cognitive 15).
+The `verdict` field is always present and is the primary decision signal. With the default `new-only` gate, the `attribution` object counts introduced vs inherited findings and audit sub-results annotate individual findings with `introduced: true/false`. With `gate=all`, audit skips that extra base-snapshot attribution pass, so introduced/inherited counts stay `0` and per-finding `introduced` fields are omitted. Dead code, complexity, and duplication sections follow their respective schemas from the individual commands. Thresholds for complexity are inherited from `fallow health` config (defaults: cyclomatic 20, cognitive 15).
+
+Audit creates a temporary git worktree to compare against the base ref. When the current checkout has `node_modules`, audit links it into the base worktree so tsconfig `extends` chains into installed packages and path aliases resolve like the working tree. The worktree is removed on normal exit. If the process is force-killed, run `git worktree prune` to clean up stale `.git/worktrees/fallow-audit-base-*` entries.
 
 ---
 
@@ -810,7 +861,7 @@ Detects feature flag patterns in the codebase. Identifies environment variable f
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
-| `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality` | `human` | Output format |
+| `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality\|pr-comment-github\|pr-comment-gitlab\|review-github\|review-gitlab` | `human` | Output format |
 | `--quiet` | bool | `false` | Suppress progress bars |
 | `--top` | number | — | Show only the top N flags |
 
@@ -832,7 +883,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 3,
-  "version": "2.47.0",
+  "version": "2.69.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -841,6 +892,41 @@ fallow flags --format json --quiet --workspace my-package
 
 ---
 
+## `explain`: Rule Explanation
+
+Print rule rationale, examples, fix guidance, and docs URL for one issue type without running analysis.
+
+### Usage
+
+```bash
+fallow explain unused-export
+fallow explain fallow/code-duplication --format json --quiet
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<issue-type>` | Issue type token or rule id, for example `unused-export`, `unused-exports`, `fallow/unused-dependency`, `high-complexity`, or `code-duplication`. |
+
+### JSON Output Structure
+
+```json
+{
+  "id": "fallow/unused-export",
+  "name": "Unused Exports",
+  "summary": "Export is never imported",
+  "rationale": "Named exports that are never imported by any other module in the project. Includes both direct exports and re-exports through barrel files. The export may still be used locally within the same file.",
+  "example": "export const formatPrice = ... exists in src/money.ts, but no module imports formatPrice.",
+  "how_to_fix": "Remove the export or make it file-local. If it is public API, import it from an entry point or add an intentional suppression with context.",
+  "docs": "https://docs.fallow.tools/explanations/dead-code#unused-exports"
+}
+```
+
+MCP equivalent: `fallow_explain` with required `issue_type`.
+
+---
+
 ## `schema`: CLI Introspection
 
 Dumps the full CLI interface definition as machine-readable JSON.
@@ -871,9 +957,9 @@ fallow plugin-schema > plugin-schema.json
 
 ---
 
-## `license`: Manage Paid-Feature License
+## `license`: Manage Continuous Runtime License
 
-Manage the local JWT used to unlock paid features (Phase 2 runtime coverage). Verification is fully offline against an Ed25519 public key compiled into the binary. Only `--trial` and `refresh` hit the network (`api.fallow.cloud`, 5s connect / 10s total timeout).
+Manage the local JWT used to unlock continuous/cloud runtime monitoring. Single-capture local runtime analysis does not require a license. Verification is fully offline against an Ed25519 public key compiled into the binary. Only `--trial` and `refresh` hit the network (`api.fallow.cloud`, 5s connect / 10s total timeout).
 
 ```bash
 fallow license activate --trial --email you@company.com
@@ -915,7 +1001,7 @@ fallow license deactivate
 |-----------------|-------|----------|
 | `<= 7` | ExpiredWarning | Analysis runs; CLI prints a refresh hint |
 | `> 7, <= 30` | ExpiredWatermark | Analysis runs; output gains a visible watermark until refreshed |
-| `> 30` | HardFail | Paid features blocked; run `fallow license refresh` or start a new trial |
+| `> 30` | HardFail | Continuous/cloud runtime monitoring is blocked; run `fallow license refresh` or start a new trial |
 
 ### Actionable error messages
 
@@ -943,9 +1029,9 @@ Unknown codes fall back to the backend's `message` field, or the raw body.
 
 ## `coverage`: Production-Coverage Workflow
 
-Helper subcommand for the runtime-coverage workflow. Three subcommands today:
+Helper subcommand for runtime coverage setup, focused analysis, and cloud inventory upload. Three subcommands today:
 
-- `coverage setup` — resumable state machine that wires license activation, sidecar installation, framework-aware coverage recipe writing, and automatic handoff into `fallow health --runtime-coverage`.
+- `coverage setup` — resumable state machine that wires sidecar installation, framework-aware coverage recipe writing, optional license activation for continuous monitoring, and automatic handoff into `fallow health --runtime-coverage`.
 - `coverage analyze` — focused runtime coverage analysis. Local mode reads `--runtime-coverage <path>`; cloud mode requires explicit `--cloud`, `--runtime-coverage-cloud`, or `FALLOW_RUNTIME_COVERAGE_SOURCE=cloud` and never triggers from `FALLOW_API_KEY` alone.
 - `coverage upload-inventory` — push a static function inventory to fallow cloud so the dashboard can surface `untracked` functions (those in the codebase but never called at runtime).
 
@@ -953,37 +1039,53 @@ Helper subcommand for the runtime-coverage workflow. Three subcommands today:
 fallow coverage setup                         # interactive
 fallow coverage setup --yes                   # accept all prompts
 fallow coverage setup --non-interactive       # print instructions, do not prompt
+fallow coverage setup --yes --json            # agent-readable JSON, no prompts/writes/installs/network
+fallow coverage setup --yes --json --explain  # add _meta field docs, enums, warnings, docs URL
 
 fallow coverage analyze --runtime-coverage ./coverage --format json
 fallow coverage analyze --cloud --repo owner/repo --format json
 
 fallow coverage upload-inventory              # infers project-id, git-sha, API key
 fallow coverage upload-inventory --dry-run    # print what would be uploaded, exit 0
+
+fallow coverage upload-source-maps --dir dist           # upload build source maps from CI
+fallow coverage upload-source-maps --dry-run            # print maps and fileName values, no network
 ```
 
+`--json` is the agent-driven entry point: implies `--non-interactive`, never writes files, never installs the sidecar, never makes network calls, and produces a stable JSON payload with these top-level keys: `schema_version` (string `"1"`), `framework_detected`, `package_manager`, `runtime_targets`, `members`, `config_written`, `commands`, `files_to_edit`, `snippets`, `dockerfile_snippet`, `next_steps`, `warnings`. Add `--explain` to inject an opt-in `_meta` block with field definitions, enum values, warning semantics, and the docs URL; `schema_version` stays `"1"`. `framework_detected` uses canonical ids (`nextjs`, `nestjs`, `nuxt`, `sveltekit`, `astro`, `remix`, `vite`, `plain_node`, `unknown`). When both a Node-server framework (Elysia, Hono, Fastify, Express, Koa, `@trpc/server`) and Vite appear in the same `package.json`, the Node-server framework wins. Workspace projects emit one `members[]` entry per runtime-bearing workspace (each with its own `framework_detected`, `package_manager`, `runtime_targets`, `files_to_edit`, `snippets`, `dockerfile_snippet`, `warnings`); top-level fields mirror the first emitted runtime member, and `runtime_targets` at top level is the union (`[]`, `["node"]`, `["browser"]`, or `["node", "browser"]`) across all members. Single-app projects emit a `members[]` array of length 1 (path `"."`) so consumers can treat it uniformly. Library-only workspaces (no `start`/`preview`/`dev` script and no Node-server dependency) are skipped, as are aggregator roots whose only `dev` / `preview` script delegates to a tool other than vite (e.g., `turbo dev`, `nx run-many`); when no runtime members are found, the payload reports `framework_detected: "unknown"`, `runtime_targets: []`, `members: []`, and a `warnings` entry of `"No runtime workspace members were detected; emitted install commands only."`. A Vite browser app is recognized when `vite` is a dependency AND either a `dev`/`preview` script invokes `vite` (or `vite-preview` / `vite-plus` / `vp`) OR the workspace contains an `index.html` or `src/main.{ts,tsx,js,jsx,mts,mjs}` entry.
+
+### `setup` flow
+
+1. **License check** — if missing or hard-fail, offers to start a trial.
+2. **Sidecar discovery** — resolves `FALLOW_COV_BIN`, `FALLOW_COV_BINARY_PATH`, platform-package binaries in npm/bun/pnpm layouts, project-local `node_modules/.bin/fallow-cov`, package-manager bin, `~/.fallow/bin/fallow-cov`, and `PATH`. When an explicit env path is set but points to a non-existent file, setup errors fast instead of falling through.
+3. **Coverage recipe** — detects framework (Next.js, Nuxt, Astro, SvelteKit, Remix, NestJS, Vite browser apps, plain Node) and package manager (npm, pnpm, yarn, bun), then writes `docs/collect-coverage.md` with the correct commands.
+4. **Handoff** — if `./coverage/coverage-final.json` or a V8 coverage directory already exists, setup runs `fallow health --runtime-coverage <path>` directly.
+
 ### `analyze` flags
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
 | `--runtime-coverage <PATH>` | path | none | Local V8 directory, V8 JSON file, or Istanbul coverage map. Mutually exclusive with cloud mode. |
 | `--cloud`, `--runtime-coverage-cloud` | bool | false | Explicitly fetch cloud runtime facts from `/v1/coverage/:repo/runtime-context`. |
-| `--repo <OWNER/REPO>` | string | `$FALLOW_REPO` → `git remote get-url origin` | Repository identifier for cloud mode. Encoded as one URL path segment (`owner%2Frepo`). |
-| `--api-key <KEY>` | string | `$FALLOW_API_KEY` | Fallow cloud bearer token for cloud mode. The env var alone does not opt in to cloud mode. |
+| `--api-key <KEY>` | string | `$FALLOW_API_KEY` | Fallow cloud bearer token, used only after explicit cloud opt-in. |
 | `--api-endpoint <URL>` | string | `$FALLOW_API_URL` or `https://api.fallow.cloud` | Override for staging / on-prem. |
+| `--repo <OWNER/REPO>` | string | `$FALLOW_REPO`, then parsed git origin | Repository whose latest cloud runtime facts should be pulled. Slashes are percent-encoded as one route segment. |
 | `--coverage-period <DAYS>` | integer | 30 | Cloud observation window, 1 through 90 days. |
-| `--project-id <ID>` | string | none | Optional monorepo/project disambiguator. |
-| `--environment <ENV>` | string | none | Optional cloud environment filter. |
-| `--commit-sha <SHA>` | string | none | Optional cloud commit filter. |
-| `--production` | bool | false | Analyze production code only before joining cloud facts. |
+| `--project-id <ID>` | string | none | Optional project discriminator for monorepos. |
+| `--environment <NAME>` | string | none | Optional environment filter. |
+| `--commit-sha <SHA>` | string | none | Optional advanced filter for a specific observed commit. |
+| `--top <N>` | integer | unset | Show only the top N runtime findings, hot paths, blast-radius entries, and importance entries. Truncation happens before rendering, so it propagates to JSON, human, and cloud-merge output equally. |
+| `--blast-radius` | bool | false | Show the first-class blast-radius section in human output. JSON always includes `runtime_coverage.blast_radius` whenever runtime coverage analysis runs. |
+| `--importance` | bool | false | Show the first-class importance section in human output. JSON always includes `runtime_coverage.importance` whenever runtime coverage analysis runs. |
+| `--production` | bool | false | Run analyze in production mode, matching `fallow health --production`. Filters out test files and dev-only code paths before merging runtime data. |
+| `--min-invocations-hot <N>` | integer | 100 | Hot-path classification threshold. Functions invoked at least N times during the captured window are classified as hot. Mirrors the same flag on `fallow health --runtime-coverage`. |
+| `--min-observation-volume <N>` | integer | 5000 | Minimum total trace volume before the sidecar emits high-confidence `safe_to_delete` / `review_required` verdicts. Below this, confidence is capped at `medium`. |
+| `--low-traffic-threshold <RATIO>` | decimal | 0.001 | Fraction of total trace count below which an invoked function is classified `low_traffic` rather than `active`. `0.001` = 0.1%. |
+| `--explain` | bool | false | With `--format json`, attach a top-level `_meta` block with field definitions, enum values (`data_source`, `test_coverage`, `v8_tracking`, `action_type`, etc.), warning-code documentation, and the docs URL. |
 
 Cloud analysis emits the same `runtime_coverage` JSON block as local mode. Its summary includes `data_source: "cloud"`, `last_received_at`, and `capture_quality` derived from the pulled runtime window. Cloud functions that cannot be matched to the local AST/static index are omitted from findings and reported through a `cloud_functions_unmatched` warning.
 
-### `setup` flow
-
-1. **License check** — if missing or hard-fail, offers to start a trial.
-2. **Sidecar discovery** — resolves `FALLOW_COV_BIN`, project-local `node_modules/.bin/fallow-cov`, package-manager bin, `~/.fallow/bin/fallow-cov`, and `PATH`. When `FALLOW_COV_BIN` is set but points to a non-existent file, setup errors fast instead of falling through.
-3. **Coverage recipe** — detects framework (Next.js, Nuxt, Astro, SvelteKit, Remix, NestJS, plain Node) and package manager (npm, pnpm, yarn, bun), then writes `docs/collect-coverage.md` with the correct commands.
-4. **Handoff** — if `./coverage/coverage-final.json` or a V8 coverage directory already exists, setup runs `fallow health --runtime-coverage <path>` directly.
+Each finding's `actions[].type` uses the canonical kebab-case vocabulary: `delete-cold-code` is emitted on `verdict=safe_to_delete`, `review-runtime` on `verdict=review_required`. The sidecar may emit additional protocol-specific identifiers, so consumers should treat unknown values as forward-compat extensions rather than schema violations.
 
 ### `upload-inventory` flags
 
@@ -1004,9 +1106,26 @@ Only plain JS/TS/JSX/TSX sources are walked. Declaration files (`*.d.ts`, `*.d.m
 ### Environment
 
 - `FALLOW_COV_BIN` — explicit override for the sidecar binary (for `setup`). Wins over all other discovery paths. Must point to an existing file.
-- `FALLOW_API_KEY` — fallow cloud bearer token (for `upload-inventory`). Overridden by `--api-key`.
+- `FALLOW_API_KEY` — fallow cloud bearer token (for `upload-inventory` and `upload-source-maps`). Overridden by `--api-key` for `upload-inventory`; `upload-source-maps` reads only the env var so secrets stay out of argv.
 - `FALLOW_API_URL` — base URL for cloud calls. Overridden by `--api-endpoint`.
 
+### `coverage upload-source-maps` flags
+
+Coverage CI helper for bundled/minified runtime coverage. It scans a build directory for `.map` files and uploads them to `/v1/coverage/:repo/source-maps` keyed by the commit SHA the beacon reports.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--dir <PATH>` | path | `dist` | Directory scanned recursively. |
+| `--include <GLOB>` | glob | `**/*.map` | Include glob relative to `--dir`. |
+| `--exclude <GLOB>` | glob | `**/node_modules/**` | Exclude glob, repeatable. |
+| `--repo <NAME>` | string | `package.json` `repository.url`, then `git remote get-url origin` | Repo name used in the source-map API path. |
+| `--git-sha <SHA>` | string | `$GITHUB_SHA` -> `$CI_COMMIT_SHA` -> `$COMMIT_SHA` -> `git rev-parse HEAD` | Commit SHA, 7-40 hex chars. |
+| `--endpoint <URL>` | string | `$FALLOW_API_URL` or `https://api.fallow.cloud` | Override for staging / on-prem. |
+| `--strip-path <BOOL>` | bool | `true` | Upload basename-only `fileName` values. Use `--strip-path=false` when runtime coverage reports paths like `assets/app.js`. |
+| `--dry-run` | bool | `false` | Print what would upload; no API key or network call. |
+| `--concurrency <N>` | integer | `4` | Parallel upload fanout. |
+| `--fail-fast` | bool | `false` | Stop on the first upload failure. |
+
 ### Exit Codes
 
 | Code | Meaning |
@@ -1098,7 +1217,7 @@ Available on all commands:
 | `FALLOW_QUIET` | Set to `1` to suppress progress. CLI `--quiet` overrides. |
 | `FALLOW_BIN` | Path to fallow binary (used by the MCP server). |
 | `FALLOW_TIMEOUT_SECS` | MCP server subprocess timeout in seconds (default: `120`). Increase for very large codebases. |
-| `FALLOW_EXTENDS_TIMEOUT_SECS` | Timeout for fetching remote `extends` URLs in seconds (default: `5`). |
+| `FALLOW_EXTENDS_TIMEOUT_SECS` | Timeout for fetching remote config inheritance in seconds (default: `5`). Do not raise this for untrusted sources. |
 | `FALLOW_COMMAND` | GitLab CI: command to run (default: `dead-code`). |
 | `FALLOW_FAIL_ON_ISSUES` | GitLab CI: set to `true` to exit 1 if issues found. |
 | `FALLOW_CHANGED_SINCE` | GitLab CI: git ref for incremental analysis. Auto-detected in MR pipelines. |
@@ -1107,6 +1226,7 @@ Available on all commands:
 | `FALLOW_SCORE` | GitLab CI: set to `true` to compute health score in combined mode. Enables health delta header in MR comments. |
 | `FALLOW_TREND` | GitLab CI: set to `true` to compare current health metrics against saved snapshot. Implies `FALLOW_SCORE`. |
 | `FALLOW_EXTRA_ARGS` | GitLab CI: additional CLI flags passed through to fallow. |
+| `FALLOW_VERSION` | GitLab CI: fallow version to install. Empty (default) reads the project's `package.json` `fallow` dependency, then falls back to `latest`; set explicitly to override the local pin. |
 | `GITLAB_TOKEN` | GitLab CI: project access token with `api` scope (for MR comments/reviews; `CI_JOB_TOKEN` is read-only for MR notes in the official GitLab API). |
 
 Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in your agent environment to avoid passing flags on every invocation.
@@ -1123,6 +1243,29 @@ Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in your agent environment to avoid
 | `compact` | Grep-friendly: `type:path:line:name` per line | Quick filtering |
 | `markdown` | Markdown tables | Documentation, PR comments |
 | `codeclimate` / `gitlab-codequality` | CodeClimate JSON array | GitLab Code Quality, CodeClimate-compatible tools |
+| `pr-comment-github` / `pr-comment-gitlab` | Sticky PR/MR comment markdown with HTML-comment marker for upsert | Posted by the action / template `comment.sh` scripts |
+| `review-github` / `review-gitlab` | JSON envelope for `POST /pulls/.../reviews` (GH) or `POST /merge_requests/.../discussions` (GL) | Posted by the action / template `review.sh` scripts; reconciled by `fallow ci reconcile-review` |
+
+---
+
+## `ci`: Provider-Aware Review Automation
+
+`fallow ci reconcile-review` reads a typed review envelope (`--format review-github` / `review-gitlab`), looks up existing fingerprints on the PR/MR, and resolves stale review threads when their finding is no longer present in the new envelope. Posts an idempotent "Resolved in `<sha>`" follow-up comment per stale finding (skipped if a marker for the same fingerprint at the current SHA already exists).
+
+### Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--provider` | `github\|gitlab` | Required. Selects the provider API. |
+| `--pr` | `<number>` | GitHub PR number. Required when `--provider github`. |
+| `--mr` | `<iid>` | GitLab MR internal id. Required when `--provider gitlab`. |
+| `--repo` | `owner/name` | GitHub repo. Defaults to `$GH_REPO` / `$GITHUB_REPOSITORY`. |
+| `--project-id` | `<id>` | GitLab project id (numeric or `group/project`). Defaults to `$CI_PROJECT_ID`. |
+| `--api-url` | `<url>` | Override the API base URL (GitHub Enterprise, self-hosted GitLab). |
+| `--envelope` | `<path>` | Path to the review envelope JSON written by `--format review-{github,gitlab}`. |
+| `--dry-run` | `bool` | Compute the new/stale plan without posting / resolving. |
+
+The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_API_RETRIES` (default 3) caps attempts; `FALLOW_API_RETRY_DELAY` (default 2) sets the floor delay; server-supplied `Retry-After` overrides the floor on 429 responses.
 
 ---
 
@@ -1141,11 +1284,10 @@ Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in your agent environment to avoid
 | `FALLOW_CHANGED_SINCE` | auto | Git ref for incremental analysis. Auto-detected in MR pipelines (`origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`) |
 | `FALLOW_COMMENT` | `false` | Post a summary comment on the MR with findings |
 | `FALLOW_REVIEW` | `false` | Post inline code review comments on MR diff lines where issues were found |
-| `FALLOW_VERSION` | — | Fallow version to install. Empty reads the project's `package.json` `fallow` dependency, then falls back to `latest`; set explicitly to override the local pin |
 | `FALLOW_SCORE` | `false` | Compute health score (0-100 with letter grade) in combined mode. Enables the health delta header in MR comments |
 | `FALLOW_TREND` | `false` | Compare current health metrics against saved snapshot. Implies `FALLOW_SCORE`. Shows per-metric deltas |
 | `FALLOW_EXTRA_ARGS` | — | Additional CLI flags passed through to fallow |
-| `GITLAB_TOKEN` | — | Project access token with `api` scope (required for `FALLOW_COMMENT` and `FALLOW_REVIEW`; `CI_JOB_TOKEN` is read-only for MR notes in the official GitLab API) |
+| `GITLAB_TOKEN` | — | Project access token with `api` scope (required for `FALLOW_COMMENT` and `FALLOW_REVIEW`). Alternatively, enable job token API access |
 
 **Package manager detection**: The GitLab template auto-detects the project's package manager (npm, pnpm, or yarn) from lockfiles. MR comments and review comments show the correct install/run commands for the detected manager (e.g., `pnpm add -D` vs `npm install --save-dev`).
 
@@ -1160,7 +1302,7 @@ Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in your agent environment to avoid
 ```json
 {
   "schema_version": 3,
-  "version": "2.47.0",
+  "version": "2.69.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1185,9 +1327,9 @@ Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in your agent environment to avoid
     "stale_suppressions": 0
   },
   "unused_files": [{ "path": "src/old.ts" }],
-  "unused_exports": [{ "path": "src/utils.ts", "name": "unusedFn", "line": 42, "actions": [{"type": "remove-export", "auto_fixable": true, "description": "Remove the `export` keyword from the declaration"}, {"type": "suppress-line", "auto_fixable": false, "description": "Suppress with an inline comment above the line", "comment": "// fallow-ignore-next-line unused-export"}] }],
+  "unused_exports": [{ "path": "src/utils.ts", "name": "unusedFn", "line": 42, "actions": [{"type": "remove-export", "auto_fixable": true, "description": "Remove the unused export from the public API"}, {"type": "suppress-line", "auto_fixable": false, "description": "Suppress with an inline comment above the line", "comment": "// fallow-ignore-next-line unused-export"}] }],
   "unused_types": [{ "path": "src/types.ts", "name": "OldType", "line": 10 }],
-  "unused_dependencies": [{ "name": "lodash", "line": 5 }],
+  "unused_dependencies": [{ "name": "lodash", "line": 5, "used_in_workspaces": ["packages/web"] }],
   "unused_dev_dependencies": [{ "name": "jest", "line": 8 }],
   "unused_enum_members": [{ "path": "src/enums.ts", "enum_name": "Status", "member": "Archived", "line": 5 }],
   "unused_class_members": [{ "path": "src/service.ts", "class_name": "Service", "member": "oldMethod", "line": 20 }],
@@ -1203,13 +1345,15 @@ Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in your agent environment to avoid
 }
 ```
 
+For dependency findings, `used_in_workspaces` means the package is imported by another workspace even though the declaring workspace does not import it. Move the dependency to the consuming workspace instead of auto-removing it.
+
 #### `actions` Array
 
 Every issue in `dead-code` JSON output includes an `actions` array with structured fix suggestions. Each action has:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `type` | string | yes | Action type in kebab-case (14 types, e.g., `remove-export`, `remove-file`, `remove-dependency`, `suppress-line`, `add-to-config`) |
+| `type` | string | yes | Action type in kebab-case (for example `remove-export`, `remove-file`, `remove-dependency`, `move-dependency`, `suppress-line`, `add-to-config`) |
 | `auto_fixable` | bool | yes | `true` if `fallow fix` handles this action automatically |
 | `description` | string | yes | Human-readable description of the action |
 | `comment` | string | no | Suppression comment text (on `suppress-line` actions) |
@@ -1228,7 +1372,7 @@ Example:
     {
       "type": "remove-export",
       "auto_fixable": true,
-      "description": "Remove the `export` keyword from the declaration"
+      "description": "Remove the unused export from the public API"
     },
     {
       "type": "suppress-line",
@@ -1263,6 +1407,25 @@ Dependency issues use `add-to-config` with `config_key` and `value`:
 }
 ```
 
+When a dependency action is `move-dependency`, `auto_fixable` is `false`; the package is imported from another workspace and needs a package.json ownership move rather than removal.
+
+#### Health `actions` array (CRAP findings)
+
+Health findings (`fallow health` JSON output) include an `actions` array. Primary action selection is formula-aware: the rule first checks whether full coverage CAN bring CRAP under threshold (CRAP bottoms out at `cyclomatic` at 100% coverage, so `cyclomatic < maxCrap` means coverage is a viable remediation), then uses `coverage_tier` to choose the description.
+
+| Condition | Primary action |
+|-----------|----------------|
+| `cyclomatic >= maxCrap` (coverage cannot remediate, regardless of tier) | `refactor-function` |
+| `cyclomatic < maxCrap` and `coverage_tier=none` | `add-tests` ("start from scratch") |
+| `cyclomatic < maxCrap` and `coverage_tier=partial` or `high` | `increase-coverage` ("targeted branch coverage") |
+| Cyclomatic/cognitive triggered (no CRAP) | `refactor-function` |
+
+The `coverage_tier` field is `"none"` (file not test-reachable / Istanbul 0%), `"partial"` (Istanbul `(0, 70)` / estimated 40%), or `"high"` (Istanbul `>= 70` / estimated 85%).
+
+When CRAP-only with cyclomatic count within 5 of `maxCyclomatic` AND cognitive at or above `maxCognitive / 2`, a secondary `refactor-function` is appended. The cognitive floor suppresses false positives on flat type-tag dispatchers and JSX render maps (high CC, near-zero cog). A single finding can carry multiple action types: e.g. a finding that exceeds both cyclomatic and CRAP at `coverage_tier=partial` gets `increase-coverage` AND `refactor-function`. Treat the first non-`suppress-line` action as primary.
+
+The `suppress-line` action is auto-omitted when `--baseline`/`--save-baseline` is set, OR when `health.suggestInlineSuppression: false` in config. The report root carries an `actions_meta: { suppression_hints_omitted: true, reason: "baseline-active" | "config-disabled" }` breadcrumb in that case.
+
 #### `baseline_deltas` Object
 
 When `--baseline` is used in combined output, the JSON includes a `baseline_deltas` object showing per-category changes since the baseline:
@@ -1284,7 +1447,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 ```json
 {
   "schema_version": 3,
-  "version": "2.47.0",
+  "version": "2.69.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1328,7 +1491,7 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "check": {
     "schema_version": 3,
-    "version": "2.47.0",
+    "version": "2.69.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],
@@ -1350,7 +1513,7 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
   },
   "dupes": {
     "schema_version": 3,
-    "version": "2.47.0",
+    "version": "2.69.0",
     "elapsed_ms": 82,
     "total_clones": 15,
     "total_lines_duplicated": 230,
@@ -1359,7 +1522,7 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
   },
   "health": {
     "schema_version": 3,
-    "version": "2.47.0",
+    "version": "2.69.0",
     "elapsed_ms": 32,
     "summary": {},
     "findings": [],
@@ -1399,6 +1562,10 @@ Config files are searched in priority order: `.fallowrc.json` > `.fallowrc.jsonc
   // Dependencies to ignore
   "ignoreDependencies": ["autoprefixer"],
 
+  // Suppress unused-export findings when the symbol is referenced inside its
+  // declaring file (knip parity). Boolean or { type, interface } object form.
+  "ignoreExportsUsedInFile": true,
+
   // Per-issue-type severity
   "rules": {
     "unused-files": "error",
@@ -1432,6 +1599,7 @@ Config files are searched in priority order: `.fallowrc.json` > `.fallowrc.jsonc
     "minTokens": 50,
     "minLines": 5,
     "threshold": 0,
+    "ignoreDefaults": true,
     "skipLocal": false,
     "ignorePatterns": ["**/*.generated.ts"]
   },
@@ -1453,8 +1621,8 @@ Config files are searched in priority order: `.fallowrc.json` > `.fallowrc.jsonc
   // These files are treated as always-used and never flagged as unused.
   "dynamicallyLoaded": ["plugins/**/*.ts", "locales/**/*.json"],
 
-  // Inherit from base config (relative paths, npm: packages, or https:// URLs)
-  "extends": ["./base-config.json", "npm:@my-org/fallow-config", "https://example.com/shared-config.json"],
+  // Inherit from base config (prefer local paths or trusted npm packages)
+  "extends": ["./base-config.json", "npm:@my-org/fallow-config"],
 
   // Custom external plugins
   "plugins": ["tools/plugins/"],
@@ -1476,6 +1644,7 @@ Config files are searched in priority order: `.fallowrc.json` > `.fallowrc.jsonc
 entry = ["src/index.ts", "scripts/*.ts"]
 ignorePatterns = ["**/*.generated.ts"]
 ignoreDependencies = ["autoprefixer"]
+ignoreExportsUsedInFile = true
 production = false
 publicPackages = ["@myorg/shared-lib", "@myorg/utils"]
 dynamicallyLoaded = ["plugins/**/*.ts", "locales/**/*.json"]
@@ -1489,6 +1658,7 @@ unused-types = "off"
 mode = "mild"
 minTokens = 50
 minLines = 5
+ignoreDefaults = true
 
 [[overrides]]
 files = ["*.test.ts"]

package/skills/fallow/references/gotchas.md

@@ -23,7 +23,7 @@ Always preview with `--dry-run` before applying. This is a destructive operation
 
 ## Don't Create Config Unless Needed
 
-Fallow works with zero configuration for most projects thanks to 90 auto-detecting framework plugins. Creating an unnecessary config file can mask issues or override detection behavior.
+Fallow works with zero configuration for most projects thanks to 94 auto-detecting framework plugins. Creating an unnecessary config file can mask issues or override detection behavior.
 
 ```bash
 # WRONG: creating config for a standard Next.js project
@@ -429,6 +429,26 @@ Fallow marks `static/style.css` and `static/app.js` as reachable. Root-relative
 
 ---
 
+## GraphQL `#import` Documents Are Tracked
+
+GraphQL `.graphql` and `.gql` files can keep nearby fragment documents reachable with relative `#import` comments. Fallow tracks `./` and `../` specifiers, including extensionless imports that resolve through `.graphql` and `.gql`; package-style specifiers are ignored.
+
+```graphql
+# src/query.graphql
+
+#import "./fragments/user-fields"
+
+query CurrentUser {
+  currentUser {
+    ...UserFields
+  }
+}
+```
+
+Fallow marks `src/fragments/user-fields.graphql` or `src/fragments/user-fields.gql` as reachable when either file exists. A typo in the relative path is reported as an unresolved import instead of silently dropping the edge.
+
+---
+
 ## Library Packages: Use `publicPackages` Instead of Visibility Tags
 
 In monorepos, shared library packages have exported APIs consumed by external consumers not visible to fallow. Instead of annotating every export with `/** @public */` (or `@internal`, `@beta`, `@alpha`), use the `publicPackages` config to mark entire workspace packages as public libraries. Exports and exported enum/class members from these packages are excluded from unused API detection.

package/skills/fallow/references/patterns.md

@@ -129,6 +129,31 @@ Parse the JSON to list specific files and exports that became unused.
 
 Computes a health score (0-100 with letter grade) in combined mode and enables the health delta header in PR comments.
 
+### GitHub Actions: Severity-Aware PR Quality Gate (Audit)
+
+```yaml
+- uses: fallow-rs/fallow@v2
+  with:
+    command: audit
+    gate: new-only        # default; fails only on findings introduced by this PR
+    fail-on-issues: true
+```
+
+Runs `fallow audit` to combine dead-code + complexity + duplication scoped to changed files. The gate respects rule severity from `.fallowrc.json`, so `unused-exports: warn` projects do not fail when a PR touches a file with pre-existing warn-tier findings. Use `gate: all` to fail on every finding in changed files.
+
+The action exposes `outputs.verdict` (`pass`/`warn`/`fail`) and `outputs.gate` for downstream conditionals; `outputs.issues` holds the introduced count under `gate: new-only` and the total count under `gate: all`.
+
+```yaml
+- uses: fallow-rs/fallow@v2
+  id: fallow
+  with:
+    command: audit
+
+- name: Block release on regression
+  if: steps.fallow.outputs.verdict == 'fail'
+  run: exit 1
+```
+
 ### GitHub Actions: Inline PR Annotations (No Advanced Security)
 
 The official action supports inline PR annotations via GitHub workflow commands. This does not require Advanced Security (unlike SARIF upload) and works on any GitHub plan.
@@ -398,6 +423,7 @@ Creates `.fallowrc.json` with mapped settings:
 - knip `rules`/`exclude`/`include` → fallow `rules` (error/warn/off)
 - knip `ignore` → fallow `ignorePatterns`
 - knip `ignoreDependencies` → fallow `ignoreDependencies`
+- 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
 
 ### Step 3: Compare results
@@ -595,7 +621,7 @@ Focus on findings that are BOTH dead code and duplicated:
 
 ## Custom Plugin Setup
 
-For frameworks not covered by the 90 built-in plugins.
+For frameworks not covered by the 94 built-in plugins.
 
 ### Option 1: Inline framework config
 
@@ -693,13 +719,13 @@ Because Claude receives stderr as tool feedback on a blocked `PreToolUse` call,
 Install it automatically:
 
 ```bash
-fallow setup-hooks
+fallow hooks install --target agent
 ```
 
 Remove it later with:
 
 ```bash
-fallow setup-hooks --uninstall
+fallow hooks uninstall --target agent
 ```
 
 Manual files:
@@ -727,79 +753,14 @@ Manual files:
 
 ### `.claude/hooks/fallow-gate.sh`
 
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Generated by fallow setup-hooks.
-# Requires bash and jq. On Windows run via git-bash or WSL.
-# Blocks Claude Code git commit and git push when fallow audit returns verdict fail.
-# Runtime errors fail open with a single stderr notice so skips stay visible.
-
-if ! command -v jq >/dev/null 2>&1; then
-  echo "fallow-gate: jq not on PATH, skipping audit." >&2
-  exit 0
-fi
+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).
 
-INPUT="$(cat)"
-CMD="$(jq -r '.tool_input.command // empty' <<<"$INPUT")"
-
-if ! printf '%s\n' "$CMD" | grep -Eq '(^|[[:space:];|&()])git[[:space:]]+(commit|push)([[:space:]]|$)'; then
-  exit 0
-fi
-
-if command -v fallow >/dev/null 2>&1; then
-  RUNNER=(fallow)
-elif command -v npx >/dev/null 2>&1 && VER="$(npx --no-install fallow --version 2>/dev/null || true)" && [[ "$VER" == fallow* ]]; then
-  RUNNER=(npx --no-install fallow)
-else
-  echo "fallow-gate: fallow binary not found (tried PATH and npx --no-install), skipping audit." >&2
-  exit 0
-fi
-
-TMP_JSON="$(mktemp)"
-TMP_ERR="$(mktemp)"
-cleanup() {
-  rm -f "$TMP_JSON" "$TMP_ERR"
-}
-trap cleanup EXIT
-
-if "${RUNNER[@]}" audit --format json --quiet --explain >"$TMP_JSON" 2>"$TMP_ERR"; then
-  STATUS=0
-else
-  STATUS=$?
-fi
-
-VERDICT="$(jq -r '.verdict // empty' <"$TMP_JSON" 2>/dev/null || true)"
-IS_ERROR="$(jq -r '.error // false' <"$TMP_JSON" 2>/dev/null || echo false)"
-
-if [ "$VERDICT" = "fail" ]; then
-  cat "$TMP_JSON" >&2
-  exit 2
-fi
-
-if [ "$STATUS" -eq 2 ] || [ "$IS_ERROR" = "true" ]; then
-  MSG="$(jq -r '.message // empty' <"$TMP_JSON" 2>/dev/null || true)"
-  if [ -n "$MSG" ]; then
-    echo "fallow-gate: fallow audit runtime error ($MSG), skipping." >&2
-  else
-    echo "fallow-gate: fallow audit runtime error, skipping." >&2
-  fi
-  exit 0
-fi
-
-if [ "$STATUS" -ne 0 ]; then
-  ERR_LINE="$(sed -n '1p' "$TMP_ERR" 2>/dev/null || true)"
-  if [ -n "$ERR_LINE" ]; then
-    echo "fallow-gate: fallow audit exited $STATUS ($ERR_LINE), skipping." >&2
-  else
-    echo "fallow-gate: fallow audit exited $STATUS, skipping." >&2
-  fi
-  exit 0
-fi
-
-exit 0
-```
+Behavior you can rely on:
+- Runs only when the intercepted command matches `git commit` or `git push`; otherwise exits 0.
+- 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.46.0`). 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` 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.
+- 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`):
 
@@ -812,13 +773,13 @@ Keep `fallow audit` in CI alongside this local gate. The hook only runs for Clau
 ### Remove the hook
 
 ```bash
-fallow setup-hooks --uninstall
+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.
 
 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 init --hooks`
+### Distinguish from `fallow hooks install --target git`
 
-`fallow init --hooks` is a different command: 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 setup-hooks` is the *agent* enforcement path, targeting `.claude/` and `AGENTS.md`. Both can live in the same repo: git hooks catch human commits, the setup-hooks 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/` and `AGENTS.md`. Both can live in the same repo: git hooks catch human commits, the agent gate catches agent commits.