@hominis/fireforge 0.54.0 → 0.60.0

package/docs/exit-codes.md

@@ -1,96 +1,78 @@
 <!-- SPDX-License-Identifier: EUPL-1.2 -->
 
-# Exit codes (internal)
-
-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.                       | (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 (including a patch `rebase --dry-run` predicts will reject), 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, or an allowlisted shape fired past its `# max-hits` ceiling. | `SmokeRunError`                                                                                   |
-|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw the browser exit uncleanly before the window elapsed, or exit cleanly before it without any console output.            | `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. `createProgram` 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 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, each
-with its own code.
-
-- `BUILD_ERROR` (5) is a suite that failed. 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.
-
-Separate codes keep a summary line from showing opposite facts as the same
-kind of failure, such as `FAIL - exit 1` beside `FAIL - exit 5`. The `FIREFORGE-VERDICT:` line's `reason=` key carries the same
-distinction for humans.
-
-`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 or declined.** A Ctrl+C and a deliberate "no" at a
-confirmation are distinct, so a script can tell them apart: 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.
-
-## `fireforge check`
-
-The composed gate maps its verdict onto the existing codes rather than
-adding one:
-
-| Exit | When                                                                                                                                                                                                |
-| ---: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-|    0 | Every step passed or was skipped.                                                                                                                                                                   |
-|    1 | At least one step failed (`reason=step-failures`). Each step's own exit code is in the `--json` document's `steps[].exitCode`. Also a `--patches` name that matches no patch, before any step runs. |
-|   15 | Every failed step exited 15 (`reason=lock-timeout`): nothing was judged red, the steps never got their locks. Re-queue it.                                                                          |
-|    2 | `fireforge.json` is invalid, including a `check.status` policy `status` would refuse. Raised before any step runs.                                                                                  |
-|    8 | An unknown `--only`/`--skip` step, or a bad `--jobs`. Raised before any step runs.                                                                                                                  |
-
-`furnace validate` exits 9 (`FURNACE_ERROR`) both for errors and for
-warnings past `--max-warnings`, so a gate that wants the distinction reads
-`summary.errors` from its `--json` document.
-
-## 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
-an existing code", it does not need one. Add a row here in the same change.
+# Exit codes
+
+A script branches on the exit code, and CI uses it to decide whether to retry or escalate. Every failure also has a stable string `code` (`lock-timeout`, `gate-dirty-tree`). It is printed on stderr with the message, followed by the hint when the failure has one:
+
+```
+error[gate-dirty-tree]: <message>
+hint: <what to do next>
+```
+
+The `--json` failure document `{ schemaVersion, error, code, hint }` carries the same three ([machine-output.md](machine-output.md)). Branch on the exit code for the category and on `code` for the exact cause.
+
+| Code | Name                   | Meaning                                                                                                                  |
+| ---: | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+|    0 | `SUCCESS`              | Completed. A prompt answered "no" also exits 0: the run did what it was asked.                                           |
+|    1 | `GENERAL_ERROR`        | A failure you act on: a red `lint`, `typecheck`, `check` or `doctor`, a refusal before any work started.                 |
+|    2 | `CONFIG_ERROR`         | `fireforge.json` or a state document is missing or invalid, including an unknown key.                                    |
+|    3 | `DOWNLOAD_ERROR`       | The Firefox source could not be downloaded or extracted, or this host has not downloaded the pin yet.                    |
+|    4 | `GIT_ERROR`            | A git operation failed, or a ref could not be moved the way the command requires.                                        |
+|    5 | `BUILD_ERROR`          | `mach` failed: a build that did not compile, a test run that went red.                                                   |
+|    6 | `PATCH_ERROR`          | A patch did not apply, or the patch queue is inconsistent or could not be changed.                                       |
+|    7 | `MISSING_DEPENDENCY`   | A required tool (git, python3, watchman for `watch`) is not installed or not usable.                                     |
+|    8 | `INVALID_ARGUMENT`     | The command line is wrong: an unknown option, a bad value, a combination that is refused.                                |
+|    9 | `FURNACE_ERROR`        | Component management failed: validation errors, generated typing files out of date.                                      |
+|   10 | `RESOLUTION_ERROR`     | Conflicts are left for a person to resolve, such as a rebase that ended with conflict markers.                           |
+|   11 | `INTERNAL_ERROR`       | An internal invariant did not hold: a bug in FireForge, never yours to fix. The message asks for a report.               |
+|   12 | `SMOKE_EXIT_FAILURE`   | A smoke start (`run --smoke-exit`) saw console errors that no allowlist entry accepts.                                   |
+|   13 | `SMOKE_LAUNCH_FAILURE` | A smoke start's browser exited before its window elapsed.                                                                |
+|   14 | `INCONCLUSIVE`         | A result exists but cannot be trusted, because what it judged changed underneath it. Run again; do not report it as red. |
+|   15 | `LOCK_TIMEOUT`         | A wait for a lock or a workspace expired, so the work never started. Run again, or pass `--wait-lock <seconds>`.         |
+|  130 | `USER_CANCELLED`       | Interrupted with Ctrl+C (SIGINT), at a prompt or while running. Changes in progress were rolled back.                    |
+|  143 | `TERMINATED`           | Asked to stop with SIGTERM. Changes in progress were rolled back.                                                        |
+
+A second interrupt while the first is still being handled ends the process at once with the same code, without the rollback.
+
+## The commands that judge
+
+### `test`
+
+| Result                                                                                         | Exit |
+| ---------------------------------------------------------------------------------------------- | ---: |
+| Every planned test file ran and passed; a negative control was caught                          |    0 |
+| Refused before the harness started: a stale build without `--build`, a path that is not a test |    1 |
+| Red: failures, a crash, a hang, a file that never started or finished                          |    5 |
+| A negative control failed: `control-missed`, `control-wrong-red`, `control-baseline-red`       |    5 |
+| The engine changed while the harness ran (`test-inconclusive`, `control-inconclusive`)         |   14 |
+| The workspace, the display or a build slot did not come free                                   |   15 |
+
+### `check`
+
+| Result                                                                                        | Exit |
+| --------------------------------------------------------------------------------------------- | ---: |
+| Every step that ran passed                                                                    |    0 |
+| A step failed, or a step had nothing to run and `check.failOnSkipped` is set (`check-failed`) |    1 |
+| An unknown step name for `--only` or `--skip`                                                 |    8 |
+| The workspace did not come free; no step's result is reported                                 |   15 |
+
+### `gate`
+
+| Result                                                                                                                                                       | Exit |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---: |
+| `verified`: everything passed and `refs/fireforge/verified` is at the commit                                                                                 |    0 |
+| `pending`: everything passed and acceptances are outstanding; the ref has not moved                                                                          |    0 |
+| `feedback`: the entries named with `--lane` passed; nothing was recorded                                                                                     |    0 |
+| The working tree differs from HEAD (`gate-dirty-tree`); only the check is red (`gate-check-failed`)                                                          |    1 |
+| No commit to judge (`gate-no-commit`); the verified commit is not an ancestor (`gate-not-fast-forward`); the ref moved while the gate ran (`gate-ref-moved`) |    4 |
+| The build, a lane, a stress run, a control or a smoke start is red (`gate-failed`)                                                                           |    5 |
+| The working tree or HEAD changed while the gate ran (`gate-tree-moved`)                                                                                      |   14 |
+| The workspace did not come free                                                                                                                              |   15 |
+
+A gate that exits 0 has not necessarily moved the ref: read `result=` on the verdict line, `outcome` in the JSON document, or the ref itself. A red check with green lanes exits 1 because nothing `mach` ran failed; any red build or declared entry exits 5 whatever the check said.
+
+`gate accept` exits 1 when a lane it stands on has no recorded pass for the commit (`gate-evidence-missing`) or the tree is dirty, and 8 for an undeclared ID.
+
+### `doctor`
+
+Exits 0 when no check failed (warnings do not count) and 1 otherwise (`doctor-unhealthy`). A missing tool of `externalToolchains` is a failed check when it is `required` and a warning otherwise.

package/docs/furnace.md

@@ -2,211 +2,143 @@
 
 # Furnace components
 
-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 in the regular patches
-you export.
-
-```bash
-npx fireforge furnace scan
-npx fireforge furnace override moz-button -t css-only
-npx fireforge furnace create moz-my-widget
-npx fireforge furnace deploy
+Furnace manages the fork's UI components: custom elements the fork adds, and overrides of Firefox's stock widgets. Their sources live in the project under `components/`, described by `furnace.json`; Furnace deploys them into the engine a command builds in, validates them, scaffolds, renames and removes them, and generates the typing files that make them typed for the code that uses them. It works the same in both modes.
+
+```sh
+npx fireforge furnace create moz-my-widget -d "A widget" --localized --tests browser-chrome
+npx fireforge furnace override moz-button --css-only -d "Brand colours"
 npx fireforge furnace status
-npx fireforge furnace preview
+npx fireforge furnace validate
+npx fireforge build --ui
+```
+
+## Layout
+
+```
+furnace.json
+components/
+  custom/moz-my-widget/      moz-my-widget.mjs, moz-my-widget.css, moz-my-widget.ftl, moz-my-widget-*.mjs
+  overrides/moz-button/      the copied stock files you edit
+  shared/                    CSS fragments several components include
 ```
 
-`fireforge furnace --help` lists every subcommand.
+`furnace.json` is created with `"componentPrefix": "moz-"` the first time a command writes it. Its full schema is in [configuration.md](configuration.md#furnacejson).
+
+## Creating and overriding
+
+`furnace create <tag>` writes a custom component: `<tag>.mjs` (a class extending `MozLitElement` that calls `customElements.define`), `<tag>.css`, and with `--localized` its own `<tag>.ftl`, plus its `furnace.json` entry. The tag must start with `componentPrefix`.
+
+- `-d, --description <text>`: what the component is.
+- `--localized`: give it its own Fluent file. `--shared-ftl <path>` shares an existing feature Fluent file instead.
+- `--register` (the default) lists the element in `toolkit/content/customElements.js` so it is defined lazily; `--no-register` leaves it out.
+- `--compose <tag>`: a component it renders in its template.
+- `--tests browser-chrome|mochikit|xpcshell`: scaffold a test in that harness and register it in its manifest.
+- `--dry-run`: show what would change.
+
+`furnace override <name>` copies a stock component from the engine (`toolkit/content/widgets/<name>`, or `--from <dir>`) into `components/overrides/<name>/` and records the Firefox version it was taken from. `--css-only` copies and deploys only its stylesheets.
+
+`furnace rename <from> <to>` renames a component, its files, its tests and every reference to it. `furnace remove <name>` removes a component, its tests and its `furnace.json` entry. Each of these is one transaction over `components/`, `furnace.json`, the typing files and the component's tests. None of them touches a workspace; the next deployment adds and removes what changed.
+
+In source mode the engine files a component brings along (its tests and their manifests) are written under `src/`, and a first edit of an upstream manifest declares its override as a registration.
+
+## Deploying
+
+`build`, `test`, `run`, `package`, `watch` and `gate` deploy the components into their workspace before they start, so you rarely deploy by hand. `furnace apply` does it on its own:
+
+```sh
+npx fireforge furnace apply --dry-run
+npx fireforge furnace apply
+```
+
+Deployment compares what the components want the engine to hold with what it holds, and writes the difference in one transaction:
+
+- each custom component's files into `toolkit/content/widgets/<tag>/` (or its `targetPath`), and its Fluent file into `ftlBasePath` (default `toolkit/locales/en-US/toolkit/global`);
+- each override's files over the stock files;
+- one `toolkit/content/jar.mn` line per module and stylesheet of a custom component, packaged as `chrome://global/content/elements/<file>`;
+- one `customElements.js` entry per registered element, in the list that matches how it loads (ES modules in the list imported on `DOMContentLoaded`).
+
+A deployment record in the workspace says what each component deployed, so a deployed file the component does not have, or a component `furnace.json` does not list, is taken away, and an override's file goes back to the upstream bytes. Everything else is decided from the bytes on disk: an unchanged component costs a read and a hash, and a reset engine or a lost record is repaired by the next deployment.
+
+`furnace status` lists the components and whether the engine holds them as the project has them. `furnace diff [name]` shows how a custom component differs from its deployed copy, or an override from the stock files.
 
 ## Shared CSS fragments
 
-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:
+Shadow DOM gives every widget stylesheet its own copy of shared rules. Put them in `components/shared/` and include them from a component stylesheet with a directive on its own line:
 
 ```css
 /* @fireforge-include base-button.css */
 ```
 
-`deploy` expands the fragment into the deployed copy only, so editing the
-fragment shows up as component drift until the next deploy. `furnace diff`
-compares the deployed copy against this composed form (and says so in the
-`+++` header), so a freshly deployed includer shows no difference.
-
-## Deploying and applying
-
-`furnace deploy` takes any number of names and deploys them under one lock
-hold (`fireforge furnace deploy moz-a moz-b moz-c`), so a batch of widgets
-waits for the engine lock once rather than once per widget. Each name is its
-own atomic unit: it is applied and its state persisted before the next starts.
-An unknown name refuses the whole invocation before anything is written, and
-a stock name is warned about and skipped. With no name, everything deploys.
-
-Deploy registers every `.mjs` and `.css` file in a custom component directory
-in `toolkit/content/jar.mn`, including extra modules beside the main one. Add
-the file to the directory and deploy instead of writing the jar line by hand.
-A line that already registers the file anywhere in the jar (same target, or
-same `(widgets/<tag>/<file>)` source) is kept and never duplicated, so mach
-does not fail with "Item already in manifest". Removing a file from the
-directory drops only its line, and `furnace rename` rewrites the widget's
-lines where they stand, so the rest of the block keeps its order and the
-owning patch carries no reorder hunks.
-
-The apply and deploy summaries name why each component was skipped, for
-example `Applied 0, skipped 1 (1 already current)`. "Already current" means
-the source is unchanged since the last recorded apply and the engine copy
-still matches it. The apply state is shared by every session on the checkout,
-so that apply may have been another session's, such as a peer's
-`test --build`.
-
-## Renaming
-
-`furnace rename <old> <new>` moves the component and rewrites its
-registrations in place. The `customElements.js` entry keeps its position,
-layout and `// <MARKER>:` comments (the marker is `markerComment` from
-`fireforge.json`, else the upper-cased `binaryName`); an entry is only added
-fresh, with the marker, when none existed. The old entry never survives the
-rename. The locale `jar.mn` line is re-pointed only when the old component had
-one, so a `sharedFtl` component never gains a per-component `.ftl` line.
-`--dry-run` prints every file move and engine edit without writing.
-
-## Typed cross-module imports
-
-For multi-file components, set `furnace.json#typecheckJsconfig` to a
-consumer-owned jsconfig. `deploy` then maintains `compilerOptions.paths`
-entries that map each deployed
-`chrome://global/content/elements/<file>.mjs` URL to its workspace source.
-
-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.
-
-## Validation as a gate
-
-`furnace validate` prints its findings for people. A gate reads
-`furnace validate --json` instead: one document with the verdict
-(`passed`), the counts, per-component counts and every finding, specified in
-[`machine-output.md`](machine-output.md). Errors fail the run.
-`--max-warnings <n>` also fails it when more than `n` warnings remain, so
-`--max-warnings 0` keeps a component tree warning-clean.
-
-A finding that was reviewed and accepted is recorded in `furnace.json`
-rather than in a gate script:
+The deployed copy has the fragment inlined after the directive and fenced by an end marker; the project's source keeps only the directive. Editing a fragment changes the deployed content of every component that includes it.
+
+## Validating
+
+```sh
+npx fireforge furnace validate
+npx fireforge furnace validate moz-my-widget --max-warnings 0
+```
+
+`furnace validate` checks every component against the rules below and ends with a verdict line. Errors fail; warnings fail past `--max-warnings` (or `check.maxWarnings.furnace` inside `check`). The accessibility checks read the composed component (`<tag>.mjs` and its `<tag>-*.mjs` modules together) and are heuristics over source text.
+
+| Check                           | Severity | Finds                                                                                                 |
+| ------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| `missing-mjs`                   | error    | A custom component without `<tag>.mjs`                                                                |
+| `missing-css`                   | warning  | A component without `<tag>.css`                                                                       |
+| `missing-ftl`                   | error    | A localized component without its `.ftl` (and no `sharedFtl`)                                         |
+| `conflict-markers`              | error    | Unresolved merge conflict markers                                                                     |
+| `filename-mismatch`             | error    | Files not named `<tag>.*` or `<tag>-*`                                                                |
+| `missing-fragment`              | error    | An include of a fragment `components/shared/` does not have                                           |
+| `no-aria-role`                  | warning  | Generic interactive markup without native semantics or `role=`                                        |
+| `no-keyboard-handler`           | warning  | `@click` without a keyboard handler                                                                   |
+| `hardcoded-text`                | warning  | Text that should be a `data-l10n-id` (a `// furnace-ignore: hardcoded-text` comment exempts a module) |
+| `no-delegates-focus`            | warning  | An interactive component without `delegatesFocus`                                                     |
+| `positive-tabindex`             | warning  | A positive `tabindex`                                                                                 |
+| `unlabelled-form-input`         | warning  | A form input without an accessible label                                                              |
+| `icon-button-label`             | warning  | An icon-only `<moz-button>` without an accessible name; runs only when `optInChecks` lists it         |
+| `relative-import`               | error    | A relative import instead of a `chrome://` or `resource://` URL                                       |
+| `no-custom-element-define`      | error    | A module that never calls `customElements.define()`                                                   |
+| `not-moz-lit-element`           | error    | A class that does not extend `MozLitElement`                                                          |
+| `raw-color-value`               | error    | A raw colour instead of a design token                                                                |
+| `token-prefix-violation`        | error    | A `var()` outside the token prefix, `tokenAllowlist` and `runtimeVariables`                           |
+| `excessive-important`           | warning  | More than three `!important`                                                                          |
+| `missing-reduced-motion`        | warning  | An animation or transition without a `prefers-reduced-motion` query                                   |
+| `prefers-color-scheme`          | warning  | A `prefers-color-scheme` query; theme through tokens instead                                          |
+| `compose-not-referenced`        | warning  | A `composes` entry the template and stylesheet never reference                                        |
+| `override-base-version-drift`   | error    | An override taken from another Firefox version than the project builds                                |
+| `missing-component-dir`         | error    | A `furnace.json` entry whose directory is missing or empty                                            |
+| `component-floor`               | error    | Fewer components judged than `minComponents`                                                          |
+| `typing-drift`                  | error    | A generated typing file out of date                                                                   |
+| `deployment-stale`              | error    | The engine does not hold a component as the project has it                                            |
+| `validation-exception-on-error` | error    | A `validationExceptions` entry that matches an error                                                  |
+| `stale-validation-exception`    | warning  | A `validationExceptions` entry that matches nothing                                                   |
+
+`furnace.json#validationExceptions` accepts reviewed warnings: `{ "component", "check", "reason" }`, narrowed with `tag` or `file`. An exception never accepts an error.
 
 ```json
 {
   "validationExceptions": [
     {
-      "component": "moz-dock-button",
-      "check": "no-keyboard-handler",
-      "reason": "Activation goes through the inner moz-button."
+      "component": "moz-my-widget",
+      "check": "hardcoded-text",
+      "file": "moz-my-widget-debug.mjs",
+      "reason": "Developer-only panel, not shipped in release"
     }
   ]
 }
 ```
 
-An entry suppresses every finding of `check` (the name `validate` prints in
-brackets) on `component`. Each field is required and the reason must be
-non-empty, because the entry is the review record. Suppressed findings are
-still listed, with their reason, under `excepted` in the JSON document and
-counted in the summary. An entry that matches nothing is stale: the finding
-it records is gone, so `validate` reports a `stale-validation-exception`
-warning asking for the entry to be deleted. A run over one component judges
-only that component's entries. `deploy` honours the same entries when it
-validates, but leaves the staleness report to `validate`.
-
-An entry never suppresses an error: an error blocks apply,
-and a review record cannot make a broken component deployable. The error
-stays counted, and the entry is reported as a
-`validation-exception-on-error` error until the finding is fixed and the
-entry deleted.
-
-An optional `tag` narrows an entry to findings about one element tag, so a
-reviewed `<panel-list>` menu does not mute `no-keyboard-handler` for the
-rest of the component. A finding that names several tags (`no-keyboard-handler`
-names every synthetic element with an `@click`) is suppressed only when
-entries cover all of them:
-
-```json
-{
-  "component": "moz-vault",
-  "check": "no-keyboard-handler",
-  "tag": "li",
-  "reason": "Rows are reached through the list's roving focus."
-}
-```
-
-An optional `file` narrows an entry the same way to findings
-in one module of the component, by file name. `hardcoded-text` names the
-modules it found text in, so a vendored bundle whose bytes are pinned (and
-so cannot carry a `furnace-ignore` comment) can be accepted while the
-authored modules beside it keep the check. An entry names a `tag` or a
-`file`, not both:
+## Typing files
 
-```json
-{
-  "component": "moz-editor",
-  "check": "hardcoded-text",
-  "file": "moz-editor-codemirror.mjs",
-  "reason": "The vendored bundle's width probe is never rendered."
-}
+```sh
+npx fireforge furnace types
+npx fireforge furnace types --check
 ```
 
-Accessibility checks judge the composed component: the host
-`<tag>.mjs` and its companion modules (`<tag>-*.mjs`, tests and stories
-left out) read as one source. Moving a template between the component's
-modules therefore does not change its findings: a keyboard handler in a
-companion covers an `@click` in the host, and an `@click` in a companion
-is judged too. `hardcoded-text` judges each module on its own, so a
-`// furnace-ignore: hardcoded-text` comment covers the file it is in, not
-its siblings. Toolkit's `panel-item` counts as natively
-keyboard-activated, beside `button`, form controls and the `moz-*` buttons.
-
-`minComponents` sets the fewest components a full `furnace validate` must
-judge. A run under it, an empty tree included, fails with a
-`component-floor` error on `furnace.json`, so a moved or emptied
-components tree cannot pass by validating nothing. A run naming one
-component is not held to it.
+`furnace types` writes two files from the components, so code that imports a component module or creates its element is typed:
 
-```json
-{ "minComponents": 40 }
-```
-
-`optInChecks` turns on checks that are off by default:
+- `typecheckJsconfig`: in each named `jsconfig.json`, a `compilerOptions.paths` entry per component module, mapping its chrome URL to its source in `components/custom/`. Other entries are left alone.
+- `typecheckTagMap`: a declaration file adding each registered element whose module exports its class to `HTMLElementTagNameMap`. Furnace owns the whole file.
 
-```json
-{ "optInChecks": ["icon-button-label"] }
-```
+A path starting `engine/` names the project's tracked copy of that engine file (`engine/` itself in patch mode, `src/` in source mode); any other path is relative to the project root. `--check` writes nothing and fails while a file is out of date. `typecheck`, `furnace validate` and `doctor` all refuse or report stale typing files.
 
-`icon-button-label` warns about an icon-only `<moz-button>` in a component's
-Lit templates (one with an `iconsrc` or an `icon` type, and no `label` or
-text content) that has neither `data-l10n-id` nor `aria-label`, so a screen
-reader would announce it only as "button". A button built with
-`document.createElement` is not seen.
-
-## Safety
-
-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]`, and that budget
-covers both locks they take. The leaves that take only the furnace lock
-(`create`, `remove`, `rename`, `refresh`, `scan`, `override`, `preview` and
-the `chrome-doc` pair) apply the flag to that lock. Without the flag, the
-session budget from `FIREFORGE_WAIT_LOCK` applies. See
-[`configuration.md`](configuration.md#lock-waits).
-
-`build` and `test` rewrite deployed component files from their sources before
-building, and `--refuse-unexported-drift` refuses when that would destroy
-engine content no patch records. A deployed file that is a Furnace deployment
-of its own source is classified `deployed-unexported` and allowed: it equals
-the composed current source, differs from it only inside generated fragment
-expansions, or is exactly what the last recorded apply deployed. Those files
-are listed in an informational note, since their patches still owe a
-re-export. Only content that matches no patch body, no baseline and none of
-these source forms is refused.
+See [authoring.md](authoring.md) for design tokens, manifest registration and chrome script wiring.