@hominis/fireforge 0.45.0 → 0.46.1

package/docs/configuration.md

@@ -2,34 +2,57 @@
 
 # Configuration
 
-`fireforge.json` at the project root is the project's configuration;
+`fireforge.json` at the project root holds the project's configuration, and
 `furnace.json` holds component configuration. This file covers the settings
-whose behaviour needs more than a schema line, plus the environment variables
+whose behavior needs more than a schema line, plus the environment variables
 FireForge reads.
 
-## `firefox` — the source pin
-
-`firefox.version` (with `firefox.product`, and optionally `firefox.sha256` and
-`firefox.candidate`) is the source pin `fireforge download` resolves an archive
-from. `fireforge source set` writes it.
-
-The pin lives in `fireforge.json` beside hand-maintained policy sections, which
-is worth knowing when reverting that file: `git checkout -- fireforge.json`
-after an accidental reformat also reverts an **uncommitted** pin, and the tree
-is then building a different version than the config claims.
-
-`fireforge doctor` reports the pin beside what the checkout actually is — the
+## `firefox`, the source pin
+
+`firefox.version`, together with `firefox.product` and optionally
+`firefox.sha256` and `firefox.candidate`, is the source pin that
+`fireforge download` resolves an archive from. `fireforge source set` writes
+it.
+
+The pin lives in `fireforge.json` next to hand-maintained policy sections,
+which is worth knowing when you revert that file. Running
+`git checkout -- fireforge.json` after an accidental reformat also reverts an
+uncommitted pin, and the tree is then building a different version than the
+config claims.
+
+### Archive integrity: `firefox.sha256` and `firefox.allowUnverifiedDownload`
+
+Every fresh download is checked against Mozilla's published `SHA256SUMS` for
+the release. A mismatch fails the download and discards the archive. The
+check also fails closed when the published digest cannot be obtained at all:
+a 404, a captive portal answering with an HTML page, a dropped connection, or
+a timeout. TLS alone is thin trust for the artifact that becomes the git
+baseline every patch is built on, and "the checksum host was unreachable" is
+exactly the condition someone positioned on the network can arrange.
+
+- `firefox.sha256` pins the digest. It takes precedence over the published
+  file and is the right answer for reproducible builds and offline mirrors:
+  obtain it out of band, and the download verifies with no network beyond the
+  archive itself.
+- `firefox.allowUnverifiedDownload: true` accepts a download when the
+  published digest is unavailable, with a loud warning. This disables the
+  integrity check for that case, so the archive is trusted on TLS alone. Use
+  it only for a mirror you already trust, and prefer pinning `sha256`
+  instead. A digest that is fetched and does not match is rejected either
+  way. The setting is ignored when `sha256` is set.
+
+`fireforge doctor` reports the pin beside what the checkout actually is (the
 engine's own `browser/config/version.txt` and the version the last download
-recorded — and warns when they disagree. It is a report, not a lock: a tree
-may legitimately be mid-migration. `product`, `sha256` and `candidate` have no
-recorded counterpart on disk, so the check does not claim to have verified
-them.
+recorded) and warns when they disagree. It is a report, not a lock, since a
+tree may legitimately be mid-migration. `product`, `sha256` and `candidate`
+have no recorded counterpart on disk, so the check does not claim to have
+verified them.
 
 ## External toolchains
 
 Projects with generated asset prerequisites can declare opt-in
-`externalToolchains`. `fireforge doctor` reports missing **required** tools as
-errors and missing **optional** tools as warnings.
+`externalToolchains`. `fireforge doctor` reports missing required tools as
+errors and missing optional tools as warnings.
 
 Seasonal branding on macOS, for example, can declare Apple's Icon Composer
 tool at
@@ -38,27 +61,28 @@ plus `actool` via `xcrun`, `sips`, and `iconutil`.
 
 ## `patchLint`
 
-Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals
-shim that tracks upstream WebIDL additions per release.
+Per-patch lint type-checks plain Firefox JS against a built-in
+Firefox-globals shim that tracks upstream WebIDL additions per release.
 
-- `patchLint.checkJsExtraShim` adds members to the structured shim globals via
-  TypeScript interface merging, e.g.
+- `patchLint.checkJsExtraShim` adds members to the structured shim globals
+  via TypeScript interface merging, for example
   `interface ChromeUtilsShim { newApi(): any }`.
 - `patchLint.checkJsTestFiles: true` extends the pass to patch-owned test
-  `.js` files (`browser_*` / `test_*` / `xpcshell_*` and `/test/` paths). Each
-  is checked as its own small script-scope program against a loose built-in
-  harness shim.
+  `.js` files (`browser_*`, `test_*`, `xpcshell_*`, and `/test/` paths). Each
+  one is checked as its own small script-scope program against a loose
+  built-in harness shim.
 - `patchLint.checkJsTestShim` points at a project `.d.ts` whose typed
-  declarations (e.g. a real `TestUtils` interface) override the loose
-  baseline, so calls to nonexistent harness members fail at export time.
-- `patchLint.prettier` (`'off'` | `'warning'` | `'error'`, default `'off'`)
+  declarations (a real `TestUtils` interface, say) override the loose
+  baseline, so calls to harness members that do not exist fail at export
+  time.
+- `patchLint.prettier` (`'off'`, `'warning'` or `'error'`, default `'off'`)
   runs the project's configured Prettier over patch-owned `.sys.mjs`
   modules. It runs from inside `engine/`, so `engine/.prettierrc*` and
-  `engine/.prettierignore` decide — the same command run from the repo root
-  can report a false pass when the root `.prettierignore` excludes
+  `engine/.prettierignore` decide the outcome. The same command run from the
+  repo root can report a false pass when the root `.prettierignore` excludes
   `engine/`. Prettier is resolved from `engine/node_modules`, then the
-  project's, then `npx --no-install`. **Left `'off'`, formatting is out of
-  scope for the per-patch tier**; no other tier checks `.sys.mjs`
+  project's, then `npx --no-install`. Left at `'off'`, formatting is out of
+  scope for the per-patch tier, and no other tier checks `.sys.mjs`
   formatting either.
 - `patchLint.fileSizeThresholds` tunes the `file-too-large` line counts per
   file class:
@@ -75,11 +99,11 @@ shim that tracks upstream WebIDL additions per release.
   ```
 
   Every field is optional and merges over the defaults (general
-  `500/750/900`, test `1200/1400/1600`). The merged triple must satisfy
-  `notice <= warning <= error`, which is validated at config load. Note that
-  under the recommended gate posture `--max-warnings 0` the `warning` band is
-  a hard failure, not a soft limit — which is what these thresholds exist to
-  let you move.
+  `500/750/900`, test `1200/1400/1600`). The merged triple has to satisfy
+  `notice <= warning <= error`, which is validated at config load. Under
+  the recommended gate posture `--max-warnings 0`, the `warning` band
+  is a hard failure rather than a soft limit, which is what these thresholds
+  exist to let you move.
 
 ## `patchPolicy`
 
@@ -91,61 +115,131 @@ gaps does not move a patch out of the band its category owns.
 `test.canaryPath` and `test.canaryTimeoutSeconds` supply the defaults for
 `fireforge test --canary`. See [`testing.md`](testing.md).
 
+## `buildAudit`
+
+The post-build packaging audit is warn-only. Most of what it would otherwise
+report as "missing packaged artifact" is classified away from the structure
+of the tree itself: an unselected `--with-branding` tree read from the
+generated `engine/mozconfig`, a directory reached only through a
+platform-gated `DIRS +=` in an ancestor `moz.build`, a Storybook
+`*.stories.mjs`. One case cannot be derived from the tree: a source that is
+deliberately never packaged, such as a type-only mirror whose header says it
+is never loaded. Declare those:
+
+```json
+{
+  "buildAudit": {
+    "unpackaged": [
+      {
+        "path": "browser/base/content/hominis-tile-host-types.js",
+        "reason": "Type-only mirror of the tile host, never loaded, and no jar.mn entry by design."
+      }
+    ]
+  }
+}
+```
+
+- `path` is engine-relative. A `*` may glob within one path segment. `**` is
+  refused, because a subtree carve-out is how a reviewed exception quietly
+  becomes a blanket one.
+- `reason` is required and must be non-empty. This is the one audit class
+  FireForge cannot verify against the tree, so the declaration is the
+  evidence. By the time someone reads it, an unexplained carve-out is
+  indistinguishable from a mistake.
+- Admitted paths are listed in the audit output, never silenced. The notice
+  reads `admitted as unpackaged by buildAudit.unpackaged "<path>"` followed
+  by the declared reason.
+- A declared path that does resolve to a packaged artifact is reported as a
+  stale carve-out rather than suppressed, because the declaration asserts a
+  fact about the tree that is no longer true.
+- A declaration matching nothing that changed in a given run says nothing.
+  Unlike `--expect-unmanaged`, whose unmet entries are reported because it is
+  a per-invocation flag list, this is a standing list checked only against
+  the files that happened to change, so "not met" is the normal case.
+
+The `Packaged:` summary line names each non-zero skip class with its count,
+so a run that dismissed four unselected-branding files reads differently from
+one that dismissed four unregistered sources.
+
 ## Design tokens
 
-Tokens are managed with `fireforge token add`.
+Tokens are managed with `fireforge token add`. `fireforge token list` and
+`fireforge token show` report what is already there.
 
 - `--create-category` declares a new category banner and inserts the token in
-  one step. It is incompatible with `--variant`; author the category with the
-  base token first, then add each variant.
+  one step. It cannot be combined with `--variant`: author the category with
+  the base token first, then add each variant.
 - `--category` is required for a base declaration and optional under
   `--variant`, where the declaration is routed into a `:root<selector>` block
   and never into a category section. It is still validated when supplied.
 - `--variant` takes the same selector grammar the block matcher understands:
-  one attribute fragment (`[data-private]`, `[data-skin=precision]`), a run of
-  them (`[data-skin=precision][data-theme=dark]`), and an optional pseudo-class
-  tail (`[data-skin=precision]:not([data-private])`). Names and values must be
-  identifier-safe, and `=value` is normalized to `="value"`. A variant naming a
-  qualifier matches only a block carrying that qualifier; one without a
-  qualifier still matches a qualified block, and the write says so.
+  one attribute fragment (`[data-private]`, `[data-skin=precision]`), a run
+  of them (`[data-skin=precision][data-theme=dark]`), and an optional
+  pseudo-class tail (`[data-skin=precision]:not([data-private])`). Names and
+  values must be identifier-safe, and `=value` is normalized to `="value"`. A
+  variant naming a qualifier matches only a block carrying that qualifier.
+  One without a qualifier still matches a qualified block, and the write says
+  so.
 - `--mode override` mirrors into both `:root[data-theme="dark"]` and
   `:root[data-theme="light"]`. A qualified block such as
   `:root[data-theme="light"]:not([data-private])` is matched and written
-  through, with a warning naming the selector — the qualifier is
-  semantically load-bearing, but silently skipping half the mirror is the
-  worse failure.
+  through, with a warning naming the selector. The qualifier carries meaning,
+  but silently skipping half the mirror is the worse failure.
 - A token already present in the target block is reported with its location
-  (`already exists in :root[…] (line N), unchanged`) rather than a bare
+  (`already exists in :root[…] (line N), unchanged`) rather than as a bare
   no-op.
 
+### Reading the token file
+
+`token add --category` refuses a category that the tokens CSS does not
+declare, so `token list` exists to name the categories without you
+hand-parsing a `= Category =` banner out of the file.
+
+- `fireforge token list [--category <name>] [--json]` reports each category
+  banner with the tokens declared under it, in file order. Declarations above
+  the first banner are reported under `(no category)` rather than dropped,
+  and a banner with no tokens is still listed, since `token add` accepts it.
+  An unknown `--category` is refused by naming the ones that exist, because a
+  filter that printed nothing would read as "this category is empty".
+- `fireforge token show <token-name> [--json]` reports the owning category
+  and the value the token takes in every block that declares it: the base
+  `:root`, the dark `@media` mirror, and each `:root[variant]`, with the line
+  of each. The leading `--` is optional, and if you include it, pass the `--`
+  separator first (`fireforge token show -- --my-token`).
+
+Only the base `:root` block owns a token, so `token list` reports it once.
+The dark and variant blocks mirror it and appear in `token show`.
+
 ## Smoke runs
 
 For unattended smoke checks, `fireforge run --smoke-exit <s> --headless`
 launches the browser headless. A headed smoke window on a shared desktop
-absorbs live input, which contaminates the console capture — headed non-CI
-launches print a warning saying so. Exit codes 12 and 13 separate a console
-regression from a launch failure; see [`exit-codes.md`](exit-codes.md).
+absorbs live input, which contaminates the console capture, so headed
+non-CI launches print a warning saying so. Exit codes 12 and 13 separate a
+console regression from a launch failure. See
+[`exit-codes.md`](exit-codes.md).
 
 ## Lock waits
 
-Every FireForge command that mutates the engine takes the engine-session lock,
-and some take a second subsystem lock as well. Contention fails fast after
-about a second by default.
+Every FireForge command that mutates the engine takes the engine-session
+lock, and some take a second subsystem lock as well. Contention fails fast
+after about a second by default.
 
-`--wait-lock [seconds]` (bare flag = 60, valid 1–3600) replaces that with a
-bounded wait, and the budget covers **every** lock the command takes — for
-`furnace apply`/`deploy`/`sync` that means the furnace lock as well as the
-engine-session lock. While waiting, a progress line roughly every 5 seconds
-identifies the holder by PID, command and start time.
+`--wait-lock [seconds]` (bare flag means 60, valid range 1 to 3600) replaces
+that with a bounded wait, and the budget covers every lock the command takes.
+For `furnace apply`, `deploy` and `sync` that means the furnace lock as well
+as the engine-session lock. While waiting, a progress line roughly every 5
+seconds identifies the holder by PID, command and start time.
 
 Commands that take no lock accept `--wait-lock` and ignore it, so a scripted
-sequence can blanket-append the flag without a usage error killing the run.
+sequence can append the flag everywhere without a usage error killing the
+run.
 
 `FIREFORGE_WAIT_LOCK=<seconds>` applies the same budget to every command in a
 session, using the same bounds as the flag. It is the only way to give a
 budget to the furnace mutators that declare no flag (`create`, `remove`,
-`rename`, `refresh`, `scan`, `override`, `chrome-doc`, …). An explicit
-`--wait-lock` always wins.
+`rename`, `refresh`, `scan`, `override`, `chrome-doc`, and the rest). An
+explicit `--wait-lock` always wins.
 
 `fireforge status --lock` reports the current holder and queue depth.
 
@@ -153,11 +247,11 @@ budget to the furnace mutators that declare no flag (`create`, `remove`,
 
 | Variable                             | Effect                                                                                                                                  |
 | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `FIREFORGE_WAIT_LOCK`                | Session-wide lock wait budget in seconds (1–3600). See above.                                                                           |
+| `FIREFORGE_WAIT_LOCK`                | Session-wide lock wait budget in seconds (1 to 3600). See above.                                                                        |
 | `FIREFORGE_MAX_UNTRACKED_FILES`      | Per-directory cap when expanding collapsed untracked directories in `status` (default 5000). A non-positive value warns and is ignored. |
 | `FIREFORGE_GIT_ADD_TIMEOUT_MS`       | Timeout for the monolithic `git add -A` baseline pass (default 10 min). For slow or loaded filesystems.                                 |
 | `FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS` | Timeout for the chunked `git add -- <dir>` fallback (default 30 min). Paired with the above.                                            |
 
-`CLAUDECODE` is read by mozbuild, not by FireForge, and `fireforge test
---full-output` unsets it for test dispatches only — see
+`CLAUDECODE` is read by mozbuild, not by FireForge. `fireforge test
+--full-output` unsets it for test dispatches only. See
 [`testing.md`](testing.md#output-verbosity).

package/docs/exit-codes.md

@@ -2,64 +2,81 @@
 
 # Exit codes (internal)
 
-The exit code is the machine-readable half of the CLI's contract: a script
-branches on it, and CI decides whether to retry or escalate. The values live
-in `src/errors/codes.ts`; this file is the operator-facing statement of what
-they mean and which class produces each.
+The exit code is the machine-readable half of the CLI's contract. A script
+branches on it, and CI uses it to decide whether to retry or escalate. The
+values live in `src/errors/codes.ts`. This file says what they mean and
+which error class produces each one.
 
-| Code | Name                   | Meaning                                                                                                                  | Produced by                                                    |
-| ---: | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
-|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined — declining is a successful run that chose not to proceed. | —                                                              |
-|    1 | `GENERAL_ERROR`        | Unspecified failure the operator must act on.                                                                            | `GeneralError`, `ParserFallbackError`                          |
-|    2 | `CONFIG_ERROR`         | `fireforge.json` missing or invalid.                                                                                     | `ConfigError` and subclasses                                   |
-|    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                            | `DownloadError` and subclasses                                 |
-|    4 | `GIT_ERROR`            | A git operation failed.                                                                                                  | `GitError` and subclasses                                      |
-|    5 | `BUILD_ERROR`          | `mach build` failed, or a test suite went red.                                                                           | `BuildError` and subclasses, `TestFailureError`                |
-|    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                        | `PatchError`                                                   |
-|    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                       | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError` |
-|    8 | `INVALID_ARGUMENT`     | The flags were wrong. Usage problem, not an environment one.                                                             | `InvalidArgumentError`                                         |
-|    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                    | `FurnaceError`                                                 |
-|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                              | `ResolutionError`                                              |
-|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. **A bug in FireForge**, not something the operator can fix.                          | `InternalInvariantError`                                       |
-|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw unallowed console errors in the smoke window.                                                     | `SmokeRunError`                                                |
-|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw a non-clean browser exit before the window elapsed.                                               | `SmokeRunError`                                                |
-|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away: `engine/` moved while the harness ran. **Not red** — re-run it.                    | `InconclusiveVerdictError`                                     |
-|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it, with a larger `--wait-lock`.                                 | `LockContentionError`                                          |
-|  130 | `USER_CANCELLED`       | The operator INTERRUPTED a prompt (Esc / Ctrl+C). 128 + SIGINT.                                                          | `CancellationError`                                            |
+| Code | Name                   | Meaning                                                                                                                 | Produced by                                                                                       |
+| ---: | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined: declining is a successful run that chose not to proceed. | (none)                                                                                            |
+|    1 | `GENERAL_ERROR`        | Unspecified failure the operator has to act on.                                                                         | `GeneralError` (and `PreflightRefusalError`), `ParserFallbackError`, `ExecTimeoutError`           |
+|    2 | `CONFIG_ERROR`         | `fireforge.json` missing or invalid.                                                                                    | `ConfigError` and subclasses                                                                      |
+|    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                           | `DownloadError` and subclasses                                                                    |
+|    4 | `GIT_ERROR`            | A git operation failed.                                                                                                 | `GitError` and subclasses, except `GitNotFoundError`                                              |
+|    5 | `BUILD_ERROR`          | `mach build` failed, or a test suite went red.                                                                          | `BuildError` and subclasses, `TestFailureError`                                                   |
+|    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                       | `PatchError`, `PatchManifestCorruptError`, `RebaseError` and subclasses                           |
+|    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                      | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError`                                    |
+|    8 | `INVALID_ARGUMENT`     | The flags were wrong. A usage problem, not an environment one.                                                          | `InvalidArgumentError`, plus commander usage errors (unknown command or option, missing argument) |
+|    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                   | `FurnaceError`                                                                                    |
+|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                             | `ResolutionError`                                                                                 |
+|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. This is a bug in FireForge, not something the operator can fix.                     | `InternalInvariantError`                                                                          |
+|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw console errors that were not allowed in the smoke window.                                        | `SmokeRunError`                                                                                   |
+|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw the browser exit uncleanly before the window elapsed.                                            | `SmokeRunError`                                                                                   |
+|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away because `engine/` moved while the harness ran. This is not red. Re-run it.         | `InconclusiveVerdictError`                                                                        |
+|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it with a larger `--wait-lock`.                                 | `LockContentionError`                                                                             |
+|  130 | `USER_CANCELLED`       | The operator interrupted a prompt (Esc or Ctrl+C). 128 + SIGINT.                                                        | `CancellationError`                                                                               |
+
+Usage errors that commander detects itself (an unknown command, an unknown
+or malformed option, a missing required argument) never reach a command
+action. Before 0.46.0 commander terminated the process with its own exit 1
+and printed no refusal envelope under `--json`. `createProgram` now installs
+commander's `exitOverride()`, and the entry point maps the resulting
+`CommanderError` to `INVALID_ARGUMENT` (8) with the standard envelope on
+stdout. `--help` and `--version` take the same path and still exit 0, and so
+does a command group invoked without a subcommand (`fireforge`,
+`fireforge tree`): commander prints the group's help and the entry point
+treats that as informational rather than as a wrong flag. That matches the
+exit 0 that `patch`, `token` and `furnace` give through their own help
+action.
 
 ## The three distinctions that matter for CI
 
-**Retry vs escalate.** `GENERAL_ERROR` usually means the operator must change
-something and a retry may help. `INTERNAL_ERROR` means nothing they could
-change would have helped — escalate it, do not retry.
+**Retry or escalate.** `GENERAL_ERROR` usually means the operator has to
+change something, and a retry may then help. `INTERNAL_ERROR` means nothing
+they could change would have helped. Escalate it, do not retry.
+
+**Red, never ran, or thrown away.** These are three different facts, and
+before 0.44.0 two of them shared exit 1.
+
+- `BUILD_ERROR` (5) is a suite that failed. Since 0.45.0 it is thrown as
+  `TestFailureError`, which keeps the code but carries test remedies rather
+  than build ones (`--json` reports it as `test-failure`).
+- `LOCK_TIMEOUT` (15) is a run that never started, because another FireForge
+  process held the lock for the whole budget. Nothing about the request was
+  wrong, so re-queue it.
+- `INCONCLUSIVE` (14) is a suite whose result was discarded because
+  `engine/` moved underneath it. The code may be perfectly green, so
+  reporting it as red is wrong.
 
-**Red vs never-ran vs thrown-away.** These are three different facts and,
-before 0.44.0, two of them shared exit 1. `BUILD_ERROR` (5) is a suite that
-FAILED — thrown as `TestFailureError` since 0.45.0, which keeps the code but
-carries test remedies rather than build ones (`--json` reports it as
-`test-failure`). `LOCK_TIMEOUT` (15) is a run that never started, because another
-FireForge process held the lock for the whole budget — nothing about the
-request was wrong, so re-queue it. `INCONCLUSIVE` (14) is a suite whose
-result was DISCARDED, because `engine/` moved underneath it — the code may
-be perfectly green, and reporting it as red is wrong. A summary line reading
-`FAIL — exit 1` beside `FAIL — exit 5` invited treating opposites as the same
-kind of fact; the codes now separate them mechanically. The
-`FIREFORGE-VERDICT:` line's `reason=` key carries the same distinction for
-humans.
+A summary line reading `FAIL - exit 1` beside `FAIL - exit 5` invited
+treating opposite facts as the same kind of thing. The codes now separate
+them. The `FIREFORGE-VERDICT:` line's `reason=` key carries the same
+distinction for humans.
 
-Note that `LockContentionError` backs every lock in FireForge — engine
-session, patch directory, build, furnace — so all four now exit 15. That is
-deliberate: the fact is the same whichever lock was contended.
+`LockContentionError` backs every lock in FireForge (engine session, patch
+directory, build, furnace), so all four exit 15. That is intentional: the
+fact is the same whichever lock was contended.
 
-**Interrupted vs declined.** Before 0.44.0 both a Ctrl+C and a deliberate
-"no" at a confirmation returned the same value and exited 0, so a script
-could not tell them apart. They are now distinct: an interrupt raises
-`CancellationError` and exits **130**; a declined confirmation returns
-normally and exits **0**, because the run did what it was asked and the
-answer was no.
+**Interrupted or declined.** Before 0.44.0 a Ctrl+C and a deliberate "no" at
+a confirmation both returned the same value and exited 0, so a script could
+not tell them apart. They are now distinct: an interrupt raises
+`CancellationError` and exits 130, and a declined confirmation returns
+normally and exits 0, because the run did what it was asked and the answer
+was no.
 
 ## Adding a code
 
 New codes go in `src/errors/codes.ts` with a comment saying what a consumer
-should DO differently on seeing it — if the answer is "nothing different from
+should do differently on seeing it. If the answer is "nothing different from
 an existing code", it does not need one. Add a row here in the same change.

package/docs/furnace.md

@@ -2,10 +2,10 @@
 
 # Furnace components
 
-Furnace is FireForge's answer to UI components. It tracks stock widgets,
+Furnace is how FireForge handles UI components. It tracks stock widgets,
 creates new fork-owned widgets, and overrides existing ones. The files still
-land inside the Firefox source directory and end up as part of the regular
-patches to export.
+land inside the Firefox source directory and end up in the regular patches
+you export.
 
 ```bash
 npx fireforge furnace scan
@@ -20,38 +20,39 @@ npx fireforge furnace preview
 
 ## Shared CSS fragments
 
-Cross-widget CSS can be single-sourced. Place the fragment in
-`components/shared/` and reference it from a widget stylesheet with a
+CSS used by more than one widget can live in a single file. Put the fragment
+in `components/shared/` and reference it from a widget stylesheet with a
 comment:
 
 ```css
 /* @fireforge-include base-button.css */
 ```
 
-`deploy` expands it into the deployed copy only, so editing the fragment
-surfaces as component drift until the next deploy.
+`deploy` expands the fragment into the deployed copy only, so editing the
+fragment shows up as component drift until the next deploy.
 
 ## Typed cross-module imports
 
 For multi-file components, set `furnace.json#typecheckJsconfig` to a
 consumer-owned jsconfig. `deploy` then maintains `compilerOptions.paths`
-entries mapping each deployed
+entries that map each deployed
 `chrome://global/content/elements/<file>.mjs` URL to its workspace source.
 
-Entries are recognized as Furnace-managed by containment in the components
-workspace, so a hand-written entry is preserved and a managed entry whose
-helper was deleted is pruned.
+An entry counts as Furnace-managed if it is contained in the components
+workspace. A hand-written entry is therefore preserved, and a managed entry
+whose helper was deleted is pruned.
 
 ## Safety
 
-Every furnace mutation runs through `runFurnaceMutation`: a per-root lock, a
-rollback journal restored on both a signal and a thrown error, and a
-`pendingRepair` marker that blocks further mutations when a rollback was
-incomplete — cleared with `fireforge doctor --repair-furnace`. The full
-contract, including which commands take which locks, is in
+Every furnace mutation runs through `runFurnaceMutation`, which gives it a
+per-root lock, a rollback journal restored on both a signal and a thrown
+error, and a `pendingRepair` marker that blocks further mutations when a
+rollback was incomplete. Clear the marker with
+`fireforge doctor --repair-furnace`. The full contract, including which
+commands take which locks, is in
 [`lifecycle-invariants.md`](lifecycle-invariants.md).
 
-`apply`, `deploy` and `sync` accept `--wait-lock [seconds]`, whose budget
-covers **both** locks they take. The twelve mutators without the flag pick up
-a session budget from `FIREFORGE_WAIT_LOCK`; see
+`apply`, `deploy` and `sync` accept `--wait-lock [seconds]`, and that budget
+covers both locks they take. The twelve mutators without the flag pick up a
+session budget from `FIREFORGE_WAIT_LOCK`. See
 [`configuration.md`](configuration.md#lock-waits).