rigortype 0.4.5 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4da9b991a97cd586806b416facb6dbf6c3a3b938c7c9433e330bc44c0757fdaf
-  data.tar.gz: 1167e8d91ccbc8740ac4094f67db82937bd3b374d2488a43e514f7922c7a98b1
+  metadata.gz: 983cf341f34d4407d6d06ab2b0bf50260f5b52a4f6e29c61ce0042123ab833cc
+  data.tar.gz: 17ea6b8b13033e507d0e7570913ab2609c830c9a5cfa706cfe055b6857d315f5
 SHA512:
-  metadata.gz: db2047e49879c399812704702d4064304bf4ac9be8fe25132cc65ac441e2962f7b8c45cf59371727dffaf52caab9accbfb7c8ea0abe1976f264a7a4506e46e6f
-  data.tar.gz: e426da15aeb714ab906df710946ae3b2c96b35509632b9c35efba289d303da519f58e3cd362a8b47c4ba8a9f883e54e657edeb3e09c1934b4cd542f119440678
+  metadata.gz: 0cd85174733cb61860d33f5636e81ac5d19972f9e6bd66fc6282d1aa7330735f8a57a067e1cfa81071632a45a0ca123f607be5b5bda7b3b32153fb8069328dfc
+  data.tar.gz: 64ecfde3bfe3eaef83ff44fa6ee1ca72bf6f353648c55a354726e60a87203012f907ce5406dc162289ff2a99056cf8b2962a79f636d5e7dd93cf16ec2b00e8d2

data/README.md

@@ -131,7 +131,7 @@ and [CI guide](https://rigor.typedduck.fail/manual/11-ci/).
 
 ```sh
 rigor check lib                 # find bugs (caches under .rigor/ — gitignore it)
-rigor init                      # drop a starter .rigor.yml
+rigor init                      # drop a starter .rigor.yml (suggests plugins from Gemfile.lock)
 rigor annotate lib/foo.rb       # reprint a file with inferred types in the margin
 rigor triage lib                # summarise diagnostics: distribution, hotspots
 rigor sig-gen --diff lib/foo.rb # emit RBS from inference (--write to save)
@@ -232,7 +232,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.4.5`** (2026-10-19) — on the
+Current release: **`v0.4.7`** (2026-11-03) — on the
 `0.4.x` line, continuing the evaluation era opened by `v0.2.0`, the first
 publicly-announced (general / evaluation) release. The line publishes
 an enumerated [compatibility surface](docs/compatibility.md) as a

data/data/gem_overlay/activesupport/core_ext.rbs

@@ -898,31 +898,34 @@ end
 
 class Hash[unchecked out K, unchecked out V]
   # `core_ext/hash/keys`
-  def symbolize_keys: () -> Hash[Symbol, V]
+  # `key.to_sym rescue key` keeps a key without `to_sym`, so no one key type is right: `Hash[untyped, V]` here,
+  # and with the plugin `dynamic_return` hook (#2433) maps each key member where it can.
+  def symbolize_keys: () -> Hash[untyped, V]
   def symbolize_keys!: () -> self
   def deep_symbolize_keys: () -> Hash[untyped, untyped]
-  def deep_symbolize_keys!: () -> self
+  def deep_symbolize_keys!: () -> Hash[untyped, untyped]
   def stringify_keys: () -> Hash[String, V]
-  def stringify_keys!: () -> self
+  def stringify_keys!: () -> Hash[String, V]
   def deep_stringify_keys: () -> Hash[untyped, untyped]
-  def deep_stringify_keys!: () -> self
+  def deep_stringify_keys!: () -> Hash[untyped, untyped]
   def assert_valid_keys: (*K | Array[K]) -> self
-  def deep_transform_keys: () { (K) -> K } -> Hash[K, untyped]
-  def deep_transform_keys!: () { (K) -> K } -> self
+  def deep_transform_keys: [X] () { (K) -> X } -> Hash[X, untyped]
+  def deep_transform_keys!: [X] () { (K) -> X } -> Hash[X, untyped]
   def deep_transform_values: () { (V) -> untyped } -> Hash[K, untyped]
-  def deep_transform_values!: () { (V) -> untyped } -> self
+  def deep_transform_values!: () { (V) -> untyped } -> Hash[K, untyped]
   # `alias_method`s of `symbolize_keys` / `symbolize_keys!`.
-  def to_options: () -> Hash[Symbol, V]
+  def to_options: () -> Hash[untyped, V]
   def to_options!: () -> self
 
   # `core_ext/hash/deep_dup`
   def deep_dup: () -> Hash[K, V]
 
-  # `core_ext/hash/deep_merge`
-  def deep_merge: (Hash[K, V]) -> Hash[K, V]
-                | (Hash[K, V]) { (K, V, V) -> V } -> Hash[K, V]
-  def deep_merge!: (Hash[K, V]) -> self
-                 | (Hash[K, V]) { (K, V, V) -> V } -> self
+  # `core_ext/hash/deep_merge` — the twin of the plugin's rows (#2424 review): the argument's keys join the
+  # receiver's, and a nested merge makes a value neither side declares, so values read `untyped`.
+  def deep_merge: [A, B] (Hash[A, B] other_hash) -> Hash[K | A, untyped]
+                | [A, B] (Hash[A, B] other_hash) { (K | A, untyped, untyped) -> untyped } -> Hash[K | A, untyped]
+  def deep_merge!: [A, B] (Hash[A, B] other_hash) -> Hash[K | A, untyped]
+                 | [A, B] (Hash[A, B] other_hash) { (K | A, untyped, untyped) -> untyped } -> Hash[K | A, untyped]
   # `other.is_a?(Hash)` — the hook `ActiveSupport::DeepMergeable` asks before
   # recursing into a value. `:nodoc:`, but public.
   def deep_merge?: (untyped other) -> bool

data/data/vendored_gem_sigs/bundler/bundler.rbs

@@ -150,7 +150,7 @@ module Bundler
     # `#initialize`, `#specs` — declared by `sig/shims/bundler.rbs` with the same types.
     def platforms: () -> Array[untyped]
     def sources: () -> Array[untyped]
-    def dependencies: () -> Array[Dependency]
+    def dependencies: () -> Hash[String, Dependency]
     def ruby_version: () -> untyped
     def bundler_version: () -> untyped
   end

data/data/vendored_gem_sigs/rubygems/rubygems_extras.rbs

@@ -112,8 +112,9 @@ class Gem::Specification
 
   # Instance-side surface widely used by bundler / rubygems
   # internals. `attr_accessor` mirrors the writer + reader pair
-  # so the survey's `.name=` / `.version=` / `.full_gem_path=` /
-  # `.loaded_from=` / `.post_install_message=` writes resolve too.
+  # so the survey's `.name=` / `.version=` / `.loaded_from=` /
+  # `.post_install_message=` writes resolve too. `.full_gem_path` is declared on `Gem::BasicSpecification`,
+  # which this class inherits from.
   def activate: () -> untyped
   def specification_version: () -> Integer
   def files: () -> Array[String]
@@ -127,13 +128,13 @@ class Gem::Specification
   # `#version`'s READER is declared by `sig/shims/rubygems.rbs` (`attr_reader version (): Version`);
   # only the writer is ours.
   def version=: (Gem::Version) -> Gem::Version
-  attr_accessor full_gem_path: String
   attr_accessor loaded_from: String?
   attr_accessor post_install_message: String?
 end
 
 class Gem::BasicSpecification
   def version: () -> Gem::Version
+  attr_accessor full_gem_path: String
   def executables: () -> Array[String]
   def name: () -> String
   def full_name: () -> String

data/docs/handbook/01-getting-started.md

@@ -283,8 +283,11 @@ If you used the [AI-assisted setup](#the-fast-path-let-an-ai-agent-set-it-up),
 the `rigor-project-init` skill already wrote one for you. To
 write a starter by hand, `rigor init` emits `.rigor.dist.yml`
 — the project default that gets committed, with `paths` and a
-`severity_profile` filled in, `target_ruby` commented out until
-you set it to your project's Ruby, and the rest commented out. That is all most projects need; the key
+`severity_profile` filled in. When your `Gemfile.lock` declares a
+gem a bundled plugin models, the template suggests that plugin
+under `plugins:`, commented out, for you to enable. `target_ruby`
+is commented out until you set it to your project's Ruby, and the
+rest is commented out too. That is all most projects need; the key
 reference, the JSON-schema editor integration, and `includes:`
 composition are in
 [Configuration](../manual/03-configuration.md).

data/docs/handbook/11-sig-gen.md

@@ -155,6 +155,11 @@ The `sig.skipped.*` reasons are:
   generic by an inline declaration and `sig/` does not declare
   it yet, or names its type parameters otherwise. See
   [Classes made generic inline](#classes-made-generic-inline).
+- `sig.skipped.generic-reopening` — the method's class, or one
+  it is nested in, is declared generic by loaded RBS with a
+  type parameter that has a bound or a default, and `sig/`
+  does not declare it. See
+  [Reopening a generic class](#reopening-a-generic-class).
 - `sig.skipped.inline-differs` — the method is declared
   inline and in `sig/`, and the two disagree. A refusal:
   `--write` and `--check` exit `1`. See
@@ -330,10 +335,34 @@ so a return inferred for the new line would describe
 parameters that are about to change. Delete the `sig/` member
 and re-run; sig-gen then writes the method afresh.
 
+### Reopening a generic class
+
+When your code reopens a class that loaded RBS declares
+generic — `class Array`, `class Hash`, a gem's class, or one
+your `sig/` declares — sig-gen writes the header with that
+declaration's type parameters: `class Array[unchecked out E]`.
+rbs rejects a reopening whose parameters differ, so a bare
+`class Array` would fail the class, and every class whose
+signature mentions it, with `GenericParameterMismatchError`.
+The members still say `untyped` for the element type, and a
+class whose name matches a copied parameter is written
+anchored (`::E`), since a bare `E` would name the parameter.
+
+The parameters are copied only when every one is plain: a
+name, a variance and `unchecked`. A bound or a default
+(`class Box[T < Comparable]`) is a type written for the
+declaring file's namespace and could mean another class
+where sig-gen writes, so that class's methods, and those of
+classes nested in it, are skipped as
+`sig.skipped.generic-reopening`. Declare the class in `sig/`
+with its parameters and sig-gen writes the members into that
+declaration. A file that already declares the class keeps its
+own header.
+
 ### Classes made generic inline
 
-sig-gen does not write a class's type parameters yet. A class
-declared generic inline (`# @rbs generic T`) is therefore not
+sig-gen does not copy type parameters from an inline
+declaration. A class declared generic inline (`# @rbs generic T`) is therefore not
 opened in `sig/`: a header without its parameters would make
 rbs reject the class, and every class whose signature mentions
 it, with `GenericParameterMismatchError`. Its methods, and
@@ -538,8 +567,17 @@ overrides the method with the other one is not reported as
 widening the return. A body that returns only `nil` keeps
 the `untyped`: it is the shape of a template method a
 subclass fills in, and `-> nil` would make every override
-that returns a value a widening. `nil` inside a union and a
-computed `Float` are proposed as they are. An `untyped` that
+that returns a value a widening. A literal inside a tuple, a
+record or a type argument is widened the same way while the
+shape stays (`-> [1, "a"]` becomes `-> [Integer, String]`,
+`-> { a: 1 }` becomes `-> { a: Integer }`); of the generic
+types, only the arguments of `Array`, `Hash`, `Set`, `Range`
+and `Enumerator` are widened. `nil` inside a union or a shape
+and a computed `Float` are proposed as they are. When the
+method also carries an inline `# @rbs` annotation for its
+parameters only, a return holding a literal that would be
+widened, nested or not, is not proposed at all and the
+`untyped` stays. An `untyped` that
 only the inline reader synthesizes for a `def` you did not
 annotate keeps the literal, as does a method no `.rbs`
 declares — the literal is still the strictest thing the body
@@ -617,6 +655,24 @@ list is the current state):
   are recognised as user-authored and never produce a
   duplicate `def` insertion.
 
+Two rules shape the class declarations and type names around
+those methods:
+
+- **A subclass of a core or stdlib class** is declared even
+  when it has no method of its own to emit, so a method
+  returning one resolves: `class MyHash < Hash; end` is
+  written `class MyHash < ::Hash[untyped, untyped]`. The
+  declaration goes into the file written for its source file,
+  so it appears only when that source file has at least one
+  method to emit. A class some signature already declares is
+  left to that declaration.
+- **A type name a namespace shadows** is written with a
+  leading `::`. Inside a `module Foo` that declares a
+  `Foo::Set`, a method returning a core `Set` is written
+  `-> ::Set[untyped]`, because RBS would read a bare `Set`
+  there as `Foo::Set`. Where nothing shadows the name, it is
+  written bare as before.
+
 Method shapes the generator does **not** cover yet:
 
 - `define_method(:name) { ... }`.
@@ -634,7 +690,7 @@ two are wired today, one is reserved.
 | Policy | Behaviour |
 | --- | --- |
 | `untyped` (default) | Every parameter is spelled `untyped`. No inference-derived parameter contract is imposed on future callers. The user retains complete authorship over parameter typing. |
-| `observed` | Collect argument types from every call site under `--observe=PATH...` (defaults to the configured `test_paths:`, or whichever of `spec/` and `test/` exist), union per parameter position, erase to RBS, emit the union. With no test root to observe, or a declared root that does not exist or is not read, sig-gen says so on stderr, and `--format=json` carries the same fact in a top-level `observation` key (below). |
+| `observed` | Collect argument types from every call site under `--observe=PATH...` (defaults to the configured `test_paths:`, or whichever of `spec/` and `test/` exist), union per parameter position, erase to RBS, emit the union. A literal argument is widened to its class first, so `"hello"` proposes `String` (#2254). With no test root to observe, or a declared root that does not exist or is not read, sig-gen says so on stderr, and `--format=json` carries the same fact in a top-level `observation` key (below). |
 | `observed-strict` | Reserved. Will additionally widen to capability roles (`_ToStr`, `_ToS`, …) once the role catalog ships. Currently rejected with a usage error. |
 
 Under `--params=observed`, the `--print` / `--diff` JSON payload gains

data/docs/handbook/appendix-phpstan.md

@@ -20,7 +20,7 @@ unchanged. This appendix maps the vocabulary.
 | Default behaviour | Inference, fall back silent | Inference, fall back silent |
 | "Levels" | 0 – 10 (numeric) | `lenient` / `balanced` / `strict` (named) |
 | Per-rule control | `ignoreErrors:` regex, level demotion | `disable:`, `severity_overrides:` |
-| Baseline | `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) / `rigor.baseline.json` (ad-hoc) |
+| Baseline | `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) / `rigor-check.json` (ad-hoc) |
 | Stub format | PHP stub files | RBS files |
 | Custom narrowing | Type-Specifying Extensions | Plugins (Chapter 9) |
 | Custom return shape | Dynamic Return Type Extensions | Plugin `dynamic_return` |
@@ -140,10 +140,10 @@ severity controls, and includes.
 | `ignoreErrors:` (regex / pattern) | `disable:` (rule identifier or wildcard) |
 | `parameters: ignoreErrors:` per-path | `# rigor:disable-file <rule>` at the file head |
 | `includes:` | `includes:` |
-| `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) — or `rigor.baseline.json` (ad-hoc) |
-| `phpstan analyse --generate-baseline` | `rigor baseline generate` (managed) — or `rigor check --format=json > rigor.baseline.json` (ad-hoc) |
+| `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) — or `rigor-check.json` (ad-hoc) |
+| `phpstan analyse --generate-baseline` | `rigor baseline generate` (managed) — or `rigor check --format=json > rigor-check.json` (ad-hoc) |
 | `phpstan analyse` | `rigor check` |
-| `phpstan analyse --baseline` | `rigor check` with `baseline: .rigor-baseline.yml` configured (managed) — or `rigor diff rigor.baseline.json` (ad-hoc) |
+| `phpstan analyse --baseline` | `rigor check` with `baseline: .rigor-baseline.yml` configured (managed) — or `rigor diff rigor-check.json` (ad-hoc) |
 | Path resolution: relative to declaring file | Path resolution: relative to declaring file (same rule). |
 
 Rigor has two baseline mechanisms: a **managed** baseline

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
@@ -28,15 +30,25 @@ rigor check [paths...]
 `paths` are files or directories; when omitted, Rigor checks
 the `paths:` list from the configuration file.
 
+Only the files you name are reported on, but Rigor reads the
+declarations in the configured `paths:` too, so a file resolves a
+class or constant that another file declares. A file outside
+`paths:` also reads the files it loads with a literal
+`require_relative "..."`, and the files those load in turn. Their
+classes, modules and constants resolve and their methods count as
+defined, but Rigor does not infer what those methods return or
+check their arity, since another file may redefine them.
+
 | Option | Effect |
 | --- | --- |
-| `--config=PATH` | Use a specific config file instead of auto-discovery. |
+| `--config=PATH` | Use a specific config file instead of auto-discovery. A path that does not exist is an error (exit 64), not a run with the defaults. |
 | `--format=FORMAT` | Output format. Default `text`. Also `json` (structured stream), plus the CI-native renderings `sarif`, `github`, `gitlab`, `checkstyle`, `junit`, and `teamcity` — see [Running Rigor in CI](11-ci.md). |
 | `--no-ci-detect` | Disable CI auto-detection — by default `text` output also emits the running CI's native annotations / hint (`RIGOR_CI_DETECT=0` does the same). See [Running Rigor in CI § auto-detection](11-ci.md). |
 | `--explain` | Surface fail-soft fallback events as `info` diagnostics. |
 | `--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). Used in CI to guarantee `--incremental` never serves a stale result. |
+| `--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 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. |
@@ -50,7 +62,7 @@ the `paths:` list from the configuration file.
 | `--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
@@ -60,12 +72,16 @@ that want the stricter reading.
 ### Editor mode scope
 
 `--tmp-file` / `--instead-of` on their own analyse **only** the
-buffer's file: fast, and blind to what the unsaved edit does to the
+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.
 
@@ -79,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
@@ -89,12 +110,41 @@ 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`
 
@@ -111,10 +161,16 @@ 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
+colorizer). `--format=json` emits an `{ "schema_version": 1, "annotations": { line => type } }`
+document instead of the annotated source. Exit `1` on a parse error or a
 missing file.
 
+## 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`
 
 Print inferred types at one or more source positions.
@@ -136,7 +192,25 @@ 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
+`rigor check --incremental` has left a snapshot for the project:
+`type-of` folds the cross-file declarations from that snapshot's
+per-file bundles, re-reading any file whose bytes changed since,
+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. 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
@@ -162,7 +236,9 @@ and is probed as plain Ruby, parse error included.
 
 The four probe commands — `type-of`, `type-scan`, `trace` and
 `annotate` — build their environment fresh on every invocation
-and never read or write the persistent cache. That is why none
+and never read or write the persistent cache (apart from the
+read-only snapshot lookup `type-of` makes for the project's
+declarations, above). That is why none
 of them takes `--no-cache`: the flag would have nothing to skip.
 A probe therefore types against the environment `rigor check
 --no-cache` analyses with. The environment a cached (default)
@@ -494,11 +570,11 @@ a severity or a suppression line.
 
 ## `rigor diff`
 
-Compare the current diagnostics against a saved baseline JSON
-and report only what is new.
+Compare the current diagnostics against a saved
+`rigor check --format=json` result and report only what is new.
 
 ```sh
-rigor diff [options] <baseline.json> [paths...]
+rigor diff [options] <rigor-check.json> [paths...]
 ```
 
 `--current=PATH` compares against a saved diagnostics JSON
@@ -532,12 +608,30 @@ rigor sig-gen [paths]
 | `--no-cache` | Do not read or write the analysis cache. Only effect collection uses it. |
 | `--format=text\|json` | Output format. |
 
+A `paths` argument that does not exist, or is neither a directory nor a `.rb` file, is reported the way
+`rigor check` reports it: on stderr as `path:1:1: error: …`, or under `diagnostics` in `--print` and `--diff`
+JSON output. When no argument is readable this exits `1`, under every mode, `--write` and `--check` included.
+The configured default `paths:` count too, so `paths: [lib]` with no `lib/` directory exits `1`. A `--config`
+that names no file, is a directory, or is empty is a usage error and exits `64`.
+
 `--print`, `--diff`, `--write` and `--check` are mutually exclusive.
 `--check` fails exactly when `--write` would create, change or
 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).
@@ -581,7 +675,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
@@ -601,10 +701,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`
 
@@ -628,6 +738,12 @@ 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.
 
+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
@@ -640,7 +756,7 @@ rigor triage [paths]
 
 `--top=N` sets the hotspot count (default 10); `--hints-only`,
 `--selectors-only`, and `--no-hints` select which sections print.
-`triage` is advisory and always exits `0` — it never gates a build.
+`triage` is advisory and exits `0` once it runs — it never gates a build; a usage error exits `64`.
 
 By default the distribution, selectors, and hotspots sections count
 only the **actionable** diagnostics (`error` + `warning`). `info`
@@ -946,6 +1062,11 @@ loaded from (a `path:` line in text, a `"path"` key in JSON), so
 if a stale installed gem is shadowing a newer checkout's bundled
 plugin copy the mismatch is visible at a glance.
 
+A plugin that declares `per_invocation_classes:` or
+`per_invocation_non_action_macros:` ([ADR-125](../adr/125-per-invocation-classes.md))
+also gets a line for each in text, and a key in JSON (an empty
+array when it declares none).
+
 ```sh
 rigor plugins [--format=text|json] [--strict] [--capabilities] [--config=PATH]
 ```
@@ -973,15 +1094,22 @@ 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).
@@ -1237,6 +1365,42 @@ rigor upgrade
 Until then it prints the current version and notes that upgrade is
 queued. Exits `0`.
 
+## `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
 
 Most behaviour is driven by flags and `.rigor.yml`; a few
@@ -1268,8 +1432,9 @@ diagnostics about Rigor's own inference cutoffs and memory — see
 | `64` | Usage error — unknown command, bad flag, malformed argument, or a value in `.rigor.yml` the loader cannot proceed on. |
 | `70` | Internal fatal error — `SystemStackError` or `NoMemoryError` inside the analysis; Rigor could not finish the run, so its report on disk is empty rather than clean. |
 
-`rigor triage` is the exception: it is advisory and always
-exits `0`.
+`rigor triage` is the exception: it is advisory and exits `0`
+whenever it runs to completion. A usage error, such as a
+`--config` that names no file, still exits `64`.
 
 A configuration mistake prints one `rigor:` line naming the key
 and nothing else — no backtrace, on every command: