fallow 3.32.0 → 3.33.1

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.32.0",
+  "version": "3.33.1",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -142,7 +142,7 @@
       "name": "--baseline",
       "type": "string",
       "required": false,
-      "description": "Compare against a previously saved baseline file. Used by bare `fallow`, `dead-code`, `dupes` and `health`; other subcommands reject it"
+      "description": "Compare against a previously saved baseline file. Used by bare `fallow`, `dead-code`, `architecture`, `dupes` and `health`; other subcommands reject it. On bare `fallow` it holds the dead-code baseline only: pass health and duplication baselines with `--health-baseline` and `--dupes-baseline`"
     },
     {
       "name": "--baseline-mode",
@@ -164,7 +164,7 @@
       "name": "--save-baseline",
       "type": "string",
       "required": false,
-      "description": "Save the current results as a baseline file. Used by bare `fallow`, `dead-code`, `dupes` and `health`; other subcommands reject it. The path must resolve inside the project root, its Git work tree, the CI workspace or a temp directory"
+      "description": "Save the current results as a baseline file. Used by bare `fallow`, `dead-code`, `architecture`, `dupes` and `health`; other subcommands reject it. On bare `fallow` it saves the dead-code baseline only: save the others with `fallow health --save-baseline` and `fallow dupes --save-baseline`. The path must resolve inside the project root, its Git work tree, the CI workspace or a temp directory"
     },
     {
       "name": "--production",
@@ -311,7 +311,7 @@
       "name": "--sarif-file",
       "type": "string",
       "required": false,
-      "description": "Write SARIF output to a file (in addition to the primary --format output). Used by bare `fallow`, `dead-code` and `security`. The path must resolve inside the project root, its Git work tree, the CI workspace or a temp directory"
+      "description": "Write SARIF output to a file (in addition to the primary --format output). Used by bare `fallow`, `dead-code`, `architecture` and `security`. The path must resolve inside the project root, its Git work tree, the CI workspace or a temp directory"
     },
     {
       "name": "--output-file",
@@ -399,7 +399,8 @@
       "possible_values": [
         "dead-code",
         "dupes",
-        "health"
+        "health",
+        "architecture"
       ]
     },
     {
@@ -410,7 +411,8 @@
       "possible_values": [
         "dead-code",
         "dupes",
-        "health"
+        "health",
+        "architecture"
       ]
     },
     {
@@ -585,6 +587,16 @@
         "false"
       ]
     },
+    {
+      "name": "--show-cascade",
+      "type": "bool",
+      "required": false,
+      "description": "Also report the unused exports, types, class members and enum members of unused files. By default the report hides them, because deleting the file removes them, and counts them in `cascade_hidden`",
+      "possible_values": [
+        "true",
+        "false"
+      ]
+    },
     {
       "name": "--type-aware",
       "type": "bool",
@@ -625,7 +637,7 @@
   "commands": [
     {
       "name": "dead-code",
-      "description": "Analyze project for unused code and circular dependencies",
+      "description": "Analyze project for unused code and dependency hygiene",
       "flags": [
         {
           "name": "--unused-files",
@@ -851,7 +863,7 @@
           "name": "--circular-deps",
           "type": "bool",
           "required": false,
-          "description": "Only report circular dependencies",
+          "description": "Only report circular dependencies. Deprecated alias: use `fallow architecture --cycles`",
           "possible_values": [
             "true",
             "false"
@@ -861,7 +873,7 @@
           "name": "--re-export-cycles",
           "type": "bool",
           "required": false,
-          "description": "Only report re-export cycles",
+          "description": "Only report re-export cycles. Deprecated alias: use `fallow architecture --cycles`",
           "possible_values": [
             "true",
             "false"
@@ -871,7 +883,7 @@
           "name": "--package-cycles",
           "type": "bool",
           "required": false,
-          "description": "Only report dependency cycles between workspace packages",
+          "description": "Only report dependency cycles between workspace packages. Deprecated alias: use `fallow architecture --cycles`",
           "possible_values": [
             "true",
             "false"
@@ -881,7 +893,7 @@
           "name": "--boundary-violations",
           "type": "bool",
           "required": false,
-          "description": "Only report boundary violations",
+          "description": "Only report boundary violations. Deprecated alias: use `fallow architecture --boundaries`",
           "possible_values": [
             "true",
             "false"
@@ -891,7 +903,7 @@
           "name": "--policy-violations",
           "type": "bool",
           "required": false,
-          "description": "Only report rule-pack policy violations",
+          "description": "Only report rule-pack policy violations. Deprecated alias: use `fallow architecture --policy`",
           "possible_values": [
             "true",
             "false"
@@ -1023,6 +1035,60 @@
         }
       ]
     },
+    {
+      "name": "architecture",
+      "description": "Check import cycles, boundaries and policy rules after editing",
+      "flags": [
+        {
+          "name": "--cycles",
+          "type": "bool",
+          "required": false,
+          "description": "Only report import cycles: circular dependencies, re-export cycles and package cycles",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
+        {
+          "name": "--boundaries",
+          "type": "bool",
+          "required": false,
+          "description": "Only report boundary violations, boundary coverage and forbidden calls",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
+        {
+          "name": "--policy",
+          "type": "bool",
+          "required": false,
+          "description": "Only report rule-pack policy violations",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
+        {
+          "name": "--file",
+          "type": "string",
+          "required": false,
+          "description": "Only report issues in the specified file(s). Accepts multiple values. The full project graph is still built, but only issues in matching files are reported"
+        },
+        {
+          "name": "--finding-id",
+          "type": "string",
+          "required": false,
+          "description": "Only report the findings with these `finding_id` values. Repeat the flag or pass a comma-separated list"
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "required": false,
+          "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed"
+        }
+      ]
+    },
     {
       "name": "watch",
       "description": "Watch for changes and re-run analysis",
@@ -1131,7 +1197,41 @@
           "name": "symbol",
           "type": "string",
           "required": false,
-          "description": "Target symbol, formatted as FILE:SYMBOL (e.g. src/utils.ts:formatDate). Omitted when `--path` is used"
+          "description": "Target symbol, formatted as FILE:SYMBOL (e.g. src/utils.ts:formatDate). Omitted when `--path` or `--dependency` is used"
+        },
+        {
+          "name": "--dependency",
+          "type": "string",
+          "required": false,
+          "description": "How the code uses each imported name of a package: file and call counts, one hop through project wrappers, and a count of each use that the trace cannot resolve"
+        },
+        {
+          "name": "--specifier",
+          "type": "string",
+          "required": false,
+          "description": "With `--dependency`, report only these imported names (repeatable or comma-separated). Turns on the site page"
+        },
+        {
+          "name": "--sites",
+          "type": "bool",
+          "required": false,
+          "description": "With `--dependency`, list the usage sites with file, line and column",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
+        {
+          "name": "--limit",
+          "type": "string",
+          "required": false,
+          "description": "With `--dependency`, the largest number of sites on a page (1 to 500, default 50). Turns on the site page"
+        },
+        {
+          "name": "--cursor",
+          "type": "string",
+          "required": false,
+          "description": "With `--dependency`, the `next_cursor` of the previous page. Turns on the site page"
         },
         {
           "name": "--path",
@@ -2161,6 +2261,11 @@
       "description": "Maintain reusable audit base-snapshot caches",
       "flags": []
     },
+    {
+      "name": "baselines",
+      "description": "Maintain the committed baseline files that the config points at",
+      "flags": []
+    },
     {
       "name": "decision-surface",
       "description": "Surface the consequential structural DECISIONS a change embeds (the apex of the review brief), each framed as a judgment question with the routed expert to ask",
@@ -2268,7 +2373,7 @@
           "name": "--from",
           "type": "string",
           "required": true,
-          "description": "Path to a fallow JSON results file produced by `--format json` (dead-code, dupes, health, audit, security, or bare combined)"
+          "description": "Path to a fallow JSON results file produced by `--format json` (dead-code, architecture, dupes, health, audit, security, or bare combined)"
         }
       ]
     },
@@ -7037,6 +7142,24 @@
         "read_only": false,
         "code_mode_alias": "checkChanged"
       },
+      {
+        "name": "check_architecture",
+        "kind": "analysis",
+        "description": "Architecture check: import cycles, boundary violations, and rule-pack policy violations in the `architecture` envelope, each with a stable finding_id",
+        "cli_command": "fallow architecture --format json --quiet",
+        "key_params": [
+          "cycles",
+          "boundaries",
+          "policy",
+          "baseline",
+          "group_by",
+          "file"
+        ],
+        "license": "free",
+        "license_note": null,
+        "read_only": true,
+        "code_mode_alias": "checkArchitecture"
+      },
       {
         "name": "security_candidates",
         "kind": "analysis",
@@ -7558,10 +7681,14 @@
       {
         "name": "trace_dependency",
         "kind": "trace",
-        "description": "Trace where a dependency is imported and whether scripts or CI use it",
+        "description": "Trace where a dependency is imported, whether scripts or CI use it, and how the code uses each imported name",
         "cli_command": "fallow dead-code --trace-dependency <package> --format json --quiet",
         "key_params": [
-          "package_name"
+          "package_name",
+          "specifiers",
+          "sites",
+          "limit",
+          "cursor"
         ],
         "license": "free",
         "license_note": null,
@@ -7674,7 +7801,7 @@
     ]
   },
   "plugins": {
-    "count": 133,
+    "count": 134,
     "note": "Built-in framework plugins, auto-activated when their enabler dependency is present; run fallow list --plugins for the set active in a specific project",
     "names": [
       "nextjs",
@@ -7695,6 +7822,7 @@
       "firebase",
       "nestjs",
       "nestjs-trpc",
+      "nest-commander",
       "adonis",
       "docusaurus",
       "gatsby",
@@ -7833,6 +7961,11 @@
       "command": "fallow dead-code --trace-dependency <name>",
       "note": null
     },
+    {
+      "task": "migrate a dependency",
+      "command": "fallow trace --dependency <name> --sites",
+      "note": "Counts each imported name, follows one hop through project wrappers, and counts each use that it cannot resolve."
+    },
     {
       "task": "commit or open a PR",
       "command": "fallow audit --base <ref>",
@@ -7873,6 +8006,11 @@
       "command": "fallow guard <files>",
       "note": null
     },
+    {
+      "task": "check import cycles, boundaries and policy rules after changing code",
+      "command": "fallow architecture",
+      "note": null
+    },
     {
       "task": "surface security candidates",
       "command": "fallow security",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.32.0",
+  "version": "3.33.1",
   "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",
@@ -89,14 +89,14 @@
     "@tanstack/intent": "0.4.0"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.32.0",
-    "@fallow-cli/darwin-x64": "3.32.0",
-    "@fallow-cli/linux-x64-gnu": "3.32.0",
-    "@fallow-cli/linux-arm64-gnu": "3.32.0",
-    "@fallow-cli/linux-x64-musl": "3.32.0",
-    "@fallow-cli/linux-arm64-musl": "3.32.0",
-    "@fallow-cli/win32-arm64-msvc": "3.32.0",
-    "@fallow-cli/win32-x64-msvc": "3.32.0",
-    "fallow-type-aware": "3.32.0"
+    "@fallow-cli/darwin-arm64": "3.33.1",
+    "@fallow-cli/darwin-x64": "3.33.1",
+    "@fallow-cli/linux-x64-gnu": "3.33.1",
+    "@fallow-cli/linux-arm64-gnu": "3.33.1",
+    "@fallow-cli/linux-x64-musl": "3.33.1",
+    "@fallow-cli/linux-arm64-musl": "3.33.1",
+    "@fallow-cli/win32-arm64-msvc": "3.33.1",
+    "@fallow-cli/win32-x64-msvc": "3.33.1",
+    "fallow-type-aware": "3.33.1"
   }
 }

package/schema.json

@@ -380,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",

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

@@ -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
@@ -85,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` |
@@ -93,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 |
@@ -106,7 +108,9 @@ Full command catalogue, one row per command: **[references/cli-reference.md](ref
 
 ## Issue Types
 
-Dead-code filter flags select issue categories (`--unused-exports`, `--unused-types`, `--unused-deps`, `--circular-deps`, 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.
+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.
 
@@ -282,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). On bare `fallow` they hold the dead-code baseline only; pass health and duplication baselines with `--health-baseline` / `--dupes-baseline`. `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.