@hominis/fireforge 0.18.1 → 0.18.3

package/README.md

@@ -143,6 +143,9 @@ fireforge re-export --all --scan
 # Preview what an export would do without writing
 fireforge export browser/base/content/browser.js --dry-run
 
+# Same preview surface for the aggregate path
+fireforge export-all --name "all-changes" --category ui --dry-run
+
 # Insert a new patch at a specific position
 fireforge export browser/base/content/browser.js --order 3 --name "inserted" --category ui
 fireforge export browser/base/content/browser.js --before 005-ui-sidebar.patch --name "prelim"
@@ -158,7 +161,7 @@ fireforge re-export --files browser/base/content/browser.js 002-ui-toolbar
 fireforge re-export --all --scan --stamp
 ```
 
-`export` refuses when the new patch's `filesAffected` would overlap with files already claimed by another non-superseded patch. Repartitioning ownership is a deliberate operation: the message points at `fireforge re-export --files <paths> <patch>` as the safe primitive. Pass `--allow-overlap` to acknowledge the conflict and proceed anyway — the resulting queue will fail `fireforge verify` immediately, so this is an intentional escape hatch, not a default.
+`export` refuses when the new patch's `filesAffected` would overlap with files already claimed by another non-superseded patch. Repartitioning ownership is a deliberate operation: the message points at `fireforge re-export --files <paths> <patch>` as the safe primitive. Pass `--allow-overlap` to acknowledge the conflict and proceed anyway — the resulting queue will fail `fireforge verify` immediately, so this is an intentional escape hatch, not a default. The flag covers cross-patch _modification_ overlap, where two patches both edit the same file. It does NOT bypass the new-file creation guard: two patches creating the same path on `/dev/null` cannot coexist in any apply order, so that case stays a hard refusal regardless of `--allow-overlap`.
 
 `re-export --scan` also prompts before broadening a patch with more than a handful of newly discovered files or with files spanning multiple directories. The gate keeps the common refresh case frictionless (small, same-directory additions) while catching the failure mode where `--scan` silently pulls an adjacent feature into the wrong patch. Non-interactive mode requires `--yes` to acknowledge a broad expansion; dry-run previews never require confirmation.
 
@@ -210,7 +213,11 @@ This re-exports the fixed patch and clears the conflict state. The command is de
 
 The optional `lintIgnore` field lists lint check IDs to suppress for that patch specifically. Useful for the class of patch that is advisory-noisy by nature — a cohesive branding bundle, a localised-resource pack, an auto-generated manifest — where `--skip-lint` is too blunt and a per-line marker cannot exist (the `.patch` body is regenerated on every export). Threaded through `export`, `re-export`, `re-export --files`, and `lint --per-patch`. Unknown check IDs are a no-op.
 
-The optional `tier` field (only `"branding"` recognised) forces the branding threshold tier for the `large-patch-lines` rule regardless of what `filesAffected` looks like. The automatic branding-tier detection already fires when every file is under `browser/branding/` plus a narrow allowlist of branding-registration siblings (`browser/moz.configure`, `browser/confvars.sh`) — covering the canonical Firefox fork shape. Declare `tier: "branding"` only when the patch legitimately also touches a non-allowlisted sibling the auto-detector cannot reach (a fork-specific theme override under `browser/themes/<name>/`, a vendor-specific icon resource, etc.). Precedence is `test > branding > general`: a patch of all-tests always gets the more permissive test-tier thresholds even if it declares `tier: "branding"`. Unknown tier values are rejected at load time rather than silently stripped, so a typo surfaces as a loader error. Prefer `tier` over `lintIgnore: ["large-patch-lines"]` when the patch is legitimately branding-shaped — `tier` keeps the rule running at the correct thresholds (so the warning still surfaces if the patch crosses them); `lintIgnore` drops the rule entirely.
+Settable through the CLI in two places. `fireforge export --lint-ignore <check-id>` (repeatable) writes the field on creation; `fireforge re-export <name> --lint-ignore <check-id>` (repeatable, append/union semantics, de-duplicated) adds entries to an existing patch on the next refresh. For metadata-only edits that should **not** regenerate the `.patch` body — including the inverse `--remove` and `--clear` modes that re-export's append-only flag cannot express — use `fireforge patch lint-ignore <name> --add <id> | --remove <id> | --clear`.
+
+The optional `tier` field (only `"branding"` recognised) forces the branding threshold tier for the `large-patch-files` and `large-patch-lines` rules regardless of what `filesAffected` looks like. The automatic branding-tier detection already fires when every file is under `browser/branding/` plus a narrow allowlist of branding-registration siblings (`browser/moz.configure`, `browser/confvars.sh`) — covering the canonical Firefox fork shape. Declare `tier: "branding"` only when the patch legitimately also touches a non-allowlisted sibling the auto-detector cannot reach (a fork-specific theme override under `browser/themes/<name>/`, a vendor-specific icon resource, etc.). Precedence is `test > branding > general`: a patch of all-tests always gets the more permissive test-tier thresholds even if it declares `tier: "branding"`. Unknown tier values are rejected at load time rather than silently stripped, so a typo surfaces as a loader error. Prefer `tier` over `lintIgnore: ["large-patch-lines"]` when the patch is legitimately branding-shaped — `tier` keeps the rule running at the correct thresholds (so the warning still surfaces if the patch crosses them); `lintIgnore` drops the rule entirely.
+
+Settable via `fireforge export --tier branding` on creation, `fireforge re-export <name> --tier branding` on refresh, and `fireforge patch tier <name> --tier branding | --clear` for a metadata-only edit that does not rewrite the `.patch` body. The CLI rejects values other than `branding` up-front (matching the validator's strictness), and `re-export --tier` / `--lint-ignore` refuse `--all` because mass tier/ignore edits across a heterogeneous queue are virtually always footguns.
 
 If the manifest drifts after an interrupted export or manual edits, `fireforge import` will stop rather then silently applying a stale stack. Use `fireforge doctor --repair-patches-manifest` to rebuild it from disk. Because the rebuild is deterministic, the result will always be consistent with what is actually on the filesystem.
 
@@ -223,24 +230,24 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed — with tool-managed branding paths (`browser/branding/<binaryName>/`) excluded. A fresh-setup workspace carries a large generated branding diff that operators did not author directly, and letting it through tripped the patch-size and license-header rules on content that matches the `branding` bucket in `fireforge status`. When the exclusion fires the command prints a one-line note naming the excluded count so the filter is visible. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further — explicit-path mode does lint branding files (the operator's explicit request wins over the branding exclusion); the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
 
-| Check                          | Scope                                                                                           | Severity                 |
-| ------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------ |
-| `missing-license-header`       | New files (JS/CSS/FTL)                                                                          | error                    |
-| `relative-import`              | JS/MJS files                                                                                    | error                    |
-| `token-prefix-violation`       | CSS files (with furnace)                                                                        | error                    |
-| `raw-color-value`              | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                       | error                    |
-| `duplicate-new-file-creation`  | Same path created by multiple patches                                                           | error                    |
-| `forward-import`               | Patch imports from a later-patch file                                                           | error                    |
-| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`                                                               | error                    |
-| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`                                                               | error                    |
-| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`                                                               | error                    |
-| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)                                                                 | error                    |
-| `missing-modification-comment` | Modified upstream JS/MJS                                                                        | warning                  |
-| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)                                                            | warning                  |
-| `file-too-large`               | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                    | notice / warning / error |
-| `observer-topic-naming`        | Observer topics with binaryName                                                                 | warning                  |
-| `large-patch-files`            | Patches affecting >5 files                                                                      | warning                  |
-| `large-patch-lines`            | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 3000/8000/20000 branding) | notice / warning / error |
+| Check                          | Scope                                                                                            | Severity                 |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------ |
+| `missing-license-header`       | New files (JS/CSS/FTL)                                                                           | error                    |
+| `relative-import`              | JS/MJS files                                                                                     | error                    |
+| `token-prefix-violation`       | CSS files (with furnace)                                                                         | error                    |
+| `raw-color-value`              | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                        | error                    |
+| `duplicate-new-file-creation`  | Same path created by multiple patches                                                            | error                    |
+| `forward-import`               | Patch imports from a later-patch file                                                            | error                    |
+| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)                                                                  | error                    |
+| `missing-modification-comment` | Modified upstream JS/MJS                                                                         | warning                  |
+| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)                                                             | warning                  |
+| `file-too-large`               | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                     | notice / warning / error |
+| `observer-topic-naming`        | Observer topics with binaryName                                                                  | warning                  |
+| `large-patch-files`            | Patches affecting many files (tiered: >5 general, >5 test, >60 branding)                         | warning                  |
+| `large-patch-lines`            | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 8000/18000/30000 branding) | notice / warning / error |
 
 **JSDoc validation** uses AST-based analysis (Acorn) to validate exported APIs in patch-owned `.sys.mjs` files. A file is "patch-owned" if it was newly created by the current diff or by an existing patch in the queue. Functions must document every `@param` (names must match) and include `@returns` when the function returns a value. Exported constants and classes require a JSDoc block.
 
@@ -263,16 +270,16 @@ fireforge status --json             # machine-readable classified output
 
 Then fix with the appropriate primitive:
 
-| Problem                                        | Fix                                                                                                          |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Two patches each creating the same file        | `fireforge patch delete <duplicate>` or `fireforge re-export --files`                                        |
-| A patch imports from a module in a later patch | `fireforge patch reorder <later> --before <importer>`                                                        |
-| Wrong patch ordering                           | `fireforge patch reorder <patch> --to <N>`                                                                   |
-| Ordinal gaps after deletes/splits              | `fireforge patch compact`                                                                                    |
-| A patch claims files that belong elsewhere     | `fireforge re-export --files <subset> <patch>`                                                               |
-| Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                                                                 |
-| Dangling widget / locale registration in patch | Re-run `fireforge export` without `--exclude-furnace` to capture the source files, or revert furnace changes |
-| Unmanaged changes you want to discard          | `fireforge discard <file>` or `fireforge reset`                                                              |
+| Problem                                        | Fix                                                                                                              |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Two patches each creating the same file        | `fireforge patch delete <duplicate>` or `fireforge re-export --files`                                            |
+| A patch imports from a module in a later patch | `fireforge patch reorder <later> --before <importer>`                                                            |
+| Wrong patch ordering                           | `fireforge patch reorder <patch> --to <N>`                                                                       |
+| Ordinal gaps after deletes/splits              | `fireforge patch compact`                                                                                        |
+| A patch claims files that belong elsewhere     | `fireforge re-export --files <subset> <patch>`                                                                   |
+| Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                                                                     |
+| Dangling widget / locale registration in patch | Re-run `fireforge export` without `--exclude-furnace` to capture the source files, or revert furnace changes     |
+| Unmanaged changes you want to discard          | `fireforge discard <file>` (also accepts a directory path to discard everything beneath it) or `fireforge reset` |
 
 Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` as the file is owned by FireForge — `doctor --repair-patches-manifest` reconstructs missing metadata, and `fireforge re-export <filename> --description "<text>"` overwrites recovered entries with operator-supplied metadata through the tool. `fireforge verify` cross-checks every registration hunk in each patch body against the files the queue and engine supply, so a patch that registers a widget / locale without carrying its source surfaces as a `dangling-registration` error rather than slipping through as "Verify clean"; `fireforge export-all --exclude-furnace` refuses up-front when it would produce that shape.
 
@@ -436,11 +443,21 @@ fireforge patch reorder 003-ui-sidebar.patch --before 001-branding-logo.patch
 
 # Close ordinal gaps after deletes or splits (e.g. 1, 3, 7 → 1, 2, 3)
 fireforge patch compact
+
+# Set or clear the threshold-tier override on a single patch
+# (no .patch body rewrite — manifest entry only)
+fireforge patch tier 001-branding-assets.patch --tier branding
+fireforge patch tier 001-branding-assets.patch --clear
+
+# Edit the lintIgnore list on a single patch (one mode per invocation)
+fireforge patch lint-ignore 001-branding-assets.patch --add large-patch-lines --add large-patch-files
+fireforge patch lint-ignore 001-branding-assets.patch --remove large-patch-lines
+fireforge patch lint-ignore 001-branding-assets.patch --clear
 ```
 
-`delete` and `reorder` accept three identifier forms for their target: the ordinal number (`fireforge patch reorder 3 --to 1`), the full filename (`003-ui-sidebar-tweaks.patch`), or the manifest `name` handle the patch was exported with (`ui-sidebar-tweaks`). Anchors passed to `--before` / `--after` accept the same three forms.
+All `patch <verb>` subcommands accept three identifier forms for their target: the ordinal number (`fireforge patch reorder 3 --to 1`), the full filename (`003-ui-sidebar-tweaks.patch`), or the manifest `name` handle the patch was exported with (`ui-sidebar-tweaks`). Anchors passed to `--before` / `--after` accept the same three forms. All subcommands support `--dry-run` and `--yes`.
 
-All subcommands support `--dry-run` and `--yes`.
+`patch tier` and `patch lint-ignore` are metadata-only edits: they update `patches/patches.json` under the patch directory lock and never rewrite the `.patch` body. Reach for them when an operator-visible advisory (e.g. `large-patch-files` firing on a 56-file fresh-fork branding bundle) needs the threshold-tier override or a per-patch lint suppression but the patch body is already correct — running `re-export` for that case wastes an engine read + diff regeneration. `patch lint-ignore` modes (`--add` / `--remove` / `--clear`) are mutually exclusive; `patch tier` rejects `--tier` and `--clear` together. The history log records each invocation under `operation: "patch-tier"` / `"patch-lint-ignore"` for audit.
 
 ### Additional workflow commands
 
@@ -452,7 +469,11 @@ fireforge package
 fireforge watch
 
 # Add a CSS design token (requires `fireforge furnace init` first; see the Furnace/Tokens section below)
-fireforge token add --category 'Colors — General' -- --my-color 'light-dark(#fff, #000)'
+# The `--` separator is required because the token name itself starts with `--`,
+# which Commander would otherwise read as an option flag. Bare names without `--`
+# are accepted directly and get the configured `tokenPrefix` prepended.
+fireforge token add --category 'Colors — General' --mode static -- --my-color 'light-dark(#fff, #000)'
+fireforge token add --category 'Colors — General' --mode static my-color   '#fff'   # bare-name form
 ```
 
 Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` also registers the tokens CSS path in `patchLint.rawColorAllowlist` so raw color literals inside it are not flagged by `fireforge lint`, and derives `tokenPrefix: --<binaryName>-` from `fireforge.json`'s `binaryName` so `fireforge token coverage` has a prefix to key off on the very first run. Projects that prefer a different prefix can override it in `furnace.json` after init.

package/dist/src/commands/discard.js

@@ -11,6 +11,82 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, isCancel, outro, spinner, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
+/**
+ * Discards every status entry whose path lives under `dirPath`. Used by
+ * `discardCommand` as a directory-recursion fallback when the operator
+ * passed a directory path that contains modified or untracked entries
+ * but is not itself a status entry.
+ *
+ * Mirrors the single-file path's confirmation, dry-run, and Furnace-aware
+ * warning behaviour so the contract stays consistent. Each per-entry
+ * discard runs sequentially under its own try/catch so a failure on one
+ * file is reported but does not block the remaining files in the batch.
+ */
+async function discardDirectoryEntries(projectRoot, engineDir, dirPath, entries, options) {
+    if (!options.yes && !options.dryRun) {
+        const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+        if (!isInteractive) {
+            throw new InvalidArgumentError('Interactive confirmation not available. Use --yes flag to discard without confirmation.', 'Use: fireforge discard <directory> --yes');
+        }
+        const confirmed = await confirm({
+            message: `Discard changes to ${entries.length} file${entries.length === 1 ? '' : 's'} under ${dirPath}/?`,
+            initialValue: false,
+        });
+        if (isCancel(confirmed) || !confirmed) {
+            outro('Discard cancelled');
+            return;
+        }
+    }
+    if (options.dryRun) {
+        info(`Would discard changes to ${entries.length} file(s) under ${dirPath}/:`);
+        for (const entry of entries) {
+            const target = entry.originalPath && entry.originalPath !== entry.file
+                ? `${entry.originalPath} -> ${entry.file}`
+                : entry.file;
+            info(`  ${target}`);
+        }
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    const s = spinner(`Discarding ${entries.length} file(s) under ${dirPath}/...`);
+    let succeeded = 0;
+    const failures = [];
+    try {
+        for (const entry of entries) {
+            try {
+                await discardStatusEntry(engineDir, entry);
+                succeeded += 1;
+            }
+            catch (error) {
+                failures.push(`${entry.file}: ${toError(error).message}`);
+            }
+        }
+        s.stop(`Discarded ${succeeded} of ${entries.length} file(s) under ${dirPath}/${failures.length > 0 ? ` (${failures.length} failed)` : ''}`);
+        for (const failure of failures) {
+            warn(`  ${failure}`);
+        }
+        try {
+            const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+            const dirIsFurnace = [...furnacePrefixes].some((prefix) => `${dirPath}/`.startsWith(prefix) || prefix.startsWith(`${dirPath}/`));
+            if (dirIsFurnace) {
+                warn('These paths are managed by Furnace. Run "fireforge furnace apply" to redeploy components if needed.');
+            }
+        }
+        catch {
+            // Furnace config may not exist — skip silently
+        }
+        if (failures.length > 0) {
+            throw new GeneralError(`Failed to discard ${failures.length} file(s) under ${dirPath}/. See warnings above.`);
+        }
+        outro(`${succeeded} file(s) restored to original state`);
+    }
+    catch (error) {
+        if (!(error instanceof GeneralError)) {
+            s.error('Discard failed');
+        }
+        throw error;
+    }
+}
 /**
  * Runs the discard command to revert changes to a specific file.
  * @param projectRoot - Root directory of the project
@@ -31,7 +107,23 @@ export async function discardCommand(projectRoot, file, options = {}) {
     // Check if the file has changes
     const statusEntries = await expandUntrackedDirectoryEntries(paths.engine, await getWorkingTreeStatus(paths.engine));
     const statusEntry = statusEntries.find((entry) => entry.file === file || entry.originalPath === file);
+    // Directory recursion fallback: when the explicit path does not match a
+    // single status entry but DOES correspond to one or more entries below
+    // it, treat the input as a directory and discard everything inside.
+    // 2026-04-25 eval Finding 20: `discard browser/components/storybook/
+    // stories/furnace --yes` failed with "no changes to discard" even
+    // though `status --unmanaged` listed 23 files under that directory —
+    // operators were forced to discard each file individually or fall
+    // back to non-FireForge cleanup commands. Match against the
+    // directory-with-trailing-slash form so a path like `foo/bar` doesn't
+    // accidentally match `foo/bar2/file`.
     if (!statusEntry) {
+        const dirPrefix = file.endsWith('/') ? file : `${file}/`;
+        const dirEntries = statusEntries.filter((entry) => entry.file.startsWith(dirPrefix) || entry.originalPath?.startsWith(dirPrefix));
+        if (dirEntries.length > 0) {
+            await discardDirectoryEntries(projectRoot, paths.engine, file, dirEntries, options);
+            return;
+        }
         throw new GeneralError(`File "${file}" has no changes to discard.`);
     }
     if (!options.yes && !options.dryRun) {
@@ -91,7 +183,7 @@ export async function discardCommand(projectRoot, file, options = {}) {
 export function registerDiscard(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('discard <file>')
-        .description('Discard changes to a specific file (deletes untracked files)')
+        .description('Discard changes to a specific file (deletes untracked files). Pass a directory path to discard every modified or untracked file beneath it; the operation walks the status output and reverts each match individually.')
         .option('--dry-run', 'Show what would be discarded without doing it')
         .option('-y, --yes', 'Skip confirmation prompt')
         .action(withErrorHandling(async (file, options) => {

package/dist/src/commands/doctor.js

@@ -9,7 +9,7 @@ import { ExitCode } from '../errors/codes.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
-import { executableExists } from '../utils/process.js';
+import { findExecutable } from '../utils/process.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 /**
@@ -255,9 +255,22 @@ const DOCTOR_CHECKS = [
         // failure site.
         name: 'Watchman available',
         run: async () => {
-            const present = await executableExists('watchman');
-            if (present)
-                return ok('Watchman available');
+            // Resolve the absolute path so the OK row names what doctor actually
+            // found. The 2026-04-25 eval flagged a confusing case where the
+            // operator's interactive shell returned no result for `which
+            // watchman` but doctor still printed "OK" — the cause was a
+            // PATH-export discrepancy between the shell and the spawned
+            // subprocess, and surfacing the resolved path makes the discrepancy
+            // visible without users having to re-run with a verbose flag.
+            const path = await findExecutable('watchman');
+            if (path) {
+                return {
+                    name: 'Watchman available',
+                    passed: true,
+                    severity: 'ok',
+                    message: `OK (${path})`,
+                };
+            }
             return warning('Watchman available', 'watchman is not installed or not on PATH. "fireforge watch" requires it.', 'Install watchman (brew install watchman / dnf install watchman / https://facebook.github.io/watchman/), then re-run doctor.');
         },
     },

package/dist/src/commands/download.js

@@ -69,6 +69,25 @@ async function cleanPatchTouchedFiles(engineDir, patchesDir, preExistingDirty) {
     }
     return { hadQueue: true, restored: toClean.length, preserved: preserved.length };
 }
+/**
+ * Prints a one-line nudge pointing at `fireforge import` when the project
+ * carries a non-empty patch queue but the just-downloaded engine has not
+ * yet had any patches applied. The post-download spinner closes with
+ * "Patch-touched files already match baseline" because a fresh tree IS at
+ * baseline, but the 2026-04-25 eval saw operators read that as "patches
+ * are restored" and skip the import step. The note is suppressed when
+ * patches/ is missing or the manifest is empty so unconfigured projects
+ * stay quiet.
+ */
+async function noteUnappliedPatches(patchesDir) {
+    if (!(await pathExists(patchesDir)))
+        return;
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest || manifest.patches.length === 0)
+        return;
+    const n = manifest.patches.length;
+    info(`Note: ${n} patch${n === 1 ? '' : 'es'} in patches/ have not been applied to this fresh engine. Run "fireforge import" to apply them.`);
+}
 /**
  * Stops `restoreSpinner` with a message that reflects what actually
  * happened. Three branches: empty queue → explicit no-op; queue present but
@@ -151,6 +170,7 @@ export async function downloadCommand(projectRoot, options) {
                                 downloadedVersion: version,
                                 baseCommit,
                             });
+                            await noteUnappliedPatches(paths.patches);
                             outro(`Firefox ${version} is ready! (resumed from partial init)`);
                             return;
                         }
@@ -299,6 +319,7 @@ export async function downloadCommand(projectRoot, options) {
         downloadedVersion: version,
         baseCommit,
     });
+    await noteUnappliedPatches(paths.patches);
     outro(`Firefox ${version} is ready!`);
 }
 /** Registers the download command on the CLI program. */

package/dist/src/commands/export-all.js

@@ -15,6 +15,7 @@ import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { PATCH_CATEGORIES } from '../utils/validation.js';
+import { renderDryRunPreview } from './export-flow.js';
 import { autoFixLicenseHeaders, confirmSupersedePatches, guardOwnershipOverlap, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
 async function checkBrandingManagedFiles(paths, config) {
     const changedFiles = await getWorkingTreeStatus(paths.engine);
@@ -158,7 +159,8 @@ async function checkDuplicateNewFileCreations(paths, diff) {
         .join('\n');
     throw new GeneralError('Export-all refuses to capture new-file creations that are already claimed by existing patches.\n\n' +
         `Conflicting creations:\n${conflictList}\n\n` +
-        'Only one patch may create a given path. Run "fireforge export <path> [...]" with an explicit file list that omits the already-claimed path(s), or resolve the conflict via "fireforge patch delete" / "fireforge re-export --files" before retrying export-all.');
+        'Only one patch may create a given path — two creation hunks on /dev/null cannot coexist in any apply order, so this case is structurally unrecoverable rather than verify-failing. The --allow-overlap escape hatch covers cross-patch MODIFICATION overlap (which yields a queue that fails verify but still applies); it deliberately does NOT cover this case. ' +
+        'Run "fireforge export <path> [...]" with an explicit file list that omits the already-claimed path(s), or resolve the conflict via "fireforge patch delete" / "fireforge re-export --files" before retrying export-all.');
 }
 /**
  * Runs the export-all command to export all changes as a patch.
@@ -166,7 +168,8 @@ async function checkDuplicateNewFileCreations(paths, diff) {
  * @param options - Export options
  */
 export async function exportAllCommand(projectRoot, options = {}) {
-    intro('FireForge Export All');
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge Export All (dry run)' : 'FireForge Export All');
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     if (!(await pathExists(paths.engine))) {
@@ -236,13 +239,38 @@ export async function exportAllCommand(projectRoot, options = {}) {
     if (!metadata)
         return;
     const { patchName, selectedCategory, description } = metadata;
-    // Ensure patches directory exists
-    await ensureDir(paths.patches);
-    const s = spinner('Exporting all changes...');
+    // Ensure patches directory exists. Skip during a dry-run so the command
+    // is purely read-only — `--dry-run` callers should be safe to invoke
+    // against a project that has never exported a patch without leaving the
+    // empty `patches/` directory behind.
+    if (!isDryRun) {
+        await ensureDir(paths.patches);
+    }
+    const s = spinner(isDryRun ? 'Planning export-all...' : 'Exporting all changes...');
     try {
         // Extract affected files from diff
         const filesAffected = extractAffectedFiles(diff);
         await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint);
+        // Dry-run: enumerate filename, metadata, and supersede coverage without
+        // writing. Mirrors `fireforge export --dry-run` so the same preview
+        // surface is available for both targeted and aggregate exports. Runs
+        // AFTER lint so the operator sees the same lint output they would on
+        // a real run; runs BEFORE the supersede confirmation prompt because
+        // confirming a dry-run is meaningless.
+        if (isDryRun) {
+            s.stop('Plan ready');
+            await renderDryRunPreview({
+                patchesDir: paths.patches,
+                category: selectedCategory,
+                name: patchName,
+                description,
+                filesAffected,
+                sourceEsrVersion: config.firefox.version,
+                explicitSupersede: options.supersede === true,
+            });
+            outro('Dry run complete — no changes made');
+            return;
+        }
         // Check how many existing patches would be superseded
         const shouldProceed = await confirmSupersedePatches(paths.patches, filesAffected, options.supersede, isInteractive, s);
         if (!shouldProceed)
@@ -299,7 +327,8 @@ export function registerExportAll(program, { getProjectRoot, withErrorHandling }
         .option('--supersede', 'Allow superseding multiple existing patches')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--exclude-furnace', 'Export the non-Furnace subset of the aggregate diff instead of refusing when Furnace-managed files are modified. Furnace-managed files are still deployed by "fireforge furnace apply"; this flag only changes whether export-all aborts or filters in their presence.')
-        .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap with non-superseded patches (the resulting queue fails verify)')
+        .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap with non-superseded patches (the resulting queue fails verify). Does not bypass the new-file creation guard — two patches creating the same path is structurally unrecoverable, so that case still refuses regardless of this flag.')
+        .option('--dry-run', 'Print the export-all plan (filename, metadata, files affected, supersede preview) without writing anything to patches/. Lint still runs so the operator sees the same lint output a real run would produce.')
         .action(withErrorHandling(async (options) => {
         const { category, ...rest } = options;
         await exportAllCommand(getProjectRoot(), {

package/dist/src/commands/export-flow.d.ts

@@ -82,6 +82,10 @@ export interface DryRunPreviewInput {
     filesAffected: string[];
     sourceEsrVersion: string;
     explicitSupersede: boolean;
+    /** Optional `PatchMetadata.tier` opt-in carried from the CLI. */
+    tier?: 'branding';
+    /** Optional `PatchMetadata.lintIgnore` carried from the CLI. */
+    lintIgnore?: string[];
 }
 /**
  * Renders the plain (non-placement) dry-run preview: calls planExport,

package/dist/src/commands/export-flow.js

@@ -314,12 +314,20 @@ export async function renderDryRunPreview(input) {
         description: input.description,
         filesAffected: input.filesAffected,
         sourceEsrVersion: input.sourceEsrVersion,
+        ...(input.tier !== undefined ? { tier: input.tier } : {}),
+        ...(input.lintIgnore !== undefined ? { lintIgnore: input.lintIgnore } : {}),
     });
     info(`\n[dry-run] Would write: patches/${plan.patchFilename}`);
     info(`  category: ${plan.metadata.category}`);
     info(`  order: ${plan.metadata.order}`);
     info(`  description: ${plan.metadata.description || '(none)'}`);
     info(`  filesAffected (${plan.metadata.filesAffected.length}): ${plan.metadata.filesAffected.join(', ')}`);
+    if (plan.metadata.tier !== undefined) {
+        info(`  tier: ${plan.metadata.tier}`);
+    }
+    if (plan.metadata.lintIgnore !== undefined && plan.metadata.lintIgnore.length > 0) {
+        info(`  lintIgnore: ${plan.metadata.lintIgnore.join(', ')}`);
+    }
     if (supersedeDetails.length > 0) {
         info(`\n[dry-run] Would supersede ${supersedeDetails.length} existing patch(es):`);
         for (const detail of supersedeDetails) {

package/dist/src/commands/export.js

@@ -172,7 +172,15 @@ export async function exportCommand(projectRoot, files, options) {
     try {
         // Extract affected files from diff
         const filesAffected = extractAffectedFiles(diff);
-        await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint);
+        // Apply the just-set --tier and --lint-ignore on the lint pass so the
+        // operator's intent takes effect on this invocation, not only on the
+        // next one. Without this, a fresh export with `--tier branding` would
+        // still hit general thresholds because the lint runs before the
+        // metadata is committed.
+        const exportIgnoreChecks = options.lintIgnore && options.lintIgnore.length > 0
+            ? new Set(options.lintIgnore)
+            : undefined;
+        await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint, undefined, exportIgnoreChecks, options.tier);
         // Resolve placement (if any flag was given). Placement is mutually
         // exclusive with supersede — the semantics overlap confusingly.
         let placementPlan = null;
@@ -225,6 +233,10 @@ export async function exportCommand(projectRoot, files, options) {
                 filesAffected,
                 sourceEsrVersion: config.firefox.version,
                 explicitSupersede: options.supersede === true,
+                ...(options.tier !== undefined ? { tier: options.tier } : {}),
+                ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+                    ? { lintIgnore: options.lintIgnore }
+                    : {}),
             });
             outro('Dry run complete — no changes made');
             return;
@@ -243,6 +255,10 @@ export async function exportCommand(projectRoot, files, options) {
                 createdAt: new Date().toISOString(),
                 sourceEsrVersion: config.firefox.version,
                 filesAffected,
+                ...(options.tier !== undefined ? { tier: options.tier } : {}),
+                ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+                    ? { lintIgnore: options.lintIgnore }
+                    : {}),
             };
             const committedPlan = await commitPlacementExport({
                 patchesDir: paths.patches,
@@ -314,6 +330,10 @@ export async function exportCommand(projectRoot, files, options) {
             diff,
             filesAffected,
             sourceEsrVersion: config.firefox.version,
+            ...(options.tier !== undefined ? { tier: options.tier } : {}),
+            ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+                ? { lintIgnore: options.lintIgnore }
+                : {}),
         });
         for (const oldPatch of superseded) {
             info(`Superseded: ${oldPatch.filename}`);
@@ -348,11 +368,15 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('--force-unsafe', 'Bypass cross-patch lint refusal on projected placement')
         .option('--exclude-furnace', 'Exclude furnace-managed file paths from the export')
         .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap (default mode only; the resulting queue fails verify)')
+        .addOption(new Option('--tier <tier>', 'Force a tier override on the new patch (only "branding" recognised)').choices(['branding']))
+        .option('--lint-ignore <check-id>', 'Suppress a lint check on this patch (writes to PatchMetadata.lintIgnore; repeatable)', (value, prev) => [...prev, value], [])
         .action(withErrorHandling(async (paths, options) => {
-        const { category, ...rest } = options;
+        const { category, tier, lintIgnore, ...rest } = options;
         await exportCommand(getProjectRoot(), paths, {
             ...pickDefined(rest),
             ...(category !== undefined ? { category: category } : {}),
+            ...(tier !== undefined ? { tier: tier } : {}),
+            ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
         });
     }));
 }

package/dist/src/commands/furnace/remove.js

@@ -212,6 +212,64 @@ async function cleanupCustomTestFiles(name, projectRoot, journal) {
     }
     return { partialFailures };
 }
+/**
+ * Removes the MochiKit test scaffold a `furnace create --with-tests
+ * --test-style mochikit` produced for the component (matches the rename
+ * counterpart in `rename.ts`). The test file is `test_<name>.html` under
+ * `engine/toolkit/content/tests/widgets/` and the registration is the
+ * `["test_<name>.html"]` entry in the same directory's `chrome.toml`.
+ *
+ * 2026-04-25 eval Finding 13: the prior cleanup only handled the
+ * browser-chrome mochitest layout under `browser/base/content/test/
+ * <binary>/`, which left mochikit-style scaffolds and their toml entries
+ * orphaned after `furnace remove`. The post-rename name passed in here
+ * is the canonical one written to disk by deploy/rename, so the file
+ * basenames match without needing to re-derive from the old name.
+ *
+ * Best-effort: each step warns on failure rather than throwing so the
+ * rest of the remove transaction proceeds. The journal still snapshots
+ * touched files so the outer rollback can restore them on a later
+ * failure in the same operation.
+ */
+async function cleanupCustomMochikitTestFiles(name, projectRoot, journal) {
+    const partialFailures = [];
+    const paths = getProjectPaths(projectRoot);
+    const widgetsTestDir = join(paths.engine, 'toolkit/content/tests/widgets');
+    if (!(await pathExists(widgetsTestDir))) {
+        return { partialFailures };
+    }
+    const testFileName = `test_${name}.html`;
+    const testFilePath = join(widgetsTestDir, testFileName);
+    try {
+        if (await pathExists(testFilePath)) {
+            await snapshotFile(journal, testFilePath);
+            await unlink(testFilePath);
+            info(`Deleted mochikit test file: toolkit/content/tests/widgets/${testFileName}`);
+        }
+    }
+    catch (error) {
+        const msg = `Could not delete mochikit test file ${testFileName} — ${toError(error).message}. Remove it manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+    }
+    const chromeTomlPath = join(widgetsTestDir, 'chrome.toml');
+    try {
+        if (await pathExists(chromeTomlPath)) {
+            const toml = await readText(chromeTomlPath);
+            const headerLine = `["${testFileName}"]`;
+            if (toml.includes(headerLine)) {
+                await snapshotFile(journal, chromeTomlPath);
+                await writeText(chromeTomlPath, removeTomlSection(toml, testFileName));
+            }
+        }
+    }
+    catch (error) {
+        const msg = `Could not update widgets chrome.toml — ${toError(error).message}. Remove the test entry manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+    }
+    return { partialFailures };
+}
 /**
  * Removes generated xpcshell test scaffolds associated with a custom
  * component. 2026-04-24 eval Finding 5: `furnace remove` handled
@@ -433,6 +491,16 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
                 // versions.
                 const xpcshellResult = await cleanupCustomXpcshellTestFiles(name, projectRoot, journal);
                 testCleanupFailures.push(...xpcshellResult.partialFailures);
+                // 2026-04-25 eval Finding 13: mochikit-style scaffolds
+                // (`--test-style mochikit`) live under
+                // `engine/toolkit/content/tests/widgets/` with `chrome.toml`
+                // entries — neither the browser-chrome path nor the xpcshell
+                // path touches them. Without this pass, a `furnace create
+                // --with-tests --test-style mochikit` followed by `furnace
+                // remove` left the test file and its toml entry referencing a
+                // component that no longer exists.
+                const mochikitResult = await cleanupCustomMochikitTestFiles(name, projectRoot, journal);
+                testCleanupFailures.push(...mochikitResult.partialFailures);
             }
             // Remove entry from furnace.json
             if (type === 'stock') {