fallow 3.31.0 → 3.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.31.0",
+  "version": "3.33.0",
   "mcpName": "io.github.fallow-rs/fallow",
   "description": "Codebase intelligence for TypeScript and JavaScript: health, complexity, duplication, architecture, styling drift, and unused code from one graph. CLI, LSP, and MCP server. Zero config for over 100 frameworks.",
   "license": "MIT",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/fallow-rs/fallow.git"
   },
-  "homepage": "https://docs.fallow.tools",
+  "homepage": "https://fallow.tools/docs/",
   "funding": "https://github.com/sponsors/fallow-rs",
   "bugs": {
     "url": "https://github.com/fallow-rs/fallow/issues"
@@ -16,7 +16,7 @@
   "intent": {
     "version": 1,
     "repo": "fallow-rs/fallow",
-    "docs": "https://docs.fallow.tools"
+    "docs": "https://fallow.tools/docs/"
   },
   "keywords": [
     "code-intelligence",
@@ -89,14 +89,14 @@
     "@tanstack/intent": "0.4.0"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.31.0",
-    "@fallow-cli/darwin-x64": "3.31.0",
-    "@fallow-cli/linux-x64-gnu": "3.31.0",
-    "@fallow-cli/linux-arm64-gnu": "3.31.0",
-    "@fallow-cli/linux-x64-musl": "3.31.0",
-    "@fallow-cli/linux-arm64-musl": "3.31.0",
-    "@fallow-cli/win32-arm64-msvc": "3.31.0",
-    "@fallow-cli/win32-x64-msvc": "3.31.0",
-    "fallow-type-aware": "3.31.0"
+    "@fallow-cli/darwin-arm64": "3.33.0",
+    "@fallow-cli/darwin-x64": "3.33.0",
+    "@fallow-cli/linux-x64-gnu": "3.33.0",
+    "@fallow-cli/linux-arm64-gnu": "3.33.0",
+    "@fallow-cli/linux-x64-musl": "3.33.0",
+    "@fallow-cli/linux-arm64-musl": "3.33.0",
+    "@fallow-cli/win32-arm64-msvc": "3.33.0",
+    "@fallow-cli/win32-x64-msvc": "3.33.0",
+    "fallow-type-aware": "3.33.0"
   }
 }

package/schema.json

@@ -136,7 +136,7 @@
       "default": []
     },
     "duplicates": {
-      "description": "Configures clone detection: `enabled` (default true), `mode` (`strict`, `mild` default, `weak`, `semantic`, from least to most identifier/literal blinding; `strict` and `mild` are equivalent under fallow's AST tokenizer, `weak` blinds string literals, `semantic` blinds all identifiers and literals for Type-2 renamed-variable detection), `near` (false, add bounded function-scoped near-miss detection), `minTokens` (50), `minLines` (5), `minOccurrences` (integer >= 2, deserialization fails below 2), `threshold` (max duplication percentage, 0 = no limit), `ignore` globs, `ignoredClones` (reviewed clone keys to hide until their content or occurrence count changes), `ignoreDefaults` (true, merge built-in generated-file ignores), `skipLocal` (only report cross-directory clones), `crossLanguage` (strip TS type annotations to match .ts against .js), `ignoreImports` (true, strip ES import/re-export/top-level require wiring from the token stream), and `normalization` (per-flag `ignoreIdentifiers`/`ignoreStringValues`/`ignoreNumericValues` overrides on top of `mode`). Raise `minOccurrences` to focus on widespread copy-paste, enable `near` for gapped structural clones, or set `mode` to `semantic` to catch renamed-variable exact clones.",
+      "description": "Configures clone detection: `enabled` (default true), `mode` (`strict`, `mild` default, `weak`, `semantic`, from least to most identifier/literal blinding; `strict` and `mild` are equivalent under fallow's AST tokenizer, `weak` blinds string literals, `semantic` blinds all identifiers and literals for Type-2 renamed-variable detection), `near` (false, add bounded function-scoped near-miss detection), `minTokens` (50), `minLines` (5), `minOccurrences` (integer >= 2, deserialization fails below 2), `threshold` (max duplication percentage, 0 = no limit), `ignore` globs, `ignoredClones` (reviewed clone keys to hide until their content or occurrence count changes), `ignoreDefaults` (true, merge built-in generated-file ignores), `skipLocal` (only report cross-directory clones), `ignoreSymlinks` (false, omit clone instances whose path is a symlink or lies under a symlinked directory), `crossLanguage` (strip TS type annotations to match .ts against .js), `ignoreImports` (true, strip ES import/re-export/top-level require wiring from the token stream), and `normalization` (per-flag `ignoreIdentifiers`/`ignoreStringValues`/`ignoreNumericValues` overrides on top of `mode`). Raise `minOccurrences` to focus on widespread copy-paste, enable `near` for gapped structural clones, or set `mode` to `semantic` to catch renamed-variable exact clones.",
       "$ref": "#/$defs/DuplicatesConfig",
       "default": {
         "enabled": true,
@@ -150,6 +150,7 @@
         "ignoredClones": [],
         "ignoreDefaults": true,
         "skipLocal": false,
+        "ignoreSymlinks": false,
         "crossLanguage": false,
         "ignoreImports": true,
         "normalization": {},
@@ -214,6 +215,7 @@
         "unprovided-injects": "warn",
         "unrendered-components": "warn",
         "unused-component-props": "warn",
+        "absent-component-props": "off",
         "unused-component-emits": "warn",
         "unused-component-inputs": "warn",
         "unused-component-outputs": "warn",
@@ -378,6 +380,11 @@
       "type": "boolean",
       "default": false
     },
+    "showCascade": {
+      "description": "When true, the report keeps the unused exports, unused types, unused class members and unused enum members of a file that is an unused file. Boolean, defaults to false: deleting an unused file removes these findings, so the report hides them and counts them in cascade_hidden. The CLI flag --show-cascade applies the same behavior for one run.",
+      "type": "boolean",
+      "default": false
+    },
     "autoImports": {
       "description": "When true, drops Nuxt convention-based entry-pattern fallbacks so genuinely-unreferenced convention files surface as unused-file. Component fallbacks are kept when nuxt.config customizes components: in a way fallow does not model, and composable/util fallbacks are kept when it customizes imports:; a config that scans no more than the Nuxt defaults (components: false, components: [], components: { dirs: [] }, components: true, imports: { scan: false }, imports: {}, imports: { dirs: [] }) is treated like the default and its fallbacks are dropped; imports: { autoImport: false } on its own is not, because it only switches the injection off while the same directories stay registered behind #imports. A nuxt.config that carries any top-level key fallow cannot read statically, a computed key, an accessor, or a spread such as { ...base, devtools: {} }, keeps both surfaces' fallbacks for that root, because the spread may hold the keys that decide. Only top-level keys count when the config object is readable: a nested key such as a routeRules path ending in components does not keep a fallback. Nested components or imports keys in $production, $development, $test or `$env.<name>`, and components or imports hooks (a components:* key or a nested components object in hooks, also inside those overrides), count as that surface's key; such an override object or hooks object that fallow cannot read statically falls back to a text match for the keys. Each root is classified on its own config plus the configs of its local layers, so one custom nuxt.config in a monorepo does not keep every other workspace's fallbacks. A local layer is a directory named in extends, or a `layers/<name>` directory, that holds a nuxt.config; its convention files are entry points with the flag off and auto-import sources with it on, and `#layers/<name>/` resolves to it by its $meta.name (a `layers/<name>` directory without one uses its directory name). A remote or package layer is only a dependency reference. Component names follow Nuxt: a component under components/global or components/islands is named after its own directory (components/global/Foo.vue is `<Foo>`), and .client, .server, .global and .island suffixes are stripped. A name imported or re-exported by hand from #components or #imports credits its convention file just like a template tag or a bare call; a namespace import names nothing and credits nothing. Boolean, defaults to false; set it for a Nuxt project that has explicitly configured its auto-import directories. Synthesis of auto-import graph edges (resolving `<Card />` or `useUserStore()` to their convention files) happens regardless of this flag.",
       "type": "boolean",
@@ -949,6 +956,11 @@
           "type": "boolean",
           "default": false
         },
+        "ignoreSymlinks": {
+          "description": "Omit clone instances whose file path is a symlink, or lies under a\nsymlinked directory, inside the project root.\n\nDefaults to `false`: symlinked instances stay in the report and carry\n`is_symlink: true` in JSON output. Set to `true` to report only\nduplication between real files. A clone group with fewer than two\nremaining instances is not reported. Symlinked files also leave the\ncorpus, so `stats` (files, lines, tokens and the duplication\npercentage that `threshold` checks) count only real files.",
+          "type": "boolean",
+          "default": false
+        },
         "crossLanguage": {
           "description": "Enable cross-language clone detection by stripping type annotations.\n\nWhen enabled, TypeScript type annotations (parameter types, return types,\ngenerics, interfaces, type aliases) are stripped from the token stream,\nallowing detection of clones between `.ts` and `.js` files.",
           "type": "boolean",
@@ -1388,6 +1400,11 @@
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
+        "absent-component-props": {
+          "description": "Used optional inputs absent from inspected callers. Requires manual review; off by default.",
+          "$ref": "#/$defs/Severity",
+          "default": "off"
+        },
         "unused-component-emits": {
           "description": "Vue `<script setup>` `defineEmits` declared event emitted nowhere inside\nits own single-file component (no `emit('<name>')` call). The single-file\ndead-input direction. Defaults to `warn`, not `error`: an emit can be part\nof a deliberately-stable public component API, so analyzer confidence is\nlower; warn encodes that without failing CI.",
           "$ref": "#/$defs/Severity",
@@ -2230,6 +2247,17 @@
             }
           ]
         },
+        "absent-component-props": {
+          "description": "Optional override for absent optional component inputs.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "unused-component-emits": {
           "description": "Optional override for [`RulesConfig::unused_component_emits`].",
           "anyOf": [
@@ -2737,6 +2765,13 @@
       "description": "Saved per-issue-type counts written by `--save-baseline` and compared by\n`--fail-on-regression`. Every count defaults to `0` when its key is missing,\nso hand-trimmed baselines stay loadable.",
       "type": "object",
       "properties": {
+        "absentComponentProps": {
+          "description": "Baseline count of optional component prop review candidates.",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0,
+          "default": 0
+        },
         "analysisIdentity": {
           "description": "Compatibility identity for the analysis that produced these counts.\nMissing values in existing configs are treated as syntactic.",
           "$ref": "#/$defs/SemanticAnalysisIdentity",

package/scripts/lazy-verify.js

@@ -42,12 +42,24 @@ const VERIFY_LOG_ENV = "FALLOW_VERIFY_LOG";
 // keyed by `code` so independent failure modes are still surfaced.
 const _warningEmitted = new Set();
 
+// Write to fd 2 directly. Under Bun, the first use of `process.stderr` sets
+// O_NONBLOCK on the pipe, and the platform binary inherits that pipe (and
+// stdout too when stderr and stdout share one pipe). See issue #3276.
+// Diagnostics are best-effort, so a failed write is ignored.
+function writeStderr(text) {
+  try {
+    fs.writeSync(2, text);
+  } catch {
+    // Ignore: no reader, or a closed descriptor.
+  }
+}
+
 function warnOnce(code, message) {
   if (_warningEmitted.has(code)) {
     return;
   }
   _warningEmitted.add(code);
-  process.stderr.write(`fallow: ${message}\n`);
+  writeStderr(`fallow: ${message}\n`);
 }
 
 function isVerifyLogEnabled(env) {
@@ -68,7 +80,7 @@ function emitVerifyLog(env, payload) {
       parts.push(`${key}=${v}`);
     }
   }
-  process.stderr.write(`fallow-verify ${parts.join(" ")}\n`);
+  writeStderr(`fallow-verify ${parts.join(" ")}\n`);
 }
 
 // The sentinel binds the same binaries that verify-binary checks, so a new

package/scripts/lazy-verify.test.js

@@ -69,13 +69,15 @@ function cleanup(dir) {
 
 function captureStderr(t) {
   const lines = [];
-  const original = process.stderr.write.bind(process.stderr);
-  process.stderr.write = (chunk) => {
+  // lazy-verify writes diagnostics to fd 2 with fs.writeSync (issue #3276).
+  const original = fs.writeSync;
+  fs.writeSync = (fd, chunk, ...rest) => {
+    if (fd !== 2) return original(fd, chunk, ...rest);
     lines.push(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
-    return true;
+    return chunk.length;
   };
   t.after(() => {
-    process.stderr.write = original;
+    fs.writeSync = original;
   });
   return { lines };
 }

package/scripts/run-binary.js

@@ -102,8 +102,13 @@ function printVerifyError(verifyResult) {
   );
 }
 
+// Call only after the child exits. Bun sets O_NONBLOCK on fd 1 when a script
+// first reads `process.stdout`. The child inherits that open file description,
+// so a large write from the binary fails with EAGAIN and the output is cut
+// short (issue #3276).
 function writeVerifiedLineIfVersionQuery(verifyResult, version) {
   if (isVersionQuery(process.argv)) {
+    guardBrokenStdout();
     process.stdout.write(`${describeVerified(verifyResult, version)}\n`);
   }
 }
@@ -205,7 +210,8 @@ function guardBrokenStdout() {
 // handling stay identical to a bare `fallow` invocation.
 function runBinary(binaryBaseName, options = {}) {
   const prependArgs = Array.isArray(options.prependArgs) ? options.prependArgs : [];
-  guardBrokenStdout();
+  // Do not read `process.stdout` or write to `process.stderr` before the child
+  // exits: under Bun that makes the inherited pipes non-blocking for the child.
   const { pkg, manifestPath, platformPkgDir } = resolvePlatformPaths();
   const resolvedVersion = readResolvedVersion(manifestPath);
 

package/scripts/run-binary.test.js

@@ -22,7 +22,9 @@ function currentPlatformPackage() {
   return getPlatformPackage(process.platform, process.arch, libcFamily);
 }
 
-function runLauncher(t, launcher, args) {
+// Install a fake platform package whose `fallow` binary is the given Node
+// script. Returns the scratch directory and the environment for the launcher.
+function installFakeBinary(t, script) {
   const work = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-launcher-"));
   t.after(() => fs.rmSync(work, { recursive: true, force: true }));
 
@@ -36,27 +38,84 @@ function runLauncher(t, launcher, args) {
   );
 
   const binary = path.join(pkgDir, "fallow");
-  fs.writeFileSync(
-    binary,
-    "#!/usr/bin/env node\n" +
-      'require("node:fs").writeFileSync(process.env.FALLOW_TEST_ARGS, JSON.stringify(process.argv.slice(2)));\n',
-  );
+  fs.writeFileSync(binary, `#!/usr/bin/env node\n${script}`);
   fs.chmodSync(binary, 0o755);
 
+  const env = {
+    ...process.env,
+    NODE_PATH: path.join(work, "node_modules"),
+    FALLOW_SKIP_BINARY_VERIFY: "1",
+  };
+  return { work, env };
+}
+
+function runLauncher(t, launcher, args) {
+  const { work, env } = installFakeBinary(
+    t,
+    'require("node:fs").writeFileSync(process.env.FALLOW_TEST_ARGS, JSON.stringify(process.argv.slice(2)));\n',
+  );
   const argsFile = path.join(work, "args.json");
   const result = spawnSync(process.execPath, [path.join(BIN_DIR, launcher), ...args], {
     encoding: "utf8",
-    env: {
-      ...process.env,
-      NODE_PATH: path.join(work, "node_modules"),
-      FALLOW_SKIP_BINARY_VERIFY: "1",
-      FALLOW_TEST_ARGS: argsFile,
-    },
+    env: { ...env, FALLOW_TEST_ARGS: argsFile },
   });
   assert.equal(result.status, 0, result.stderr);
   return JSON.parse(fs.readFileSync(argsFile, "utf8"));
 }
 
+// The fake binary writes a large payload the way the Rust binary does: plain
+// write calls on fd 1, and it stops at the first write error but exits 0.
+// A non-blocking inherited pipe makes a write fail with EAGAIN, so the reader
+// gets a short payload (issue #3276).
+const LARGE_OUTPUT_BYTES = 4 * 1024 * 1024;
+const LARGE_OUTPUT_BINARY =
+  'const fs = require("node:fs");\n' +
+  `const total = ${LARGE_OUTPUT_BYTES};\n` +
+  'const chunk = Buffer.alloc(64 * 1024, "x");\n' +
+  "let written = 0;\n" +
+  "try {\n" +
+  "  while (written < total) written += fs.writeSync(1, chunk, 0, Math.min(chunk.length, total - written));\n" +
+  "} catch {}\n";
+
+function bunAvailable() {
+  const probe = spawnSync("bun", ["--version"], { encoding: "utf8" });
+  return probe.status === 0;
+}
+
+function runLargeOutput(t, runtime, { mergeStderr = false } = {}) {
+  const { env } = installFakeBinary(t, LARGE_OUTPUT_BINARY);
+  const launcher = path.join(BIN_DIR, "fallow");
+  const [command, args] = mergeStderr
+    ? ["/bin/sh", ["-c", 'exec "$0" "$@" 2>&1', runtime, launcher, "check"]]
+    : [runtime, [launcher, "check"]];
+  return spawnSync(command, args, { env, maxBuffer: 2 * LARGE_OUTPUT_BYTES });
+}
+
+// Count only the payload bytes. In the merged case, stdout also holds the
+// FALLOW_SKIP_BINARY_VERIFY warning line.
+function payloadBytes(stdout) {
+  let count = 0;
+  for (const byte of stdout) if (byte === 0x78) count += 1;
+  return count;
+}
+
+for (const runtime of ["node", "bun"]) {
+  for (const mergeStderr of [false, true]) {
+    const name = mergeStderr ? "stdout and stderr on one pipe" : "stdout on its own pipe";
+    test(
+      `launcher under ${runtime} passes the complete binary output (${name})`,
+      { skip: process.platform === "win32" || (runtime === "bun" && !bunAvailable()) },
+      (t) => {
+        const result = runLargeOutput(t, runtime === "node" ? process.execPath : "bun", {
+          mergeStderr,
+        });
+        assert.equal(result.status, 0, String(result.stderr));
+        assert.equal(payloadBytes(result.stdout), LARGE_OUTPUT_BYTES);
+      },
+    );
+  }
+}
+
 // Run a child that installs guardBrokenStdout, then emits a synthetic stdout
 // 'error' with the given code. Node delivers a broken-pipe failure as exactly
 // this event ("Emitted 'error' event on Socket instance"), so emitting it is a

package/skills/fallow/SKILL.md

@@ -6,7 +6,7 @@ license: MIT
 
 # Fallow: codebase intelligence for TypeScript and JavaScript
 
-Codebase intelligence for TypeScript and JavaScript. The static layer analyzes code and styles and reports quality, changed-code risk, cleanup opportunities, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, design-system styling drift, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review and cold-path deletion confidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. Broad framework plugin coverage, zero configuration, sub-second static analysis.
+Fallow analyzes code and styles for changed-code risk, cleanup opportunities, circular dependencies, duplication, complexity hotspots, architecture boundary violations, design-system styling drift, feature flags, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review and cold-path deletion confidence. A single local capture is available by default. Continuous or cloud runtime monitoring is optional.
 
 ## When to Use
 - Find cleanup opportunities: unused files, exports, types, members, dependencies, or feature flags that guard unused exports.
@@ -44,7 +44,7 @@ cargo install fallow-cli   # build from source
 1. **Always use `--format json --quiet`** for machine-readable output and parse stdout as JSON. Compact JSON is the default; never depend on whitespace or add `--pretty` in agent pipelines. Keep stderr separate so diagnostics remain visible; never merge it into the JSON stream with `2>&1`.
 2. **Preserve and interpret the exit status.** Codes 0 and 1 are successful analysis outcomes: 0 is clean and 1 means findings. Treat every other code according to `fallow schema.exit_codes`. Do not force a successful status, because that hides validation, license, setup, network, and security-gate outcomes.
 3. **Use `--explain`** to include a `_meta` object in JSON output with metric definitions, ranges, and interpretation hints. In human format, `--explain` prints a `Description:` line under each section header.
-4. **Use the root `kind` field** to identify typed JSON envelopes (`dead-code`, `dead-code-grouped`, `health`, `dupes`, `combined`, `audit`, etc.).
+4. **Use the root `kind` field** to identify typed JSON envelopes (`dead-code`, `dead-code-grouped`, `architecture`, `architecture-grouped`, `health`, `dupes`, `combined`, `audit`, etc.).
 5. **Use issue type filters** (`--unused-exports`, `--unused-files`, etc.) to limit output scope
 6. **Always `--dry-run` before `fix`**, then `fix --yes` to apply
 7. **All output paths are relative** to the project root
@@ -58,7 +58,23 @@ cargo install fallow-cli   # build from source
 15. **Check production runtime data before an edit or a delete, when Fallow Cloud is connected**. Prefer the scoped reads over the full `get_cloud_runtime_context` pull. Before an edit, run `fallow coverage review-packet --repo <owner/repo>` (MCP `get_cloud_review_packet`) for the changed files and read `hit_count`, `covered_by_test`, and the callers when present. Before a delete, require `period_tracking_state: "never_called"`, not only `tracking_state`, and read `evidence_window.observed_hours`: few observed hours or a low-traffic surface mean "not visited", not "dead". After a deploy, run `fallow coverage deployment-changes --repo <owner/repo>` (MCP `get_cloud_deployment_changes`) and, when `comparable` is `false`, report `reason` and claim no change. Open files by `repo_path`, not `file_path`. Production data is context, never a gate. Details: [references/mcp.md](references/mcp.md#scoped-cloud-reads).
 
 ## Onboarding And Insight
-Offer setup only after a human-requested analysis shows findings and all signals match: `fallow config --path` exits 3, not CI, not a pipeline format, `fallow impact --format json --quiet` has `onboarding_declined: false`, and no offer happened this session. Ask after showing value. Choices: guard commits and PRs, baseline the existing backlog and clean by category, add AGENTS.md guidance, or keep as-is. On decline, run `fallow init --decline --quiet` and stay silent for this project. Mutate only after consent. For guards, inspect `fallow hooks status --format json --quiet`, then use `fallow hooks install --target agent` and `fallow hooks install --target git`; for large backlogs, pair the gate with `--save-baseline` / new-only guidance. Offer `fallow impact enable` as local-only value tracking, never as telemetry; also offer it once on already-configured projects when `fallow impact status --format json` has `enabled: false` and `explicit_decision: false`, and record a no with `fallow impact disable --quiet`. Surface value on clear events: if the agent gate blocked a commit or push and a later retry succeeded, mention what was contained; when `next_steps` carries id `impact-report`, run its command and relay the non-zero numbers to the user in one line. On request, summarize non-zero Impact counts. Ask about telemetry only after such a win, only if `fallow telemetry status --format json` has `explicit_decision: false`, and never run `fallow telemetry enable`.
+Offer setup after showing the findings from a human-requested analysis, only when all these conditions hold:
+
+- `fallow config --path` exits 3.
+- The run is outside CI and does not use a pipeline format.
+- `fallow impact --format json --quiet` has `onboarding_declined: false`.
+- No offer happened this session.
+
+Offer these choices: guard commits and PRs, baseline the existing backlog and clean by category, add AGENTS.md guidance, or keep as-is. Mutate only after consent. On decline, run `fallow init --decline --quiet` and stay silent for this project.
+
+For guards, inspect `fallow hooks status --format json --quiet`, then use `fallow hooks install --target agent` and `fallow hooks install --target git`. For large backlogs, pair the gate with `--save-baseline` and new-only guidance.
+
+Offer `fallow impact enable` for local value tracking. Impact is separate from telemetry. Also offer it once on an already-configured project when `fallow impact status --format json` has `enabled: false` and `explicit_decision: false`. Record a decline with `fallow impact disable --quiet`.
+
+Report value when there is evidence. If the agent gate blocked a commit or push and a later retry succeeded, describe the issues that caused the block. When `next_steps` has id `impact-report`, run its command and report the non-zero numbers in one line. On request, summarize non-zero Impact counts.
+
+Ask about telemetry only after one of these events, and only if `fallow telemetry status --format json` has `explicit_decision: false`. Never run `fallow telemetry enable`.
+
 ## Task Cheat Sheet
 Route by intent before reaching for the big analysis commands. Same matrix as `fallow schema` (`task_matrix`) and the generated AGENTS.md section.
 
@@ -69,6 +85,7 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 | prove a TypeScript symbol's exact consumers before refactoring | `fallow dead-code --type-aware --symbol-impact <file>:<export-or-class.method>` |
 | find how one module reaches another | `fallow trace --path <from> <to>`; Reports `reachable: false` instead of failing when no import path exists; type-only hops are reported, not skipped. |
 | delete an "unused" dependency | `fallow dead-code --trace-dependency <name>` |
+| migrate a dependency | `fallow trace --dependency <name> --sites`; Counts each imported name, follows one hop through project wrappers, and counts each use that it cannot resolve. |
 | commit or open a PR | `fallow audit --base <ref>` |
 | read a diff before approving it | `fallow review --base <ref> --brief`; orientation, never gates: deterministic and always exit 0, unlike the audit row |
 | prioritize refactoring | `fallow health --hotspots --targets` |
@@ -77,6 +94,7 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 | consolidate duplication | `fallow dupes --trace dup:<fingerprint>` |
 | find feature flags | `fallow flags` |
 | check which architecture rules apply to a file before changing it | `fallow guard <files>` |
+| check import cycles, boundaries and policy rules after changing code | `fallow architecture` |
 | surface security candidates | `fallow security` |
 | understand a finding | `fallow explain <issue-type>` |
 | scope a monorepo | `--workspace <glob> / --changed-workspaces <ref>`; global flags, prefix any command |
@@ -90,7 +108,11 @@ Full command catalogue, one row per command: **[references/cli-reference.md](ref
 
 ## Issue Types
 
-Dead-code filter flags are one per issue type (`--unused-exports`, `--unused-types`, `--unused-deps`, `--circular-deps`, and so on). Passing one or more narrows `fallow dead-code` to those types; passing none reports every type. Every type suppresses the same way: `// fallow-ignore-next-line <issue-type>` above the finding, or `// fallow-ignore-file <issue-type>` at the top of the file; the bare form without a type suppresses all of them.
+Dead-code filter flags select issue categories (`--unused-exports`, `--unused-types`, `--unused-deps`, `--unused-files`, and so on). Some flags select related types together; `--unused-deps` covers several dependency types. Passing one or more narrows `fallow dead-code` to those categories. Passing none applies no issue-type filter.
+
+`fallow architecture` reports the architecture findings: circular dependencies, re-export cycles, package cycles, boundary violations and rule-pack policy violations. Use `--cycles`, `--boundaries` or `--policy` to select one kind. The JSON output has `kind: "architecture"` and its own `schema_version`, with the same arrays and finding ids as `dead-code`. `fallow dead-code` still reports these findings until the next major version. Its `--circular-deps`, `--re-export-cycles`, `--package-cycles`, `--boundary-violations` and `--policy-violations` flags are deprecated aliases. Run `fallow guard <files>` before an edit and `fallow architecture` after it. In bare `fallow`, `--only architecture` reports only these findings and `--skip architecture` removes them.
+
+For suppressible findings, use the placement listed in the issue catalogue: `// fallow-ignore-next-line <issue-type>` above the finding, or `// fallow-ignore-file <issue-type>` at the top of the file. Some types support only file-level suppression; others have no suppression comment. A bare supported form without a type suppresses all matching findings at that placement.
 
 `fallow explain <issue-type>` describes one type without running analysis, and the MCP server serves the same catalogue as the `fallow://issue-types` resource.
 
@@ -100,7 +122,7 @@ Full catalogue, one row per type: **[references/issue-types.md](references/issue
 
 Fallow ships an MCP server (`fallow-mcp`) that exposes these same analyses as agent tools. When the server is connected, its tools are already in your context with typed params and structured JSON returns, and each maps to a CLI fallback command. Prefer them when you want JSON without shelling out, or `code_execute` (Code Mode) to compose several read-only analyses in one sandboxed snippet (no single-call CLI equivalent). Otherwise use the CLI.
 
-The server also serves read-only reference resources (no subprocess, no analysis run, cacheable by URI; your client reads them through its own resource tool): `fallow://tools`, `fallow://issue-types`, `fallow://explain/{issue_type}`, `fallow://task-matrix`, and the config, plugin, and rule-pack JSON Schemas. Every payload is JSON and carries `fallow_version`.
+The server also serves read-only reference resources (no subprocess, no analysis run, cacheable by URI; your client reads them through its own resource tool): `fallow://tools`, `fallow://issue-types`, `fallow://explain/{issue_type}`, `fallow://task-matrix`, and the config, plugin, and rule-pack JSON Schemas. Every resource payload is JSON. Each content item carries the server version in `_meta.fallow_version`.
 
 Full tool catalogue, resource catalogue, key params, runtime source-map confidence tiers, shared timeouts, and the `next_steps` dispatch mapping: **[references/mcp.md](references/mcp.md)**.
 
@@ -113,6 +135,8 @@ Full tool catalogue, resource catalogue, key params, runtime source-map confiden
 - [Similar Code](references/similar-code.md): snapshot-stable discovery, inspection, and verdict workflow
 - [Node Bindings](references/node-bindings.md): embed the analysis engine in a Node.js process via NAPI
 
+To set up or modernize the code-quality tooling of a repository (package install, config, agent wiring, CI gate), use the `fallow-setup` skill.
+
 ## Common Workflows
 
 ### Audit a project for cleanup opportunities
@@ -240,7 +264,7 @@ fallow health --format json --quiet --group-by owner --score --ownership --save-
 fallow health --format json --quiet --group-by owner --score --workspace 'packages/*'
 ```
 
-`--group-by owner` partitions every metric by CODEOWNERS team (last-match-wins, GitHub semantics) with a directory-cached native resolver, so there is no need to parse CODEOWNERS or aggregate per owner yourself. With `--score`, each `groups[]` entry carries a first-class `health_score` (`{ score, grade, penalties: { dead_files, complexity, p90_complexity, maintainability, unused_deps, circular_deps, unit_size, coupling, duplication } }`) alongside its own `vital_signs` and per-file `file_scores[]` (`complexity_density`, `maintainability_index`). Human output renders a `● Per-owner health` table (`score / grade / files / hot`). `--save-snapshot` records a point-in-time entry that `--trend` reads later. This one command replaces a hand-rolled CODEOWNERS-resolution + per-owner-aggregation + scoring script end to end.
+`--group-by owner` partitions every metric by CODEOWNERS team (last-match-wins, GitHub semantics) with a native resolver, so there is no need to parse CODEOWNERS or aggregate per owner yourself. With `--score`, each `groups[]` entry carries a first-class `health_score` (`{ score, grade, penalties: { dead_files, complexity, p90_complexity, maintainability, unused_deps, circular_deps, unit_size, coupling, duplication } }`) alongside its own `vital_signs` and per-file `file_scores[]` (`complexity_density`, `maintainability_index`). Human output renders a `● Per-owner health` table (`score / grade / files / hot`). `--save-snapshot` records a point-in-time entry that `--trend` reads later. This one command replaces a hand-rolled CODEOWNERS-resolution + per-owner-aggregation + scoring script end to end.
 
 Caveat for root-only path aliases: in monorepos where TypeScript path aliases (e.g. `@myorg/*`) are declared only in a root `tsconfig.base.json` that the per-package `tsconfig.json` files do not extend, imports through those aliases do not resolve, so dead-code signals (unused files/exports, and the `dead_files` penalty in the per-owner `health_score`) carry false positives. The complexity, maintainability, coupling, hotspot, and ownership signals are computed per file from the AST and git history and stay accurate regardless. Prefer `health` (not `dead-code`) for per-team quality tracking there.
 
@@ -262,7 +286,7 @@ fallow dead-code --format json --quiet --save-baseline .fallow/snapshot.json
 fallow dead-code --format json --quiet --baseline .fallow/snapshot.json
 ```
 
-`--save-regression-baseline` / `--regression-baseline` / `--fail-on-regression` / `--tolerance` are count-based gates for `dead-code`, bare combined mode, and `flags --retirement` (a flags baseline needs a PATH; without `--retirement` the options have no effect on `flags` and it warns). `--save-baseline` / `--baseline` are identity-based (track finding identity, fail on new). `audit` rejects the global baseline flags and uses `--dead-code-baseline` / `--health-baseline` / `--dupes-baseline` instead.
+`--save-regression-baseline` / `--regression-baseline` / `--fail-on-regression` / `--tolerance` are count-based gates for `dead-code`, `architecture`, bare combined mode, and `flags --retirement` (a flags baseline needs a PATH; without `--retirement` the options have no effect on `flags` and it warns). `--save-baseline` / `--baseline` are identity-based (track finding identity, fail on new). `audit` rejects the global baseline flags and uses `--dead-code-baseline` / `--health-baseline` / `--dupes-baseline` instead.
 
 With no path, `--save-regression-baseline` updates `regression.baseline` in the discovered fallow config, or creates `.fallowrc.json` when none exists. Pass a path only when a standalone baseline file is preferred.
 
@@ -375,11 +399,11 @@ export const deprecatedHelper = () => {};
 ## Key Gotchas
 
 - **`fix --yes` is required** in non-TTY (agent) environments. Without it, `fix` exits with code 2
-- **Zero config by default.** Built-in framework plugins auto-detect, including Wuchale config, Contentlayer content roots, tap and tsd test entry points. Read `fallow schema.plugins` for the current registry and don't create config unless customization is needed
-- **Syntactic analysis only.** No TypeScript compiler, so fully dynamic `import(variable)` is not resolved
+- **Zero config by default.** Built-in framework plugins auto-detect, including Wuchale config, Contentlayer content roots, Kibana `kibana.jsonc` plugin entries, tap and tsd test entry points. Read `fallow schema.plugins` for the current registry and don't create config unless customization is needed
+- **Default analysis is syntactic.** Fully dynamic `import(variable)` is not resolved. Optional `--type-aware` analysis adds TypeScript checker evidence
 - **Function overloads are deduplicated.** TypeScript function overload signatures are merged into a single export (not reported as separate unused exports)
-- **Re-export chains are resolved.** Exports through barrel files are tracked, not falsely flagged
-- **`--changed-since` is additive.** Only new issues in changed files, not all issues in the project
+- **Re-export chains are resolved.** Fallow tracks exports through barrel files. Trace reported exports before removal when consumers may be outside static analysis
+- **`--changed-since` scopes findings to changed files.** Existing findings in those files can remain, and dead-code dependency findings remain project-wide. Use `fallow audit --gate new-only` to distinguish introduced findings from inherited ones
 
 For the full list with examples, see [references/gotchas.md](references/gotchas.md).