rigortype 0.4.6 → 0.4.8

data/docs/manual/02-cli-reference.md

@@ -10,6 +10,8 @@ rigor <command> [options] [arguments]
 `rigor help` prints the command list; `rigor version` prints
 the installed version. An unknown command, or a malformed
 option, exits `64` — the conventional "usage error" code.
+See [`rigor help`](#rigor-help) for a single command's help and
+the machine-readable list of commands and flags.
 
 Every command that loads your project configuration also
 accepts `--config=PATH` to point at a specific config file
@@ -46,7 +48,7 @@ check their arity, since another file may redefine them.
 | `--no-cache` | Skip the persistent cache for this run. With `--incremental` it is a cold full analysis: the incremental snapshot and the run-result cache are neither read nor written, so the next plain `--incremental` run still uses the snapshot it had before. |
 | `--incremental` | Re-analyse only the files changed since the last run plus the files that depend on them, serving the rest from a cross-process disk snapshot (ADR-46). Diagnostics are identical to a full run; a config / gem / version change (or a file added or removed) transparently forces a full re-analysis. A run with nothing changed is answered from the cache without starting the analyzer. See [Caching](12-caching.md). |
 | `--verify-incremental` | Acceptance gate: run the incremental analyzer against a full `--no-cache` run and assert the diagnostics agree as a set and in the same order, then exit (0 on match, 1 on mismatch: the differing diagnostics for a set mismatch, or the first index where the order diverges for a same-set, different-order mismatch). It re-analyses half of an unchanged tree and serves the other half from cache, so it checks the cache-merge path but not that an edit re-checks every file it affects; `--verify-incremental-edits` adds that. |
-| `--verify-incremental-edits=N` | With `--verify-incremental` (and implying it): after the check above, replay two edits on each of `N` files spread over the analysed list, through an editor buffer, never on disk: the file emptied, then the file reduced to its `class` / `module` declarations with every body dropped (skipped when that is the file itself, or holds no declaration). After each edit, the warm recheck of the baseline must equal a full analysis of the edited tree, or the run fails naming the edit and the file. Each replay costs a recheck and a full analysis. A replay the recheck declines (it would have been a full analysis) is counted in the OK line, and the run fails if every replay declined. Only these two removals are replayed, never an addition. Default 0. |
+| `--verify-incremental-edits=N` | With `--verify-incremental` (and implying it): after the check above, replay edits on each of `N` files spread over the analysed list, through an editor buffer, never on disk: the file emptied; the file reduced to its `class` / `module` declarations with every body dropped (skipped when that is the file itself, or holds no declaration); and up to two copies of the file each missing one statement of a `class` / `module` body, with everything else kept, so a finer dependency edge is the only thing that re-checks a reader (visibility calls such as `private` and `module_function` are dropped first, then other statements spread over the file). After each edit, the warm recheck of the baseline must equal a full analysis of the edited tree, or the run fails naming the edit and the file. Each replay costs a recheck and a full analysis. A replay the recheck declines (it would have been a full analysis) is counted in the OK line, and the run fails if every replay declined. Only removals are replayed, never an addition. Default 0. |
 | `--clear-cache` | Delete the cache directory before running. |
 | `--cache-stats` | Print the on-disk cache inventory when finished — on stdout under `--format text`, on stderr under every other format, so machine-readable output stays a parseable document. `--clear-cache`'s and `--verify-incremental`'s notes follow the same rule. |
 | `--[no-]stats` | Print a run summary (files, classes, memory, wall time) to stderr. Default on. |
@@ -60,7 +62,7 @@ check their arity, since another file may redefine them.
 | `--bleeding-edge[=ids]` | Adopt the bleeding-edge overlay for this run, overriding the configured [`bleeding_edge:`](03-configuration.md) selection (ADR-50 § WD2). Bare adopts every queued feature; `--bleeding-edge=a,b` adopts only the named feature ids. Inspect it with [`rigor show-bleedingedge`](#rigor-show-bleedingedge). |
 | `--no-bleeding-edge` | Ignore any configured `bleeding_edge:` selection for this run (adopt none). |
 | `--no-tolerated-effects` | Check effect envelopes as if [`effects.tolerated:`](03-configuration.md) were empty — the audit switch for your discharge policy (ADR-103). Judgment only: the run, what it collects and its cache entry are identical either way, so this never costs a re-analysis. |
-| `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together. Alone, only the buffer's own file produces diagnostics; add `--incremental` for whole-project scope (see below). |
+| `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together, once per run (a repeat is a usage error). Alone, only the buffer's own file produces diagnostics; add `--incremental` for whole-project scope (see below). |
 
 Exit `0` when no error-severity diagnostics remain, `1` when
 any are reported, `64` on a usage error. `--fail-on` raises that
@@ -70,14 +72,16 @@ that want the stricter reading.
 ### Editor mode scope
 
 `--tmp-file` / `--instead-of` on their own analyse **only** the
-buffer's file. It still reads the rest of the project's declarations
-(the classes and methods other files define), as `rigor check FILE`
+buffer's file. The `--instead-of` logical path is analysed even when it
+lies outside `paths:`, as it always has been. It still reads the rest of the
+project's declarations (the classes and methods other files define), as `rigor check FILE`
 does, but it reports nothing about what the unsaved edit does to the
 rest of the project.
 
 Adding `--incremental` analyses the **whole project with the buffer
 substituted** — the edited file and the files that depend on it are
 re-analysed, everything else is served from the incremental snapshot.
+A buffer for a claimed template is analysed as its template unit, once.
 An unsaved change to a method's return type therefore surfaces in its
 callers, not just in the file being edited.
 
@@ -91,6 +95,11 @@ Two things to know:
   exist only in your editor, and recording them would make the next
   ordinary run believe it had already analysed a file in a state it
   was never in.
+- The buffer's file need not exist on disk yet: a new file is analysed
+  as an added file, with or without path arguments.
+- Editor mode binds one buffer per run. Repeating `--tmp-file` or
+  `--instead-of` is a usage error (exit `64`), not a silent replacement
+  of the earlier pair.
 
 `--verify-incremental` refuses a buffer: it compares against a full
 analysis of the files on disk, which a buffer contradicts by
@@ -101,31 +110,82 @@ construction.
 Write a starter configuration file.
 
 ```sh
-rigor init [--path=PATH] [--force]
+rigor init [--path=PATH] [--force] [--no-plugins]
 ```
 
 Writes `.rigor.dist.yml` by default. `--path` chooses a
 different target; `--force` overwrites an existing file.
-Exit `1` if the file exists and `--force` was not given.
+Exit `1` if the file exists and `--force` was not given. A `--path` whose
+directory does not exist, or that cannot be written, is a usage error: one
+`rigor init: cannot write PATH: REASON` line on stderr and exit `64`. The
+directory is not created.
+
+When the project has a `Gemfile.lock` in the working directory,
+`rigor init` suggests the bundled plugins whose gems the lockfile
+declares (the same read as [`rigor doctor`](#rigor-doctor)'s
+plugin-gap check). The suggestions are commented out under
+`plugins: []`, so nothing loads until you enable one: delete the
+`[]` on the `plugins:` line, uncomment the entries you want, then
+run `rigor plugins --strict`. A Rails project's `rails` also brings
+in the Rails family, so the list can be long. Without a lockfile,
+or when no locked gem has a bundled plugin, the template has no
+suggestions.
+
+Suggesting rather than enabling follows ADR-96 Criterion 2: a
+lockfile's presence does not by itself opt a project into a
+plugin's code.
+
+In a Rails application (a `config/application.rb` in the working
+directory), `rigor init` also suggests the source directories that
+exist, `app` and `lib`. The active `paths:` stays `lib`; the
+suggestion is a commented `paths:` line under it, which names what
+was detected. A bare `rigor check` analyses only `lib` until you
+delete the `paths:` list above and uncomment the line below. Other
+layouts get no directory suggestion.
+
+`--no-plugins` writes the template with no plugin suggestions, even
+when a lockfile is present.
 
 ## `rigor annotate`
 
-Reprint a file with every line tagged by the type of the
-expression it evaluates to, as a trailing `#=>` comment. See
-[Inspecting inferred types](05-inspecting-types.md).
+Reprint a source file with every line tagged by the inferred type of the expression it evaluates to, as a trailing `#=>` comment (following the xmpfilter / seeing_is_believing convention). See [Inspecting inferred types](05-inspecting-types.md).
 
 ```sh
-rigor annotate [--[no-]color] [--[no-]bat] [--format=text|json] [--config=PATH] FILE
+rigor annotate [options] FILE
 ```
 
-`FILE` is required. Colour is auto-detected for a tty and
-honours `NO_COLOR`; `--color` / `--no-color` override. When
-colour is on and [`bat`](https://github.com/sharkdp/bat) is on
-`PATH`, highlighting goes through bat (`--no-bat` opts out;
-`--bat` warns if bat is missing and falls back to the built-in
-colorizer). `--format=json` emits a `{ line => type }` map
-instead of the annotated source. Exit `1` on a parse error or a
-missing file.
+| Flag | Purpose |
+| --- | --- |
+| `--config=PATH` | Path to `.rigor.yml`. Overrides auto-discovery. |
+| `--format=FORMAT` | Output format (`text` or `json`). Default: `text`. |
+| `--[no-]color` | Force or disable ANSI color (default: auto-detected for a tty; honors `NO_COLOR`). |
+| `--[no-]bat` | Force or disable syntax highlighting through [`bat`](https://github.com/sharkdp/bat) (default: enabled when color is on and `bat` is found on `PATH`). |
+
+The positional `FILE` argument is required. For each line, the command locates the last expression evaluated on that line (e.g. the last statement in `1; 2; 3` reports `3`, and a conditional header `if nil` reports its condition) and annotates it with `#=> <type>`. On method definition headers (`def`), the line is annotated with the method's inferred return type rather than the header expression.
+
+Annotations are idempotent: re-running `rigor annotate` matches existing `#=>` comments (as well as legacy `#=> dump_type:` comments) and replaces them in-place instead of stacking comments.
+
+When color is enabled and `bat` is installed, output is syntax-highlighted via `bat --language=ruby --style=plain --paging=never`. Passing `--no-bat` disables `bat` integration in favor of Rigor's built-in Prism colorizer. `--bat` warns on stderr and falls back to the built-in colorizer if `bat` is not found on `PATH`.
+
+In `--format=json`, the command emits a JSON object mapping line numbers to type strings conforming to schema version 1:
+
+```json
+{
+  "schema_version": 1,
+  "annotations": {
+    "1": "Integer",
+    "2": "String | nil"
+  }
+}
+```
+
+Exit `0` on success, `1` if the file does not exist or contains a Prism syntax error, and `64` on usage errors (such as a missing `FILE` argument).
+
+## JSON documents
+
+Every `--format=json` document Rigor defines whose top level is an object, except the three named below, starts with an integer `schema_version` (currently `1`). Where a flag selects which document is printed, `mode` follows it: `rigor coverage` prints `precision`, `protection`, `mutation` or `protection-fused`, and `rigor plugins` prints `status` or `capabilities`. The key set is contract from v1.0.0: a minor release may add a key, and removing or renaming one needs a major.
+
+`rigor lens` (its own `schema` / `revision`), `rigor baseline dump` (`version`) and `rigor check`'s CI formats (`sarif`, `gitlab`, ...) keep their own markers. `rigor type-of`, `rigor explain` and `rigor trace` are the exceptions and still print their current top-level shape (an array; for `type-of` a flat object or `{ results }`; for `explain <skip-reason>` a flat object); the next minor release switches them to `{ "schema_version": 1, "results" | "rules" | "skip_reasons" | "events": [...] }`. Until then each prints a note on stderr, and the matching MCP tools append the same note as an extra text block.
 
 ## `rigor type-of`
 
@@ -148,7 +208,8 @@ wraps several results in a `results` array. Line queries add a
 `line_enumerations` array whose `shown` and `total` counts make
 truncation explicit. `--trace` records fail-soft fallbacks,
 after the rows of a line table in text output. The editor-mode
-`--tmp-file` / `--instead-of` pair is accepted as on `check`.
+`--tmp-file` / `--instead-of` pair is accepted as on `check`, and a repeated flag is a usage error
+(exit `64`) there too.
 
 A class or constant that another project file declares reads as
 `rigor check` types it (`singleton(User)`) when a bare
@@ -159,9 +220,13 @@ and never writes it. With no reusable snapshot (none yet, or one a
 change made unusable, for example a changed configuration, lockfile, `sig/`, `pre_eval:`
 file or required feature, an engine upgrade, or a snapshot written
 for other roots) the probe types the one file on its own, so such a name reads
-`Dynamic[top]`, and it prints nothing about it. Only those
-declarations are shared: the types `check` infers for an unannotated
-parameter are not.
+`Dynamic[top]`, and it prints nothing about it. With
+`parameter_inference: true`, the types `check` infers for an
+unannotated parameter come from the same snapshot (its recorded
+call-site table), so `@v = v` reads as `check` types it, but only
+while no project file has changed since the snapshot (an editor
+buffer whose bytes differ from the snapshot counts as a change); once any file differs, or with the setting off
+or no snapshot, those types are not shared.
 
 A template a plugin compiles into Ruby (an ERB view under
 `rigor-actionpack`) is probed the way `rigor check` analyses
@@ -200,58 +265,144 @@ against `rigor check --no-cache` removes that variable.
 
 ## `rigor lens`
 
-Map the declarations of one or more files with their types and
-type provenance (experimental). See
-[Inspecting inferred types](05-inspecting-types.md).
+Map the declarations of one or more files with their types and type provenance (experimental). See [Inspecting inferred types](05-inspecting-types.md).
 
 ```sh
-rigor lens [--format=text|json] [--config=PATH] [--workers=N] FILE...
+rigor lens [options] FILE...
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `--config=PATH` | Path to `.rigor.yml`. Overrides auto-discovery. |
+| `--format=FORMAT` | Output format (`text` or `json`). Default: `text`. |
+| `--workers=N` | Worker process count for a cold run. |
+| `--claims=REQUEST` | Check documentation type claims against authored contracts (unreleased). Requires `--format=json`. |
+
+`rigor lens` performs the same incremental analysis as `rigor check --incremental` and shares its cache (`.rigor/cache`). The first execution on a file costs a full check, while subsequent runs reuse the recorded cache.
+
+`--claims=REQUEST` checks documentation type claims against authored contracts in the same run (unreleased). It requires `--format=json` and a UTF-8 JSON request following the [claims contract](../internal-spec/lens-claims.md). The `claims` section reports each claim's verdict; a conflict does not change the exit status. An invalid or stale request exits `64` without a document. Claims do not alter analysis, diagnostics or cached types.
+
+### Text representation
+
+Text output lists each declaration preceded by an anchor identifier:
+
+```text
+lib/shop.rb  xxh3-64:845f7426b6acfe12  (2 omitted)
+  4:7c90  class Shop
+  8:e37e  Shop#label: (::Integer n) -> ::String  [contract inline]
+  14:ce93  Shop#total: () -> Integer  [single_site inferred]
+  16:182b  Shop#fetch  [contested; also lib/legacy_shop.rb:2]
+  omitted constant Shop::LIMIT (line 5)
 ```
 
-A lens runs the same incremental analysis as
-`rigor check --incremental` and reads and writes its cache.
-`--workers` applies to a cold run. `--format=json` writes one
-`lens/v0` document ([specification](../internal-spec/lens.md)).
-Exit `0` when at least one file has a result, `1` when none
-does, `64` on a usage error; diagnostics in the code never
-change the exit status.
+- **`LINE:HASH`**: Stable anchor hash identifying the declaration. It changes when the declaration signature or preceding type comments change, but remains unchanged across prose comment edits.
+- **`provenance`**: The origin of the type in square brackets (e.g. `[contract sig]`, `[contract inline]`, `[single_site inferred]`, `[plugin <name>]`).
+- **`contested`**: Denotes methods where multiple definitions exist in the project (e.g. reopened classes across files); Rigor prints no signature rather than guessing runtime dispatch.
+- **`omitted`**: Constructs not yet modeled by the lens (constants, `alias`, `define_method`) are explicitly recorded as omitted rather than discarded.
+
+In `--format=json`, the command outputs a `lens/v0` JSON document (specified in [the lens output contract](../internal-spec/lens.md)).
+
+Exit `0` when at least one input file is successfully analysed (`status: "ok"`), `1` when no target achieves `status: "ok"` (the JSON document is still written to stdout), and `64` on usage errors (such as missing `FILE` arguments or an unreadable `--config` path). Diagnostics present in the analysed files do not affect the exit code.
 
 ## `rigor trace`
 
-Replay HOW the engine typed a file, step by step, as a
-terminal animation. It is a teaching probe over the same
-inference `rigor check` runs.
+Replay how the engine typed a file step-by-step as an interactive terminal animation. It is a teaching and debugging probe operating over the inference engine. See [Inspecting inferred types](05-inspecting-types.md).
 
 ```sh
-rigor trace [--delay=SECONDS] [--line=N] [--verbose] [--format=json] FILE
+rigor trace [options] FILE
 ```
 
-Each frame highlights the source range being evaluated next to
-the scope's locals and describes one inference moment: a local
-binding entering the scope (`bind`), branch types merging
-(`union`), or a method call resolving — or fail-softening to
-`Dynamic[top]` (`dispatch`). On a tty the replay steps on a key
-press (`q` quits); `--delay` autoplays. `--verbose` adds every
-expression enter/result frame, `--line=N` keeps only events on
-one line, and `--format=json` dumps the raw event stream for
-tooling or course material. See
-[Inspecting inferred types](05-inspecting-types.md).
+| Flag | Purpose |
+| --- | --- |
+| `--config=PATH` | Path to `.rigor.yml`. Overrides auto-discovery. |
+| `--delay=SECONDS` | Autoplay frames with `SECONDS` delay between steps (default: step manually on key press). |
+| `--line=N` | Replay only inference events whose source range starts on line `N`. |
+| `--verbose` | Include every expression `enter` and `result` frame (default: only teachable inference milestones). |
+| `--format=FORMAT` | Output format: `text` (interactive terminal animation) or `json` (raw event stream). Default: `text`. |
+
+### Inference events
+
+By default, the replay highlights the AST expression being evaluated alongside the current local variable environment, presenting three core inference event kinds:
+- **`bind`**: A local variable binding enters the active scope.
+- **`union`**: Types from distinct control-flow branches merge into a union type.
+- **`dispatch`**: A method call resolves against its receiver or falls back to `Dynamic[top]`.
+
+With `--verbose`, every AST node entry and evaluated type result is captured as a frame.
+
+### Interactive navigation
+
+On a terminal TTY, the animation advances one frame per key press. Press `q` to exit playback early. Specifying `--delay=SECONDS` enables hands-free autoplay.
+
+In `--format=json`, the raw stream of event objects is emitted as a top-level JSON array for external tooling or courseware integration. Like `rigor explain`, it prints a deprecation notice on stderr noting the upcoming `schema_version: 1` envelope migration (see [JSON documents](#json-documents)).
+
+Exit `0` on successful playback or stream emission, `1` if the file does not exist or contains syntax errors (Prism parse errors), and `64` on usage errors (such as missing `FILE`, passing multiple files, or invalid flags).
 
 ## `rigor type-scan`
 
-Report `type_of` inference coverage across paths — a
-diagnostic-of-the-diagnoser, useful when investigating why a
-class infers poorly.
+Report `Scope#type_of` inference coverage across paths — an engine diagnostic measuring how much of the target source is directly typed without falling back to `Dynamic[top]`.
 
 ```sh
-rigor type-scan PATH...
+rigor type-scan [options] PATH...
 ```
 
-`--limit=N` caps the printed examples (default 10),
-`--show-recognized` includes fully-covered classes,
-`--threshold=RATIO` makes the command exit non-zero when the
-unrecognized-node ratio exceeds `RATIO`, and `--format=text|json`
-selects the output format. `--config=PATH` overrides config discovery.
+| Flag | Purpose |
+| --- | --- |
+| `--config=PATH` | Path to `.rigor.yml`. Overrides auto-discovery. |
+| `--format=FORMAT` | Output format (`text` or `json`). Default: `text`. |
+| `--limit=N` | Maximum unrecognized example events to display in text mode. Default: `10`. |
+| `--show-recognized` | Include AST node classes with 0 unrecognized visits in the summary table. |
+| `--threshold=RATIO` | Exit non-zero (`1`) when the ratio of unrecognized nodes (`unrecognized / visits`) exceeds `RATIO` (float). |
+
+At least one `PATH` argument is required. The command traverses every Prism node across the specified paths and queries `Scope#type_of` against a discovery-seeded project environment (matching `rigor coverage`).
+
+### Output format
+
+In text mode, `rigor type-scan` prints a summary block, class breakdown, and unrecognized examples:
+
+```text
+Type-of scan: 1 file
+  - lib/user.rb
+
+Summary:
+  files processed:   1
+  parse errors:      0
+  AST nodes visited: 165
+  unrecognized:      14 ( 8.5%)
+
+Coverage by node class (unrecognized/visits):
+  Prism::CallNode              12/120 ( 10.0%)
+  Prism::ConstantReadNode       2/ 45 (  4.4%)
+
+Unrecognized examples (showing 10 of 14):
+  Prism::CallNode  @  lib/user.rb:14:5
+```
+
+Passing `--show-recognized` includes node classes with 0 unrecognized visits in the class breakdown. `--limit=N` caps the total number of examples shown in the unrecognized events section.
+
+In `--format=json`, the command emits a JSON document conforming to schema version 1:
+
+```json
+{
+  "schema_version": 1,
+  "files": [ "lib/user.rb" ],
+  "summary": {
+    "files_processed": 1,
+    "parse_errors": 0,
+    "visited": 165,
+    "unrecognized": 14,
+    "unrecognized_ratio": 0.0848
+  },
+  "by_class": {
+    "Prism::CallNode": { "visits": 120, "unrecognized": 12 }
+  },
+  "events": [
+    { "file": "lib/user.rb", "node_class": "Prism::CallNode", "family": "call", "line": 14, "column": 5 }
+  ],
+  "parse_errors": []
+}
+```
+
+Exit `0` if the unrecognized ratio is within `--threshold` (or when no threshold is set) and no parse errors occurred. Exit `1` if the ratio exceeds `--threshold` or if any scanned file contains parse errors. Exit `64` if no paths are provided, a specified path does not exist, or flags are invalid.
 
 ## `rigor effects`
 
@@ -384,6 +535,12 @@ origin/main:.rigor-effects.yml)` in a bot),
 `explain` additionally accepts `--symbol=KEY` to explain one
 specific unit instead of the changed ones.
 
+`update` writes `effects.snapshot.path:` (default
+`.rigor-effects.yml`). A path whose directory does not exist, or
+that cannot be written, is a usage error: one
+`rigor effects: cannot write PATH: REASON` line on stderr and
+exit `64`. The directory is not created.
+
 The file records two tables. `methods:` holds each method's
 **direct** summary — what its own body does, block literals
 and catalogued callees included, but not what the project
@@ -501,38 +658,107 @@ reviewer's judgment, which is what makes it a review artefact.
 
 ## `rigor explain`
 
-Print the catalogue entry for a diagnostic rule, or list every
-rule when called with no argument.
+Print the catalogue entry for a diagnostic rule, or list every rule when called with no argument.
 
 ```sh
-rigor explain [options] [rule]
+rigor explain [options] [<rule>]
 ```
 
-`rule` is a rule ID (`call.undefined-method`), a legacy alias,
-or a family wildcard (`call`, `flow`, `def`, `assert`, `dump`, `global`,
-`suppression`, `static`, `effect`).
-`--format=text|json` selects the output format. Exit `64` for an unknown rule.
+| Flag | Purpose |
+| --- | --- |
+| `--format=FORMAT` | Output format (`text` or `json`). Default: `text`. |
+
+### Invocation modes
+
+| Form | Purpose |
+| --- | --- |
+| (none) | Print the complete rule catalogue index (rule ID and one-line summary) followed by every `rigor sig-gen` skip reason. |
+| `<rule>` | Print the full catalogue entry for a canonical rule ID (e.g. `call.undefined-method`) or a legacy alias (e.g. `undefined-method`). |
+| `<family>` | Family wildcard (`call`, `flow`, `def`, `assert`, `dump`, `global`, `suppression`, `static`, `effect`). Prints every rule under that prefix. |
+| `<skip-reason>` | Print the explanation and recommended next action for an exact `rigor sig-gen` skip reason token (e.g. `sig.skipped.untyped-return`). Does not accept wildcards. |
+
+A rule entry includes its summary, legacy aliases, authored severity, severity mapped across configuration profiles (`lenient`, `balanced`, `strict`), evidence tier, `Fires when:` conditions, `Does not fire when:` exceptions, inline suppression syntax (`# rigor:disable <rule>`), documentation link, and the Rigor release where the rule was introduced.
+
+A `<skip-reason>` token explains why `rigor sig-gen` declined to write a signature (such as dynamic returns or unbounded blocks) and suggests what to address instead. Because skip reasons report signatures that were not written rather than code findings, they carry no severity and nothing to suppress.
+
+In `--format=json`, diagnostic rules (whether requested by a single rule ID, legacy alias, family wildcard, or with no arguments) always emit a JSON array of catalogue entry objects. In contrast, querying an individual `<skip-reason>` emits a single JSON object. In the index mode with no arguments, `--format=json` outputs only the diagnostic rule array; individual skip reasons must be queried by token. Top-level JSON shapes currently print a stderr deprecation notice regarding the future envelope migration (see [JSON documents](#json-documents)).
 
-It also answers the `sig.skipped.*` identifiers `rigor sig-gen`
-prints when it declines to write a signature — `rigor explain
-sig.skipped.untyped-return` says what the skip means and what to do
-instead. Those are not diagnostic rules, so they are rendered without
-a severity or a suppression line.
+Exit `0` on success, `64` on an unknown rule name or invalid options.
 
 ## `rigor diff`
 
-Compare the current diagnostics against a saved baseline JSON
-and report only what is new.
+Compare current diagnostics against a saved `rigor check --format=json` result and report the delta.
+
+```sh
+rigor diff [options] <rigor-check.json> [paths...]
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `--current=PATH` | Compare against a saved diagnostics JSON file instead of executing a fresh `rigor check` run. |
+| `--config=PATH` | Custom `.rigor.yml` configuration forwarded to the implicit `rigor check` run. Ignored when `--current` is supplied. |
+| `--format=FORMAT` | Output format (`text` or `json`). Default: `text`. |
+
+The positional `<rigor-check.json>` file is required. Per ADR-126 § WD1, this file is a saved `rigor check --format=json` result or JSON snapshot, distinct from the rule-bucket `.rigor-baseline.yml` managed by `rigor baseline`.
+
+When `[paths...]` are given, only those source paths are evaluated by the implicit check. Note that if `<rigor-check.json>` covers the entire repository, restricting the implicit check to a subset of paths causes all diagnostics in omitted files to be reported as `- FIXED`. When `--current=PATH` is provided, `[paths...]` are ignored.
+
+### Identity matching
+
+Diagnostic identity is determined by the 6-element tuple:
+
+```
+(path, line, column, rule, source_family, message)
+```
+
+Diagnostics matching a saved tuple are considered pre-existing. Current diagnostics missing from the saved snapshot are classified as `+ NEW` (regressions). Saved diagnostics missing from the current run are classified as `- FIXED` (progress). Moving code to another line or changing a message produces one fixed and one new entry. Severity is not part of the identity tuple; changing a diagnostic's severity without moving its location does not register as a diff.
+
+### Output format
+
+Text output reports the diff header, line-by-line additions and removals, and summary counts:
+
+```text
+# diff against rigor-check.json (10 baseline / 9 current)
++ NEW   lib/user.rb:14:5 [call.undefined-method] Method `full_name` does not exist on `User`
+- FIXED lib/auth.rb:22:9 [call.argument-type-mismatch] Expected `String`, got `Integer`
+
+1 new, 1 fixed
+```
+
+With `--format=json`, the output conforms to schema version 1:
+
+```json
+{
+  "schema_version": 1,
+  "baseline": "rigor-check.json",
+  "baseline_count": 10,
+  "current_count": 9,
+  "new": [ ... ],
+  "fixed": [ ... ]
+}
+```
+
+### CI integration
+
+`rigor diff` enables regression gating in repositories adopting Rigor incrementally by catching newly introduced diagnostics without requiring all legacy diagnostics to be fixed first.
+
+In standard CI workflows, commit a saved snapshot in-tree (e.g. `rigor-check.json`) generated by `rigor check --format=json > rigor-check.json`. In CI, run:
 
 ```sh
-rigor diff [options] <baseline.json> [paths...]
+rigor diff rigor-check.json
 ```
 
-`--current=PATH` compares against a saved diagnostics JSON
-instead of running a fresh check. `--format=text|json` selects the
-output format (default `text`), and `--config=PATH` passes a custom
-configuration to the implicit check. Exit `1` when new
-diagnostics appear.
+When comparing against a dynamic base branch in a multi-step job (where `rigor check` on the base branch may exit non-zero due to pre-existing diagnostics), guard the exit code under `set -e`:
+
+```sh
+# On base branch (or via git show / artifact)
+rigor check --format=json > /tmp/base-check.json || true
+
+# On PR branch
+rigor diff /tmp/base-check.json
+```
+
+Exit `0` when no new diagnostics appear (`new` is empty, even if `fixed` contains entries). Exit `1` when any new diagnostic of any severity (`error`, `warning`, or `info`) appears. Exit `64` if either JSON file is missing, contains invalid JSON, or command usage is incorrect.
 
 ## `rigor sig-gen`
 
@@ -571,10 +797,27 @@ refuse a file, so a tighter return `--write` declines without
 `--overwrite` does not fail it; `--check --overwrite` counts one.
 See [handbook chapter 11](../handbook/11-sig-gen.md#keeping-sig-current-in-ci).
 
+`--write` also repairs a header in any file under the signature directory it writes to (the directory
+under the project root named like the last path component of the first `signature_paths:` entry, `sig/` by
+default, vendored or generated `.rbs` under it included) that opens a generic class such as
+`class Array` or `class Hash` without its type parameters (an earlier release wrote them), reporting
+`repaired N generic header(s)`, and `--check` fails until it is written. In `--format=json` the row of a file
+no method of the run maps to has `"source": null`. A class is repaired in all of its bare headers or in none:
+when the body of any of them names a type spelt like one of the parameters (`def old: () -> E`), which the
+parameter would capture, or one of them is in another `signature_paths:` entry, which `--write` never
+rewrites, none is repaired. A `generic header left bare` line (`left_bare` in `--format=json`) names the files
+and the reason, and `--check` does not fail on it. Write the name as `::E`, or fix the other file, to let the
+repair through.
+
 `--write` names each proposal it skipped (a member `sig/` already declares, an `alias` included, or one that
 routes to a signature path it does not write to, because it is declared there or its class lives there) on its own `skipped Class#method (reason)` line; the exit status is
 unchanged. See [handbook chapter 11](../handbook/11-sig-gen.md#safety-what---write-will-and-will-not-do).
 
+A `sig/` target `--write` cannot write — a permission denial, a directory sitting where the `.rbs`
+belongs, or a parent path that is a regular file — is a usage error: one `rigor sig-gen: cannot
+write PATH: REASON` line on stderr and exit `64`. A missing parent directory is created as before.
+The run stops at the first failure; targets already written stay written.
+
 A method declared inline with `# @rbs` / `#:` is written as that
 declaration, not as what its body infers; a parameter-only
 annotation keeps its parameters and takes the return from the body,
@@ -614,7 +857,13 @@ would take every other type in the file down with it. Under
 **refused** (the existing file is left untouched) and the command
 exits `1`: you asked for a write and did not get one. Such a skip
 is a bug in Rigor's RBS rendering, not in your code — please
-report it.
+report it. An existing target that does not parse as RBS in the
+first place, and that sig-gen would write into, is refused the same
+way, named on stdout as `REFUSED` with the parse location (the JSON
+action is `skipped_unparseable`); `--check` fails on it too, so such a
+target is never reported as up to date. An unparseable `sig/` file that
+no emittable candidate maps to is not refused and still passes
+`--check`. Fix its syntax error and re-run.
 
 A method the generator declined for any other reason (a body
 that proves only `untyped`, a user-authored declaration it will
@@ -634,10 +883,20 @@ Run the Language Server over stdio. See
 rigor lsp [--transport=stdio] [--log=PATH] [--config=PATH]
 ```
 
-`stdio` is the only transport in v1. `--log=PATH` is accepted
-but not yet wired in this release — it is reserved for routing
-the server's wire log to a file; until then logging stays on
-stderr.
+`stdio` is the only transport in v1. `--log=PATH` appends the LSP
+wire log to PATH: each JSON-RPC message the client sends (`<-`) and
+each one the server writes (`->`), one line per message with a
+timestamp, plus the server's debug output from the start of the
+server loop to its end. The file is opened for appending before the
+server starts, so an unwritable PATH exits with a usage error. An
+exception that escapes the loop is written to the file with its
+backtrace. Output written before the loop starts (configuration
+loading and server setup) and any crash outside the loop still go to
+stderr, as does the server's output when the file becomes unwritable
+mid-session. A message the JSON encoder rejects (raw invalid UTF-8) is
+logged in a scrubbed form. Without `--log`, no wire log is written and
+the server's debug output goes to stderr; stdout carries only the
+protocol.
 
 ## `rigor baseline`
 
@@ -661,6 +920,18 @@ rigor baseline <generate|regenerate|dump|drift|prune> [options]
 `--baseline=PATH` to read a non-default baseline file. `dump`
 also accepts `--format=text|json` for machine-readable output.
 
+A write target — `generate` and `regenerate`'s `--output`, or the
+`--baseline` file `prune` rewrites — whose directory does not exist,
+or that cannot be written, is a usage error: one
+`rigor baseline: cannot write PATH: REASON` line on stderr and exit
+`64`. The directory is not created.
+
+No subcommand takes a positional path: `generate` and `regenerate`
+analyse the configured `paths:`, `drift` and `prune` audit them, and
+`dump` reads the baseline file and filters with `--rule`/`--file`. A path argument is a usage error
+(exit `64`). Narrow the scope with `paths:` in the configuration, not on
+the command line.
+
 ## `rigor triage`
 
 Summarise a diagnostic stream — rule distribution, **class/method
@@ -1011,30 +1282,50 @@ toolchain, so you can read a real, working plugin as a worked
 example when authoring your own.
 
 ```sh
-rigor plugin <list|path|print|root> [name]
+rigor plugin [<name>] [--path <name>] [--list] [--root]
 ```
 
-| Subcommand | Purpose |
+The positional slot is a plugin *name*; alternative outputs are
+flags, the same grammar as `rigor skill` and `rigor docs`.
+
+| Form | Purpose |
 | --- | --- |
-| `list` | Table of every bundled plugin and example, name + absolute directory path (default when no subcommand given). |
-| `path <name>` | One-line absolute path to the plugin's directory. |
-| `print <name>` | A header (dir / lib / sig / README paths) followed by the plugin's main source body inlined. |
-| `root` | The `rigortype` gem root and its key subdirectories. |
+| `rigor plugin`, `--list` | Table of every bundled plugin and example, name + absolute directory path (the default). |
+| `<name>` | A header (dir / lib / sig / README paths) followed by the plugin's main source body inlined. |
+| `--path <name>` | One-line absolute path to the plugin's directory. |
+| `--root` | The `rigortype` gem root and its key subdirectories. |
+
+The earlier verbs `list`, `path <name>`, `print <name>` and `root`
+still work for one minor release and print a deprecation notice on
+stderr naming the replacement; the output on stdout is the same.
 
 Paths resolve at runtime from the gem location (a documented
 caveat for container / cross-filesystem setups).
 
 ## `rigor playground`
 
-Start the browser playground (a CodeMirror editor with
-real-time diagnostics). Requires the separate `rigor-playground`
-gem; if it is not installed the command prints an install hint
-and exits `64`.
+Start a local browser playground (a CodeMirror editor with real-time Rigor diagnostics and type inspection).
 
 ```sh
-rigor playground
+rigor playground [options]
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `--port=PORT` | Port to bind the playground HTTP server to (default: `9393`). |
+| `--no-open` | Do not automatically open the playground URL in the default browser on launch. |
+
+The playground requires the separate `rigor-playground` companion gem. When the gem is not installed in the active Ruby environment, the command prints an installation hint on stderr and exits `64` (`CLI::EXIT_USAGE`):
+
+```text
+rigor playground requires the rigor-playground gem.
+Install it with: gem install rigor-playground
 ```
 
+When installed, the command boots the local web server and opens an interactive browser playground where Ruby code can be written, edited, and analyzed with immediate feedback.
+
+Exit `0` on clean shutdown, `1` if server startup fails (e.g. port already in use), and `64` if `rigor-playground` is missing or on usage errors.
+
 ## `rigor skill`
 
 List or print the bundled Agent Skills shipped inside the
@@ -1092,24 +1383,27 @@ they now read as an unknown skill. Use the forms above.
 
 ## `rigor describe`
 
-Top-level alias for [`rigor skill describe`](#rigor-skill) — the
-onboarding entry point that recommends the next skill for this project.
-A bare `rigor describe` is the intuitive guess most users reach for
-first, so it is surfaced as its own command ([ADR-73](../adr/73-skill-driven-user-experience.md)
-§ WD2).
+Top-level alias for [`rigor skill describe`](#rigor-skill) — the onboarding entry point that assesses the project's state and recommends the next skill to run ([ADR-73](../adr/73-skill-driven-user-experience.md) § WD2).
 
 ```sh
-rigor describe
+rigor describe [--deep]
 ```
 
-It reports a presence-only project-state probe (does a `.rigor.yml`,
-`.rigor-baseline.yml`, `sig/` directory, or CI integration exist?) and a
-recommended next skill. It is read-only and side-effect-free — it never
-runs `rigor check`. Identical output to `rigor skill describe`.
+| Flag | Purpose |
+| --- | --- |
+| `--deep` | Run `rigor check` first and route the headline recommendation on the diagnostic results. |
+
+### Audit modes
+
+By default, `rigor describe` performs a presence-only probe checking for the existence of `.rigor.yml`, `.rigor-baseline.yml`, a `sig/` directory, and CI configurations. This default mode is read-only, fast, and side-effect-free — it never executes `rigor check` and never reads or writes `.rigor/cache`.
 
-`rigor describe --deep` forwards to
-[`rigor skill describe --deep`](#rigor-skill), which opts into running the
-check first — slow, and it writes the cache.
+Passing `--deep` opts into running `rigor check` before generating recommendations, routing based on analysis health:
+- **`rigor-doctor`**: Selected if the RBS environment builds with 0 classes or any `configuration-error` diagnostic is raised.
+- **`rigor-monkeypatch-resolve`**: Selected if at least one third of remaining error diagnostics stem from calls resolving to project-side reopened core or gem definitions (addressable via `pre_eval:`).
+- **`rigor-baseline-reduce`**: Selected when remaining error diagnostics exist.
+- **Presence-only recommendation**: Retained when the analysis is completely clean or when no configuration exists yet.
+
+Output is identical to `rigor skill describe`. Exit `0` on completion, or `64` on invalid options.
 
 ## `rigor docs`
 
@@ -1175,9 +1469,10 @@ Queued today:
 | --- | --- | --- |
 | `reject-unparseable-signatures` | severity | A broken RBS set **fails the run** instead of degrading it silently: an unparseable `.rbs` under `signature_paths:` (`rbs.coverage.quarantined-signature` → `error`), a declaration that collides on resolve and collapses the whole environment (`rbs.coverage.environment-build-failed` → `error`), and a duplicate method definition that collapses one class's method surface (`rbs.coverage.definition-build-failed` → `error`). |
 | `use-of-void-value` | severity | Using a value recovered from an author-declared `-> void` return in value context is reported as `static.value-use.void` (`warning`). |
+| `plugin-api-surface` | severity | In plugin source (a class that inherits `Rigor::Plugin::Base`), a call on a `Rigor::Plugin` interface value (a hook's `scope`, `scope.environment`, ...) to a member the interface does not declare is reported as `plugin.api-surface` (`warning`). |
 | `discovery-seeded-mutation-sites` | behaviour | [`rigor coverage --protection --mutation`](15-type-protection-coverage.md) measures against the same cross-file project discovery Tier 1 already uses — both when picking the sites and when deciding whether a breakage was caught — so a call on a project class declared in a *sibling* file is measured instead of dropped, and a breakage there can actually be caught. **Adds sites to the denominator, so the reported effectiveness ratio moves** — check it against any `--threshold` you pin in CI before adopting. |
 | `dependent-closure-kill-oracle` | behaviour | [`rigor coverage --protection --mutation`](15-type-protection-coverage.md) counts a breakage as caught when the diagnostic appears anywhere in the mutated file **or the files that depend on it**, instead of in the mutated file alone — so changing what a method returns counts as caught when the error lands in its callers. Can only **add** kills, so the ratio moves up or not at all; it costs about a third more wall time per mutant, and a ratio measured under it is not comparable with one measured without it. |
-| `effects-on-by-default` | behaviour | A project whose `.rigor.yml` carries no [`effects:`](03-configuration.md#effect-labels) key at all is treated as if it had written `effects: {}` — [effect collection](03-configuration.md#effect-labels), the `rigor effects` verbs' cache sharing, and `effects.check` all turn on with every sub-key at its default. Writing `effects: false` explicitly still opts out. **Scheduled to graduate at v0.4.0** ([ADR-103](../adr/103-effect-labels.md) § WD15) rather than at the next major — an owner ruling specific to this feature, ahead of the general v1.0.0 majors-only cadence below. |
+| `effects-on-by-default` | behaviour | A project whose `.rigor.yml` carries no [`effects:`](03-configuration.md#effect-labels) key at all is treated as if it had written `effects: {}` — [effect collection](03-configuration.md#effect-labels), the `rigor effects` verbs' cache sharing, and `effects.check` all turn on with every sub-key at its default. Writing `effects: false` explicitly still opts out. **Scheduled to graduate at v0.5.0** ([ADR-103](../adr/103-effect-labels.md) § WD15, moved from v0.4.0 by § WD18) rather than at the next major — an owner ruling specific to this feature, ahead of the general v1.0.0 majors-only cadence below. |
 
 Once a feature **graduates** — it becomes the default at a major
 ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD7)
@@ -1262,18 +1557,65 @@ Exits `1` when any check fails, `0` when all pass.
 
 ## `rigor upgrade`
 
-Migration command skeleton ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md)
-WD7). The real body lands when a concrete backwards-compatibility
-break gives it a target (e.g. re-running `baseline regenerate`
-against a strengthened default profile, surfacing renamed
-suppression ids, reporting `bleeding_edge:` graduations).
+Migration command skeleton for major version transitions and breaking changes ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD7).
 
 ```sh
 rigor upgrade
 ```
 
-Until then it prints the current version and notes that upgrade is
-queued. Exits `0`.
+### Design and future role
+
+The upgrade command is designed to automate project migrations when major version transitions or breaking changes occur:
+- **Baseline regeneration**: Re-running `rigor baseline regenerate` against strengthened default rules or profiles.
+- **Suppression updates**: Surfacing and updating renamed or deprecated inline `# rigor:disable` rules.
+- **Bleeding-edge consolidation**: Reporting and removing graduated features from `bleeding_edge:` configurations.
+
+### Current status
+
+Until a backward-incompatible release provides an active migration target, the command serves as a placeholder. It prints the current Rigor version and reports that migrations are queued:
+
+```text
+rigor upgrade: No migration target available yet (ADR-50 WD7, queued).
+Current version: <version>
+```
+
+Exit `0` on completion.
+
+## `rigor help`
+
+```sh
+rigor help                  # the command list
+rigor help <command>        # the same as `rigor <command> --help`
+rigor help --format=json    # every command, its flags and formats
+```
+
+`rigor help --format=json` prints the whole CLI surface as one JSON
+document, for tools and agents that would otherwise parse the help
+text:
+
+```json
+{ "schema_version": 1, "version": "…", "commands": [ … ] }
+```
+
+Each entry of `commands` has:
+
+| Key | Value |
+| --- | --- |
+| `name` | The command name. |
+| `summary` | The one-line description `rigor help` prints. |
+| `usage` | The usage line (`Usage: rigor …`). |
+| `flags` | The command's own switches, each `{ "name", "arg", "optional", "desc" }`. `arg` is the argument's name, `null` for a switch that takes none, and `optional` is `true` when the argument may be left out (`--bleeding-edge[=LIST]`). `--[no-]x` is listed as the two flags `--x` and `--no-x`. |
+| `formats` | The values the command's own `--format` accepts, empty when it has none. A command that only has subcommands with the flag (`baseline`) lists none here. |
+| `subcommands` | One `{ "name", "usage", "flags", "formats" }` object per subcommand (`baseline dump`, `effects check`, `skill describe`), with the same meaning as above and empty arrays where the subcommand has nothing to list. |
+| `mcp_tool` | The [MCP](10-mcp-server.md) tool that mirrors the command, or `null`. |
+
+The list covers every command above plus `help` and `version`. The
+text help is rendered from the same list.
+
+`rigor help <command>` takes one command: a second word
+(`rigor help baseline drift`) is refused with exit `64`, and an
+unknown command exits `64` too. Flags after the command name are
+ignored rather than parsed.
 
 ## Environment variables