fallow 2.103.0 → 2.104.0

package/README.md

@@ -12,7 +12,7 @@ Fallow turns a JS/TS repository into a trusted quality report: health score, cha
 
 It helps you answer: what changed, what got riskier, what should be reviewed, what should be refactored, and what can be safely removed. No AI inside the analyzer. Fallow produces deterministic findings, typed output contracts, and traceable explanations that downstream tools can trust.
 
-Static analysis is free and open source. An optional paid runtime layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, 122 framework plugins, no Node.js runtime dependency for analysis. fallow's edge is doing more in one pass: dead code, duplication, dependencies, complexity, architecture, and security in a single tool. For head-to-head timings against [knip](https://knip.dev) and [jscpd](https://github.com/kucherenko/jscpd), see the [benchmarks](https://github.com/fallow-rs/fallow/tree/main/benchmarks): fallow is faster than knip on smaller projects, knip is faster on several larger repos, and jscpd's Rust rewrite is faster for raw duplication scanning.
+Static analysis is free and open source. An optional paid runtime layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, 123 framework plugins, no Node.js runtime dependency for analysis. fallow's edge is doing more in one pass: dead code, duplication, dependencies, complexity, architecture, and security in a single tool. For head-to-head timings against [knip](https://knip.dev) and [jscpd](https://github.com/kucherenko/jscpd), see the [benchmarks](https://github.com/fallow-rs/fallow/tree/main/benchmarks): fallow is faster than knip on smaller projects, knip is faster on several larger repos, and jscpd's Rust rewrite is faster for raw duplication scanning.
 
 ## Installation
 
@@ -107,7 +107,7 @@ Swap `npx` for `pnpm exec` / `yarn` / `bunx` to match your package manager. If `
 
 ## Framework support
 
-122 built-in plugins covering Next.js, Nuxt, Remix, Qwik, SvelteKit, Gatsby, Astro, Angular, NestJS, AdonisJS, Ember, Expo Router, Vite, Webpack, Vitest, Jest, Playwright, Cypress, Storybook, ESLint, TypeScript, Tailwind, UnoCSS, Prisma, Drizzle, Convex, Turborepo, Hardhat, and many more. Auto-detected from your `package.json`.
+123 built-in plugins covering Next.js, Nuxt, Remix, Qwik, SvelteKit, Gatsby, Astro, Angular, NestJS, AdonisJS, Ember, Expo Router, Vite, Webpack, Vitest, Jest, Playwright, Cypress, Storybook, ESLint, TypeScript, Tailwind, UnoCSS, Prisma, Drizzle, Convex, Turborepo, Hardhat, and many more. Auto-detected from your `package.json`.
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.103.0",
+  "version": "2.104.0",
   "description": "Deterministic codebase intelligence for TypeScript and JavaScript. Quality, risk, architecture, dependencies, duplication, and safe cleanup evidence for humans, CI, and agents. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, zero-config framework support.",
   "license": "MIT",
   "repository": {
@@ -80,16 +80,16 @@
     "detect-libc": "2.1.2"
   },
   "devDependencies": {
-    "@tanstack/intent": "0.1.1"
+    "@tanstack/intent": "0.3.2"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.103.0",
-    "@fallow-cli/darwin-x64": "2.103.0",
-    "@fallow-cli/linux-x64-gnu": "2.103.0",
-    "@fallow-cli/linux-arm64-gnu": "2.103.0",
-    "@fallow-cli/linux-x64-musl": "2.103.0",
-    "@fallow-cli/linux-arm64-musl": "2.103.0",
-    "@fallow-cli/win32-arm64-msvc": "2.103.0",
-    "@fallow-cli/win32-x64-msvc": "2.103.0"
+    "@fallow-cli/darwin-arm64": "2.104.0",
+    "@fallow-cli/darwin-x64": "2.104.0",
+    "@fallow-cli/linux-x64-gnu": "2.104.0",
+    "@fallow-cli/linux-arm64-gnu": "2.104.0",
+    "@fallow-cli/linux-x64-musl": "2.104.0",
+    "@fallow-cli/linux-arm64-musl": "2.104.0",
+    "@fallow-cli/win32-arm64-msvc": "2.104.0",
+    "@fallow-cli/win32-x64-msvc": "2.104.0"
   }
 }

package/schema.json

@@ -194,6 +194,9 @@
         "dynamic-segment-name-conflict": "error"
       }
     },
+    "unusedComponentProps": {
+      "$ref": "#/$defs/UnusedComponentPropsConfig"
+    },
     "boundaries": {
       "$ref": "#/$defs/BoundaryConfig",
       "default": {
@@ -1227,6 +1230,20 @@
         }
       ]
     },
+    "UnusedComponentPropsConfig": {
+      "description": "Options for the `unused-component-props` rule.\n\nLets a project exempt component props whose local destructure binding name\nmatches a regex from `unused-component-props`, honoring the\n\"accepted-but-intentionally-unused\" leading-underscore convention (Svelte 5\n`$props()`, React destructure) that mirrors TypeScript `noUnusedParameters`\nand ESLint `@typescript-eslint/no-unused-vars` `varsIgnorePattern` /\n`argsIgnorePattern`. Opt-in; an unset `ignorePattern` leaves the rule's\nbehavior unchanged.",
+      "type": "object",
+      "properties": {
+        "ignorePattern": {
+          "description": "Regex matched against each declared prop's LOCAL destructure binding name\n(e.g. `_stage` in `let { stage: _stage } = $props()`), which falls back\nto the public prop name when there is no alias. A prop whose local name\nmatches is treated as intentionally unused and never reported as\n`unused-component-props`. Matching is unanchored (substring), like\nESLint's `RegExp.test`, so anchor with `^_` to match a leading\nunderscore. Compiled and validated at config load (an invalid regex fails\nload). Applies to Vue, Svelte, Astro, and React/Preact props.",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
     "BoundaryConfig": {
       "description": "Architecture boundary configuration.",
       "type": "object",

package/skills/fallow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fallow
-description: Codebase intelligence for JavaScript and TypeScript. Free static layer reports quality, changed-code risk, cleanup opportunities (unused files, exports, types, dependencies), code duplication, circular dependencies, complexity hotspots, architecture boundary violations, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same health report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. 122 framework plugins, zero configuration, sub-second static analysis. Use when asked to analyze code health, audit PR risk, find cleanup opportunities or unused code, detect duplicates, check circular dependencies, audit complexity, check architecture boundaries, detect feature flags, surface security candidates, clean up the codebase, auto-fix issues, merge runtime coverage, or run fallow.
+description: Codebase intelligence for JavaScript and TypeScript. Free static layer reports quality, changed-code risk, cleanup opportunities (unused files, exports, types, dependencies), code duplication, circular dependencies, complexity hotspots, architecture boundary violations, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same health report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. 123 framework plugins, zero configuration, sub-second static analysis. Use when asked to analyze code health, audit PR risk, find cleanup opportunities or unused code, detect duplicates, check circular dependencies, audit complexity, check architecture boundaries, detect feature flags, surface security candidates, clean up the codebase, auto-fix issues, merge runtime coverage, or run fallow.
 license: MIT
 metadata:
   author: Bart Waardenburg
@@ -10,7 +10,7 @@ metadata:
 
 # Fallow: codebase intelligence for JavaScript and TypeScript
 
-Codebase intelligence for JavaScript and TypeScript. The free static layer reports quality, changed-code risk, cleanup opportunities, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. 122 framework plugins, zero configuration, sub-second static analysis.
+Codebase intelligence for JavaScript and TypeScript. The free static layer reports quality, changed-code risk, cleanup opportunities, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. 123 framework plugins, zero configuration, sub-second static analysis.
 
 ## When to Use
 - Finding cleanup opportunities (unused files, exports, types, enum/class members)
@@ -66,7 +66,6 @@ cargo install fallow-cli        # build from source
 ## Onboarding And Insight
 Offer setup only after a human-requested analysis shows findings and all signals match: `fallow config --path` exits 3, not CI, not a pipeline format, `fallow impact --format json --quiet` has `onboarding_declined: false`, and no offer happened this session. Ask after showing value. Choices: guard commits and PRs, baseline the existing backlog and clean by category, add AGENTS.md guidance, or keep as-is. On decline, run `fallow init --decline --quiet` and stay silent for this project. Mutate only after consent. For guards, inspect `fallow hooks status --format json --quiet`, then use `fallow hooks install --target agent` and `fallow hooks install --target git`; for large backlogs, pair the gate with `--save-baseline` / new-only guidance. Offer `fallow impact enable` as local-only value tracking, never as telemetry; also offer it once on already-configured projects when `fallow impact status --format json` has `enabled: false` and `explicit_decision: false`, and record a no with `fallow impact disable --quiet`. Surface value on clear events: if the agent gate blocked a commit or push and a later retry succeeded, mention what was contained; when `next_steps` carries id `impact-report`, run its command and relay the non-zero numbers to the user in one line. On request, summarize non-zero Impact counts. Ask about telemetry only after such a win, only if `fallow telemetry status --format json` has `explicit_decision: false`, and never run `fallow telemetry enable`.
 ## Task Cheat Sheet
-
 Route by intent before reaching for the big analysis commands. Same matrix as `fallow schema` (`task_matrix`) and the generated AGENTS.md section.
 
 <!-- generated:task-matrix:start -->
@@ -211,6 +210,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `get_blast_radius` | runtime-coverage | freemium | `coverage`, `group_by` | Runtime-context slice for blast-radius review. Same params as `check_runtime_coverage`; read `runtime_coverage.blast_radius` for stable `fallow:blast:<hash>` IDs, caller counts, traffic-weighted caller reach, optional cloud deploy touch counts, and low/medium/high risk bands. |
 | `get_importance` | runtime-coverage | freemium | `coverage`, `group_by` | Runtime-context slice for production-importance review. Same params as `check_runtime_coverage`; read `runtime_coverage.importance` for stable `fallow:importance:<hash>` IDs, invocations, cyclomatic complexity, owner count, 0-100 score, and templated reason. |
 | `get_cleanup_candidates` | runtime-coverage | freemium | `coverage`, `group_by` | Runtime-context slice for cleanup review. Same params as `check_runtime_coverage`; read `runtime_coverage.findings` for `safe_to_delete`, `review_required`, `low_traffic`, and `coverage_unavailable`. |
+| `get_token_blast_radius` | analysis | free | - | Design-token blast radius for Tailwind v4 @theme tokens AND CSS-in-JS defineVars/createTheme-family token definitions: per token, a consumer_count (static lower bound) and a capped located consumers[] sample tagged theme-var/css-var/utility/apply (Tailwind) or js-member (CSS-in-JS cross-module member access); descriptive context for sizing a token change, never a deletion gate |
 | `audit` | analysis | free | `gate`, `base`, `max_crap`, `coverage`, `runtime_coverage` | Combined dead-code + complexity + duplication for changed files, returns verdict. Set `gate` to `"new-only"` or `"all"`. Optional `runtime_coverage` (V8 dir / V8 JSON / Istanbul JSON) folds runtime findings into the same call; `min_invocations_hot` tunes the hot-path threshold (default 100). Runtime evidence appears under the audit `complexity` sub-result, including `coverage_intelligence` when combined evidence yields actionable recommendations. |
 | `decision_surface` | analysis | free | `base`, `max_decisions`, `workspace` | Surface the few consequential structural decisions a change embeds (coupling, public API, dependency), each as a judgment question with the routed expert; ranked, capped, and signal_id-anchored |
 | `fallow_explain` | introspection | free | `issue_type` | Explain one issue type without running analysis. Required `issue_type`; returns rationale, examples, fix guidance, and docs URL |
@@ -297,7 +297,7 @@ fallow list --entry-points --format json --quiet
 fallow list --plugins --format json --quiet
 ```
 
-Shows detected entry points and active framework plugins (122 built-in: Next.js, Vite, Ember, Wuchale, Jest, Storybook, Tailwind, PandaCSS, Contentlayer, tap, tsd, etc.).
+Shows detected entry points and active framework plugins (123 built-in: Next.js, Vite, Ember, Wuchale, Jest, Storybook, Tailwind, PandaCSS, Contentlayer, tap, tsd, etc.).
 
 ### Production-only analysis
 ```bash
@@ -443,7 +443,7 @@ When `--format json` is active and exit code is 2, errors are emitted as JSON on
 
 ## Configuration
 
-Fallow reads config from project root: `.fallowrc.json` > `.fallowrc.jsonc` > `fallow.toml` > `.fallow.toml`. Both `.fallowrc.json` and `.fallowrc.jsonc` accept JSON-with-comments syntax (same parser); the `.jsonc` extension lets editors auto-detect JSONC syntax highlighting. Most projects work with zero configuration thanks to 122 auto-detecting framework plugins.
+Fallow reads config from project root: `.fallowrc.json` > `.fallowrc.jsonc` > `fallow.toml` > `.fallow.toml`. Both `.fallowrc.json` and `.fallowrc.jsonc` accept JSON-with-comments syntax (same parser); the `.jsonc` extension lets editors auto-detect JSONC syntax highlighting. Most projects work with zero configuration thanks to 123 auto-detecting framework plugins.
 
 ```jsonc
 {
@@ -480,7 +480,7 @@ 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.** 122 framework plugins auto-detect, including Wuchale config, Contentlayer content roots, tap and tsd test entry points. Don't create config unless customization is needed
+- **Zero config by default.** 123 framework plugins auto-detect, including Wuchale config, Contentlayer content roots, tap and tsd test entry points. Don't create config unless customization is needed
 - **Syntactic analysis only.** No TypeScript compiler, so fully dynamic `import(variable)` is not resolved
 - **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

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

@@ -51,7 +51,7 @@ Analyzes the project for unused files, exports, dependencies, types, members, an
 | `--top` | `string` | - | Show only the top N items per category |
 | `--file` | `string` | - | Scope output to specific files. Only issues in the specified files are reported. Project-wide dependency issues are suppressed. Warns on non-existent paths. Useful for lint-staged |
 
-Common global flags for this command: [`--format`](#global-flags), [`--quiet`](#global-flags), [`--output-file`](#global-flags), [`--legacy-envelope`](#global-flags), [`--changed-since`](#global-flags), [`--max-file-size`](#global-flags), [`--production`](#global-flags), [`--no-production`](#global-flags), [`--production-dead-code`](#global-flags), [`--baseline`](#global-flags), [`--save-baseline`](#global-flags), [`--workspace`](#global-flags), [`--changed-workspaces`](#global-flags), [`--include-entry-exports`](#global-flags).
+Common global flags for this command: [`--format`](#global-flags), [`--quiet`](#global-flags), [`--output-file`](#global-flags), [`--changed-since`](#global-flags), [`--max-file-size`](#global-flags), [`--production`](#global-flags), [`--no-production`](#global-flags), [`--production-dead-code`](#global-flags), [`--baseline`](#global-flags), [`--save-baseline`](#global-flags), [`--workspace`](#global-flags), [`--changed-workspaces`](#global-flags), [`--include-entry-exports`](#global-flags).
 <!-- generated:flags:dead-code:end -->
 ### Issue Type Filters
 
@@ -398,7 +398,7 @@ Angular templates contribute synthetic `<template>` complexity findings whenever
 | `--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_state`, 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\|anonymized\|hash` | - | Privacy mode for author emails. `handle` shows the local-part only (default, with GitHub noreply unwrap and deterministic same-handle disambiguation). `anonymized` emits stable `xxh3:` pseudonyms; `hash` remains accepted as the legacy spelling. `raw` shows full addresses. Use `anonymized` in regulated environments. Implies `--ownership`. Configure default via `health.ownership.emailMode`. |
 | `--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. Each target's JSON can include `direct_callers[]` (direct importers with the symbols they import) and `clone_siblings[]` (duplicate-code siblings with stable `dup:<8hex>` fingerprints for `fallow dupes --trace`); both omitted when empty. Human output adds `importers:` / `clones:` lines only when that evidence is present. |
-| `--css` | `bool` | `false` | Add structural CSS analytics: specificity hotspots, !important density, over-complex selectors, deep nesting, and conservative cleanup candidates. Standard CSS is parsed structurally; preprocessor sources are scanned only where fallow can avoid expanding Sass/Less semantics. |
+| `--css` | `bool` | `false` | Add structural CSS analytics: specificity hotspots, !important density, over-complex selectors, deep nesting, and conservative cleanup candidates. Standard CSS is parsed structurally; preprocessor sources are scanned only where fallow can avoid expanding Sass/Less semantics. Also derives `styling_health`, a descriptive A-F grade for CSS quality scored separately from the code `health_score` (never gates); it weights design-token drift (hardcoded value sprawl) over byte-identical repetition. |
 | `--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. 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` | `string` | - | Fail (exit 1) only when the health score is below this threshold. Implies `--score`. Authoritative CI quality gate: when set, complexity findings are demoted to informational and the exit code is driven solely by the score, so `--min-score 0` always exits 0. Composes with `--min-severity`. |
@@ -508,7 +508,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.103.0",
+  "version": "2.104.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -835,6 +835,9 @@ Audits changed files for dead code, complexity, and duplication. Returns a verdi
 | `--max-decisions` | `string` | `4` | Cap on the number of consequential structural decisions surfaced in the review brief's decision surface (the working-memory limit). Default 4; clamped to the 3-5 band (4 plus or minus 1). Only consulted on the brief path |
 | `--walkthrough-guide` | `bool` | `false` | Emit the agent-contract WALKTHROUGH GUIDE: the current digest (brief + decision surface), the review direction, the JSON schema the agent must return, and a deterministic graph-snapshot hash pinned into the digest. The digest is built from the graph only (PR prose is never folded in, so it is injection-resistant). Implies the brief; always exits 0. A thin agent skill calls this to fetch the current guide, produces judgment JSON, then reopens with `--walkthrough-file` |
 | `--walkthrough-file` | `string` | - | Ingest an agent's judgment JSON and POST-VALIDATE it against the LIVE graph. Rejects any judgment whose `signal_id` fallow did not emit (anti-hallucination); refuses the whole payload as stale when the echoed graph-snapshot hash no longer matches (the tree moved). The verifier is the graph, not a second model. Implies the brief; always exits 0. The agent's free-text framing is fenced as non-deterministic and never gates or auto-posts |
+| `--walkthrough` | `bool` | `false` | Render the existing walkthrough guide as a staged HUMAN terminal tour (Stage 1 load-bearing / Stage 2 mechanical), or markdown with `--format markdown`. Implies the brief; always exits 0. `--format json --walkthrough` emits the same agent-contract JSON as `--walkthrough-guide` |
+| `--mark-viewed` | `string` | - | Record one or more changed files as VIEWED in the local walkthrough viewed-state ledger (`.fallow/walkthrough-state.json`), then render the tour. Files already viewed (and still current) collapse into the Cleared panel. Repeatable. Stale marks (the tree moved) are ignored on render but never deleted. Only consulted on the `--walkthrough` path |
+| `--show-cleared` | `bool` | `false` | Expand the Cleared panel in the human/markdown walkthrough tour: list each de-prioritized and already-viewed file instead of the collapsed one-line summary. Only consulted on the `--walkthrough` path |
 | `--show-deprioritized` | `bool` | `false` | Expand the de-prioritized units in the review brief's weighted focus map ("show me what you de-prioritized"). The `deprioritized` escape-hatch list is ALWAYS present in `--format json` regardless; this flag only re-expands the collapse-by-default human focus render. Only consulted on the brief path |
 
 Common global flags for this command: [`--format`](#global-flags), [`--quiet`](#global-flags), [`--changed-since`](#global-flags), [`--diff-file`](#global-flags), [`--diff-stdin`](#global-flags), [`--workspace`](#global-flags), [`--changed-workspaces`](#global-flags), [`--group-by`](#global-flags), [`--output-file`](#global-flags).
@@ -900,7 +903,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.103.0",
+  "version": "2.104.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -975,7 +978,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.103.0",
+  "version": "2.104.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1076,7 +1079,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "2.103.0",
+  "version": "2.104.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1105,7 +1108,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "2.103.0",
+  "version": "2.104.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1637,7 +1640,6 @@ Available on all commands:
 | `--group-by` | `owner\|directory\|package\|section` | - | Group output by CODEOWNERS ownership (`owner`), first path component (`directory`), workspace package (`package`, aliases: `workspace`, `pkg`), or GitLab CODEOWNERS `[Section]` headers (`section`, alias: `gl-section`). All output formats partition issues into labeled groups. `section` mode attaches an `owners` array to each group in JSON output |
 | `--performance` | `bool` | `false` | Show pipeline timing breakdown |
 | `--explain` | `bool` | `false` | JSON: include metric definitions in `_meta`. Human: print a `Description:` line under each section header. Always on for MCP. |
-| `--legacy-envelope` | `bool` | `false` | Emit the previous typed JSON root envelope without top-level `kind` |
 | `--explain-skipped` | `bool` | `false` | Show a per-pattern breakdown for default duplicate ignores |
 | `--summary` | `bool` | `false` | Show only category counts without individual items. Useful for dashboards and quick overviews |
 | `--ci` | `bool` | `false` | CI mode: `--format sarif --fail-on-issues --quiet` |
@@ -1813,7 +1815,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.103.0",
+  "version": "2.104.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1973,7 +1975,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.103.0",
+  "version": "2.104.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2017,11 +2019,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.103.0",
+  "version": "2.104.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.103.0",
+    "version": "2.104.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],
@@ -2229,6 +2231,7 @@ preset = "bulletproof"
 - `cache.maxSizeMb`: cap the serialized extraction cache size in megabytes. `FALLOW_CACHE_MAX_SIZE` wins over this config field
 - `usedClassMembers`: class method/property names that extend the built-in Angular/React lifecycle allowlist with framework-invoked names. Each entry is a plain string (global suppression) or a scoped object `{ extends?, implements?, members }` matching only classes with the given heritage. Strings can be exact names (`"agInit"`) or glob patterns (`"*"` matches every member, `"enter*"` prefix, `"*Handler"` suffix, `"on*Event"` combined). Use scoped rules for common names like `refresh` or `execute` to avoid false negatives on unrelated classes; global strings for unique names like `agInit`. Example: `["agInit", { "implements": "ICellRendererAngularComp", "members": ["refresh"] }, { "extends": "BaseCommand", "members": ["execute"] }, { "extends": "GrammarBaseListener", "members": ["enter*", "exit*"] }]`. Glob patterns that match zero members emit a `WARN` so dead allowlist entries surface. An unconstrained scoped rule (no `extends` or `implements`) is rejected at load time. Use plugin-level `usedClassMembers` in a `.fallow/plugins/*.jsonc` file for library-specific allowlists
 - `resolve.conditions`: additional package.json `exports` / `imports` condition names to honor during module resolution. Baseline conditions (`development`, `import`, `require`, `default`, `types`, `node`, plus `react-native` / `browser` under RN/Expo) are always included; user entries prepend ahead of them. Use for community conditions like `worker`, `edge-light`, `deno`, or custom bundler conditions. Example: `{ "resolve": { "conditions": ["worker", "edge-light"] } }`
+- `unusedComponentProps.ignorePattern`: opt-in regex that exempts a component prop from `unused-component-props` when the prop's LOCAL destructure binding name matches (the leading-underscore "accepted-but-intentionally-unused" convention, mirroring TS `noUnusedParameters` + ESLint `varsIgnorePattern` / `argsIgnorePattern`). Applies to Vue, Svelte, Astro, and React/Preact props. The match is on the local alias (`_stage` in `let { stage: _stage } = $props()`), not the public prop name the finding reports (`stage`); matching is unanchored like ESLint's `RegExp.test`, so anchor with `^_`. An invalid regex fails config load. Example: `{ "unusedComponentProps": { "ignorePattern": "^_" } }`
 
 ---
 

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 122 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 123 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
@@ -484,10 +484,16 @@ When `fallow health --css` reports `css_analytics.unused_theme_tokens`, treat th
 
 The detector intentionally abstains when a Tailwind plugin or published CSS surface could consume tokens invisibly. Always run the row's `actions[].command` verification before deleting a token, and do not run `fallow fix` for these rows.
 
+The same Tailwind v4 projects also get `css_analytics.token_consumers`, the reverse index: per `@theme` token, where it is consumed (a `consumer_count` plus a located `consumers[]` sample tagged `theme-var` / `css-var` / `utility` / `apply`), so you can read a token's blast radius before changing it. Treat `consumer_count` as a static lower bound: a computed class name such as `bg-${color}` is invisible to the scan, so a `0` here is the same "nothing fallow can see consumes this" population as `unused_theme_tokens`, not a deletion proof. `token_consumers` is descriptive context with no `actions[]`; drive any deletion off `unused_theme_tokens` and its verification command.
+
+`token_consumers` also covers CSS-in-JS token DEFINITIONS (StyleX `defineVars`, vanilla-extract `createTheme` / `createThemeContract` / `createGlobalTheme`), disambiguated by the consumer `kind`: a CSS-in-JS entry has `kind` `js-member`, `token` is the binding-qualified dotted access path (`vars.color.primary`), and `namespace` is the defining binding (`vars`). The cross-file scan resolves only relative imports, so a token consumed through a path alias (`@/tokens`) or a bare-package import is not counted (a sharper lower bound), and unlike Tailwind there is no corroborating dead-token finding, so a CSS-in-JS `consumer_count` of `0` is a weaker signal. Gated on a declared CSS-in-JS library (`@stylexjs/stylex` / `@vanilla-extract/css`); Panda (`defineTokens` / `token('...')`) is a planned follow-on.
+
 ## CSS Health Candidates Are Advisory
 
 `fallow health --css` also emits advisory cleanup and typo candidates in `css_analytics.unreferenced_css_classes` (a plain-CSS class defined but matched by no `class`/`className` in project markup), `css_analytics.unresolved_class_references` (the reverse: a markup class one edit away from a defined class, a likely typo), `css_analytics.unused_font_faces`, `css_analytics.undefined_keyframes`, and `css_analytics.font_size_unit_mix`. Treat them like review prompts, not confirmed defects. Run each row's `actions[].command` before changing CSS, because fonts, classes, animations, and type scales can be driven by inline styles, JavaScript, CMS templates, or preprocessor expansion that static analysis intentionally does not execute.
 
+`fallow health --css` also derives `styling_health`, a descriptive A-F grade (and 0-100 `score`) for CSS quality, scored SEPARATELY from the code `health_score`. It is descriptive-only: it never gates an exit code, badge, or CI, and never affects the code score, so do NOT branch automation on it. Read it as a design-system credibility signal. It weights design-token DRIFT over byte-identical repetition: the `token_erosion` penalty includes a hardcoded-value-sprawl term over distinct `box-shadow` / `border-radius` / `line-height` values, but counts only HARDCODED literals: a system that references its scale via `var(--*)` scores 0 sprawl regardless of how many tokens it defines (so "tokenize repeated values" is the remedy the human output suggests). A grade from a thin CSS surface (or predominantly compile-time-atomic CSS-in-JS like StyleX/Panda) is marked `confidence: "low"` with a reason. `styling_health.formula_version` bumps when the rubric is recalibrated; if you diff the score/grade over time, gate on it and re-baseline at a bump rather than reading the step-change as a regression.
+
 ---
 
 ## Library Packages: Use `publicPackages` Instead of Visibility Tags

package/skills/fallow/references/patterns.md

@@ -640,7 +640,7 @@ Focus on findings that are BOTH dead code and duplicated:
 
 ## Custom Plugin Setup
 
-For frameworks not covered by the 122 built-in plugins.
+For frameworks not covered by the 123 built-in plugins.
 
 ### Option 1: Inline framework config
 

package/types/output-contract.d.ts

@@ -25,7 +25,7 @@
 
 
 /**
- * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator (for example `dead-code`, `dead-code-grouped`, `health`, `dupes`, `combined`, `audit`, `explain`, `inspect_target`, `impact`, `security`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `review-envelope`, and `review-reconcile`). Consumers should branch on `kind` instead of probing for unique field presence. `--legacy-envelope` removes only the document-root `kind` for one compatibility cycle. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array.
+ * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator (for example `dead-code`, `dead-code-grouped`, `health`, `dupes`, `combined`, `audit`, `explain`, `inspect_target`, `impact`, `security`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `review-envelope`, and `review-reconcile`). Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array.
  */
 export type FallowJsonOutput = (FallowOutput | CodeClimateOutput)
 /**
@@ -34,11 +34,9 @@ export type FallowJsonOutput = (FallowOutput | CodeClimateOutput)
  * schema derived from this enum drives the document-root `oneOf` in
  * `docs/output-schema.json`.
  *
- * The default wire shape now carries a top-level `kind` discriminator so
- * agents and schema-validating clients can select the variant in O(1) instead
- * of probing for unique field presence. `--legacy-envelope` is a one-cycle
- * compatibility flag that removes only this document-root `kind` field from
- * CLI JSON output; nested report objects are not rewritten.
+ * The wire shape carries a top-level `kind` discriminator so agents and
+ * schema-validating clients can select the variant in O(1) instead of probing
+ * for unique field presence.
  *
  * One envelope is intentionally NOT in this enum:
  * - `CodeClimateOutput` serializes as a bare JSON array
@@ -601,6 +599,24 @@ export type CssCandidateActionType = ("verify-unused" | "verify-undefined" | "co
  * Discriminant for [`UnusedAtRule::kind`].
  */
 export type UnusedAtRuleKind = ("property-registration" | "layer")
+/**
+ * The surface through which a design token is consumed. The `theme-var` /
+ * `css-var` / `utility` / `apply` kinds are Tailwind v4 `@theme` consumption; the
+ * `js-member` kind is CSS-in-JS consumption (a cross-module member access on an
+ * imported StyleX/vanilla-extract token binding). The kind is the disjoint origin
+ * signal that distinguishes a Tailwind token entry from a CSS-in-JS token entry in
+ * the shared `token_consumers` list.
+ */
+export type ConsumerKind = ("theme-var" | "css-var" | "utility" | "apply" | "js-member")
+/**
+ * Trust level for a [`StylingHealth`] grade. TWO variants (not the three-tier
+ * `high`/`medium`/`low` of [`crate::Confidence`] / `FeatureFlagConfidence`) ON
+ * PURPOSE: styling confidence is binary (the grade is either reliable for the
+ * analyzed surface or it is not), not three distinct evidence tiers, so a
+ * never-emitted `Medium` would be dead surface. Serializes lowercase (`"high"` /
+ * `"low"`), matching the sibling confidence enums' vocabulary.
+ */
+export type StylingHealthConfidence = ("high" | "low")
 export type InspectTargetDescriptor = ({
 file: string
 type: "file"
@@ -788,12 +804,14 @@ export type RiskClass = ("low" | "medium" | "high")
  */
 export type ReviewEffort = ("glance" | "review" | "deep_dive")
 /**
- * The focus label for a review unit. EXACTLY two variants: `Skip` is NOT
- * representable, so the type system is the guarantee that free mode never emits
- * a `skip` label (safe explicit-skip is paid, runtime-backed only). Mirrors
- * the decision surface's "cut category not representable" structural posture.
+ * The focus label for a review unit. `Skip` is the SAFE explicit-skip label and
+ * is runtime-backed ONLY: it is producible solely on the paid runtime path
+ * and solely for a unit runtime-proves cold with zero risk signals. Free mode
+ * (no runtime evidence) emits only `ReviewHere` / `NotPrioritized`, never `Skip`
+ * (the build-focus-map labeller cannot reach the `Skip` arm without runtime
+ * input), so the free-tier "rank but never skip" stance holds by construction.
  */
-export type FocusLabel = ("review-here" | "not-prioritized")
+export type FocusLabel = ("review-here" | "not-prioritized" | "skip")
 /**
  * A per-unit confidence flag. The EXACT panel-decided strings: a dynamically-
  * wired or re-export-heavy unit carries one so its static-reachability signal is
@@ -4017,6 +4035,14 @@ framework_health?: (FrameworkHealthDiagnostics | null)
  * over-complex selectors, deep nesting). Present only with `--css`.
  */
 css_analytics?: (CssAnalyticsReport | null)
+/**
+ * Styling-health score and letter grade: a SECOND health axis derived from
+ * the CSS analytics (the design-system axis), orthogonal to the JS/TS code
+ * `health_score`. Present only with `--css` (the same condition as
+ * `css_analytics`), so a plain `fallow health` run is byte-unchanged. The
+ * code score is never affected by this field.
+ */
+styling_health?: (StylingHealth | null)
 }
 /**
  * Wire envelope for a single complexity finding.
@@ -5882,6 +5908,18 @@ unused_font_faces?: UnusedFontFace[]
  * downstream repo. Sorted by `(path, line, token)`.
  */
 unused_theme_tokens?: UnusedThemeToken[]
+/**
+ * A location-aware reverse index of Tailwind v4 `@theme` token consumers:
+ * per token, where it is consumed (`var()` reads, `@apply` bodies, generated
+ * utility classes) and through which surface, plus the full `consumer_count`
+ * (a static lower bound) and the defining site. Built from the same gated
+ * candidate set as `unused_theme_tokens` (v4 + non-plugin + non-published +
+ * whole-scope), so a token with `consumer_count: 0` is the same "nothing
+ * consumes this" signal. Sorted by token; empty when the project is not
+ * Tailwind v4 or a plugin / published-library / partial-scope run gated the
+ * scan out.
+ */
+token_consumers?: TokenConsumers[]
 /**
  * The project authors `font-size` values in several units (`px`, `rem`,
  * `em`, `%`), with a per-unit distinct-value count: a type-scale
@@ -6068,11 +6106,16 @@ nesting_depth: number
 /**
  * Project-wide CSS analytics aggregates across every analyzed stylesheet
  * (including stylesheets with no notable rule, which are not listed
- * individually).
+ * individually in `files`).
  */
 export interface CssAnalyticsSummary {
 /**
- * Stylesheets analyzed (standard CSS only; SCSS is skipped).
+ * Stylesheets analyzed: standard `.css` files, Vue/Svelte SFC `<style>`
+ * blocks, and (dep-gated) CSS-in-JS, both the tagged-template form and the
+ * object form (`style({...})` / `stylex.create({...})` / `css({...})`). SCSS
+ * is skipped. Note: flat atomic object CSS-in-JS (StyleX/Panda) is counted
+ * here and contributes to these aggregates, but has no notable rules, so its
+ * files never appear in the per-file `files` list.
  */
 files_analyzed: number
 /**
@@ -6526,6 +6569,92 @@ line: number
  */
 actions: CssCandidateAction[]
 }
+/**
+ * A location-aware reverse index of where one design token is consumed, so an
+ * agent editing the token can see its blast radius before changing or removing
+ * it. Covers TWO token origins. The always-available discriminator is the `token`
+ * SHAPE: a Tailwind token is the `--`-prefixed custom property (`--color-brand`),
+ * a CSS-in-JS token is a dotted access path with no `--` prefix
+ * (`vars.color.primary`). The per-consumer `kind` also discriminates origin, but
+ * only when `consumer_count > 0` (a `consumer_count: 0` entry has an empty
+ * `consumers` array and thus no `kind`), so branch on the `token` prefix for the
+ * zero-consumer case. The two origins:
+ *
+ * - Tailwind v4 `@theme` tokens (kinds `theme-var` / `css-var` / `utility` /
+ *   `apply`), built from the same gated candidate set as `unused_theme_tokens`
+ *   (v4 + non-plugin + non-published + whole-scope), so a `consumer_count: 0`
+ *   corroborates the `unused_theme_tokens` "nothing consumes this" finding.
+ * - CSS-in-JS tokens (kind `js-member`) from StyleX `defineVars` /
+ *   vanilla-extract `createTheme` family definitions, consumed via cross-module
+ *   member access. NOTE: CSS-in-JS has NO corroborating dead-token finding (there
+ *   is no `unused_theme_tokens` analogue), so a CSS-in-JS `consumer_count: 0` is a
+ *   weaker signal than the Tailwind case (and the cross-file scan is relative-import
+ *   only, so alias / bare-package imports are not counted).
+ *
+ * This is DESCRIPTIVE context (a blast-radius lookup), not a finding, so it
+ * deliberately carries no `actions` array (unlike the cleanup-candidate types in
+ * this module). `consumer_count` is always a STATIC lower bound (a computed class
+ * name like `bg-${color}`, or a CSS-in-JS access through an unresolved alias
+ * import, is not counted).
+ */
+export interface TokenConsumers {
+/**
+ * The token identity. For a Tailwind `@theme` token this is the full custom
+ * property as authored, INCLUDING the `--` prefix (`--color-brand`). For a
+ * CSS-in-JS token (kind `js-member`) this is the binding-qualified dotted
+ * access path, NO `--` prefix (`vars.color.primary`), matching how consumers
+ * read it. The presence of the `--` prefix distinguishes the two origins.
+ */
+token: string
+/**
+ * For a Tailwind token, the v4 theme namespace (`color`, `radius`,
+ * `font-weight`, ...). For a CSS-in-JS token (kind `js-member`), the defining
+ * export BINDING the token set is accessed through (`vars`), which identifies
+ * the token set, NOT a semantic group. (The field is thus overloaded by
+ * origin; branch on `consumers[].kind` or the `token` shape.)
+ */
+namespace: string
+/**
+ * Project-root-relative, forward-slash path to the declaring stylesheet
+ * (Tailwind) or the JS/TS token-definition file (CSS-in-JS).
+ */
+definition_path: string
+/**
+ * 1-based line of the token's definition (inside the `@theme` block for
+ * Tailwind; the token key inside the `defineVars`/`createTheme` object for
+ * CSS-in-JS).
+ */
+definition_line: number
+/**
+ * The FULL number of consumer locations found, a STATIC LOWER BOUND: a
+ * computed class name (`bg-${color}`) or a value read outside CSS/markup the
+ * scan never sees is not counted. This is the aggregate over every consumer,
+ * computed BEFORE [`consumers`](Self::consumers) is capped to a sample.
+ */
+consumer_count: number
+/**
+ * A capped, deterministically-sorted sample of consumer locations (at most
+ * [`TOKEN_CONSUMER_SAMPLE_CAP`]). The full count lives in
+ * [`consumer_count`](Self::consumer_count); use this list to jump to
+ * representative consumers, not to enumerate every one.
+ */
+consumers: TokenConsumerLocation[]
+}
+/**
+ * Where one Tailwind v4 `@theme` token is consumed, and through which surface.
+ * One entry in a [`TokenConsumers::consumers`] sample.
+ */
+export interface TokenConsumerLocation {
+/**
+ * Project-root-relative, forward-slash path to the consuming file.
+ */
+path: string
+/**
+ * 1-based line of the consuming reference in that file.
+ */
+line: number
+kind: ConsumerKind
+}
 /**
  * A design-token notation-consistency candidate: the distinct notations used
  * across the codebase for one value axis (today, length units on `font-size`),
@@ -6564,6 +6693,75 @@ notation: string
  */
 count: number
 }
+/**
+ * Project-level styling-health score: a SECOND health axis computed purely from
+ * the structural CSS analytics (`CssAnalyticsReport`), orthogonal to the JS/TS
+ * code-health [`HealthScore`]. Surfaced only alongside the `--css` analytics, so
+ * a plain `fallow health` run is byte-unchanged. The code score and grade stay
+ * untouched: styling health is additive, never folded into the code score.
+ *
+ * Like [`HealthScore`], the score starts at 100 and subtracts capped per-category
+ * penalties; the grade reuses the shared [`letter_grade`] thresholds verbatim
+ * (A>=85, B>=70, C>=55, D>=40, F<40), so the two axes are read on one scale.
+ */
+export interface StylingHealth {
+formula_version: number
+score: number
+grade: string
+penalties: StylingHealthPenalties
+confidence: StylingHealthConfidence
+/**
+ * Human-readable reason the grade is low-confidence: either the declaration
+ * and stylesheet counts a thin grade was computed from, or that structure is
+ * not assessable for compile-time-atomic CSS-in-JS. `None` when confidence is
+ * `High`. Prose, not a stable machine field: gate on `confidence`, not on
+ * this string.
+ */
+confidence_reason?: (string | null)
+}
+/**
+ * Per-category penalty breakdown for the styling-health score. Each field is the
+ * number of points subtracted from a starting 100 for one CSS signal family,
+ * already capped at its category ceiling. A `0.0` field means "the signal was
+ * evaluated and clean"; the whole struct is only ever built when CSS analytics
+ * were produced, so there is no "missing pipeline" ambiguity to model with
+ * `Option` here (the parent `StylingHealth` is itself `Option` on the report).
+ */
+export interface StylingHealthPenalties {
+/**
+ * Copy-paste declaration blocks (`duplicate_declaration_blocks`), scaled by
+ * total removable declarations. Capped at 20pt.
+ */
+duplication: number
+/**
+ * Dead styling surface, two independently-normalized terms summed and capped
+ * at 20pt: (a) unused `@theme` tokens as a share of the total `@theme` token
+ * population (size-independent, so a declaration-sparse Tailwind project is
+ * not penalized for a few dead tokens); plus (b) the other dead entities
+ * (unreferenced classes, unused `@property`/`@layer` at-rules, dead
+ * `@font-face` families) as a share of `total_declarations`.
+ */
+dead_surface: number
+/**
+ * Broken references: markup classes one edit from a defined class
+ * (`unresolved_class_references`) and animations referencing a `@keyframes`
+ * defined nowhere (`undefined_keyframes`). Capped at 15pt.
+ */
+broken_references: number
+/**
+ * Design-token erosion: mixed `font-size` units (`font_size_unit_mix`),
+ * Tailwind arbitrary-value bypasses (`tailwind_arbitrary_values`), and
+ * distinct HARDCODED `box-shadow`/`border-radius`/`line-height` values above
+ * per-axis baselines (the v3 value-sprawl drift sub-term; `var(--*)`-
+ * referenced values are not counted). Capped at 10pt.
+ */
+token_erosion: number
+/**
+ * Structural smells from the summary aggregates: `!important` density and
+ * deep style-rule nesting. Capped at 10pt.
+ */
+structural: number
+}
 /**
  * Envelope emitted by `fallow explain <issue-type> --format json`.
  *
@@ -6991,6 +7189,14 @@ framework_health?: (FrameworkHealthDiagnostics | null)
  * over-complex selectors, deep nesting). Present only with `--css`.
  */
 css_analytics?: (CssAnalyticsReport | null)
+/**
+ * Styling-health score and letter grade: a SECOND health axis derived from
+ * the CSS analytics (the design-system axis), orthogonal to the JS/TS code
+ * `health_score`. Present only with `--css` (the same condition as
+ * `css_analytics`), so a plain `fallow health` run is byte-unchanged. The
+ * code score is never affected by this field.
+ */
+styling_health?: (StylingHealth | null)
 grouped_by?: (GroupByMode | null)
 groups?: (HealthGroup[] | null)
 _meta?: (Meta | null)
@@ -8778,10 +8984,11 @@ export interface FocusMap {
  */
 review_here: FocusUnit[]
 /**
- * EVERY `not-prioritized` unit (the escape hatch). Always present and fully
+ * EVERY de-prioritized unit (`not-prioritized`, plus runtime-backed `skip`
+ * units on the paid path) -- the escape hatch. Always present and fully
  * enumerated so a reviewer can always "show me what you de-prioritized"; the
  * human brief collapses it by default and re-expands under
- * `--show-deprioritized`.
+ * `--show-deprioritized`. Nothing is ever hidden, including a `skip`.
  */
 deprioritized: FocusUnit[]
 }
@@ -8806,9 +9013,9 @@ reason: string
 confidence?: ConfidenceFlag[]
 }
 /**
- * The composite attention score, with the four deterministic component
- * sub-scores kept on the wire so the runtime seam can re-weight `total`
- * without recomputing the signals.
+ * The composite attention score, with the deterministic component sub-scores
+ * kept on the wire so the runtime layer adds its weight without recomputing the
+ * signals.
  */
 export interface FocusScore {
 /**
@@ -8829,7 +9036,16 @@ risk_zone: number
  */
 change_shape: number
 /**
- * The summed total. The paid runtime layer multiplies a runtime hot/cold weight in here.
+ * Runtime-weight component (paid): a hot path (runtime evidence of high
+ * invocation) adds an invocation-bucketed weight so it amplifies the blast
+ * and outranks an otherwise-equal cold unit. `0` in free mode (no runtime
+ * input), so the free-tier total stays the four deterministic components and
+ * is byte-identical to the no-runtime baseline.
+ */
+runtime?: number
+/**
+ * The summed total of every present component (the four deterministic ones
+ * plus the runtime weight).
  */
 total: number
 }