rigortype 0.2.0 → 0.2.2

data/docs/manual/03-configuration.md

@@ -0,0 +1,152 @@
+# Configuration
+
+Rigor reads a single YAML configuration file from the project
+root. `rigor init` writes a starter one.
+
+## Discovery and precedence
+
+With no `--config` flag, Rigor looks for, in order:
+
+1. `.rigor.yml`
+2. `.rigor.dist.yml`
+
+The **first file found wins** — the two are not merged. The
+convention is to commit `.rigor.dist.yml` as the shared
+project config and let an individual developer drop an
+(un-tracked) `.rigor.yml` to override it locally.
+
+To *layer* configs rather than replace, a config file can name
+a base with `includes:` (recursive). `--config=PATH` bypasses
+discovery entirely.
+
+All relative paths in a config file resolve against that
+file's own directory.
+
+## A minimal config
+
+```yaml
+target_ruby: "4.0"
+paths:
+  - lib
+plugins: []
+cache:
+  path: .rigor/cache
+```
+
+## Key reference
+
+### Sources and target
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `target_ruby` | String | `"4.0"` | The Ruby version *your* project runs — `"X.Y"`, `"X.Y.Z"`, or `"latest"`. Independent of the Ruby Rigor itself runs on. |
+| `paths` | Array | `["lib"]` | Directories or files to analyse. |
+| `exclude` | Array | `[]` | Glob patterns to skip. `vendor/bundle`, `.bundle`, and `node_modules` are always excluded. |
+| `includes` | Array | `[]` | Other config files to layer underneath this one. |
+| `fold_platform_specific_paths` | Boolean | `false` | Resolve Ruby-version-conditional load paths when discovering sources. |
+
+### Type sources
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `libraries` | Array | `[]` | Standard-library / gem names whose bundled RBS to load. |
+| `signature_paths` | Array | `nil` | Extra directories of `.rbs` files. Relative entries resolve against the config file's directory. |
+| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches. |
+| `plugins` | Array | `[]` | Plugins to activate — see [Using plugins](07-plugins.md). |
+
+### Config validation warnings
+
+`rigor check` warns on STDERR when a configured value silently resolves to
+nothing — the class of mistake where a typo loads zero signatures (or
+leaves a suppression inert) and the only symptom is downstream and
+confusing. A missing RBS path, for instance, turns every call into the
+types it was meant to describe into a high-confidence
+`call.undefined-method`, so a one-character mistake can look like hundreds
+of real type errors. The audit covers:
+
+```
+rigor: signature_paths: "/path/to/sig" does not exist (no signatures loaded from it)
+rigor: signature_paths: "/path/to/sig" matched 0 signature files
+rigor: libraries: "csb" is not an available RBS library (no signatures loaded from it)
+rigor: disable: "call.undefined-methdo" is not a recognized rule id; the suppression has no effect
+rigor: severity_overrides: "flow.bogus" is not a recognized rule id; the override has no effect
+rigor: bundler.lockfile: "./missing/Gemfile.lock" does not exist
+```
+
+These are warnings, not errors — partial or optional bundles and
+forward-looking config are valid setups. The audit only fires on explicit,
+working-setup-safe signals: an unset default (auto-detected `<root>/sig`,
+auto-detected bundle) is never warned about, and a `disable:` /
+`severity_overrides:` token under a *plugin* family (`rspec.…`,
+`rbs_extended.…`) is left alone, since its rule id cannot be enumerated
+statically and may resolve at run time. The same findings appear in the
+`--format=json` payload under `config_warnings` (each tagged with a
+`kind`), so CI can assert on them.
+
+### Diagnostics
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `disable` | Array | `[]` | Rule IDs or families to suppress project-wide. |
+| `severity_profile` | String | `"balanced"` | `lenient`, `balanced`, or `strict` — see [Diagnostics](04-diagnostics.md). |
+| `severity_overrides` | Hash | `{}` | Per-rule / per-family severity, e.g. `{ call: warning, flow.always-truthy-condition: off }`. |
+| `baseline` | String / `false` | `nil` | Path to a `.rigor-baseline.yml`, or `false` to disable an inherited one. See [Baselines](06-baseline.md). |
+| `bleeding_edge` | Boolean / Array / Hash | `false` | Adopt the next major's queued diagnostic disciplines early ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD2). `false` adopts none; `true` adopts the whole overlay; a list of feature ids adopts only those; `{ all: true, except: [ids] }` adopts all but the named. Orthogonal to `severity_profile`. Override it for a single run with [`rigor check --bleeding-edge[=ids]`](02-cli-reference.md#rigor-check) / `--no-bleeding-edge`. Inspect with [`rigor show-bleedingedge`](02-cli-reference.md#rigor-show-bleedingedge). The overlay is empty in this release, so every form is currently a no-op. |
+
+### Dependency RBS discovery
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `bundler.auto_detect` | Boolean | `true` | Auto-detect the Bundler install path and lockfile. |
+| `bundler.bundle_path` | String | `nil` | Explicit Bundler install root. |
+| `bundler.lockfile` | String | `nil` | Explicit `Gemfile.lock` path. |
+
+`bundler.auto_detect` looks for the Bundler install root in project-local
+locations first — the `path` recorded in `<project>/.bundle/config`, then a
+`<project>/vendor/bundle/` directory — and falls back to a user-global
+`bundle config set --global path …` (`~/.bundle/config`) when the project
+has no in-tree bundle.
+
+It deliberately does **not** read `BUNDLE_PATH` from rigor's own
+environment, and it cannot reach gems installed at the *default* shared
+location (the active Ruby's `GEM_HOME`, when no `path` is configured):
+rigor runs in its own isolated Ruby and reads your project as data
+([ADR-27](../adr/27-tool-distribution-model.md)), so it does not know the
+project Ruby's gem home without running your toolchain. If `rigor check`'s
+`--stats` shows gems whose RBS it could not find, point it at the bundle
+explicitly with `bundler.bundle_path:`, or supply signatures another way:
+`rbs collection install` (auto-discovered) or `dependencies.source_inference:`.
+| `rbs_collection.auto_detect` | Boolean | `true` | Auto-discover `rbs_collection.lock.yaml`. |
+| `rbs_collection.lockfile` | String | `nil` | Explicit `rbs_collection.lock.yaml` path. |
+| `dependencies.source_inference` | Array | `[]` | Per-gem source-inference modes (ADR-10). |
+| `dependencies.budget_per_gem` | Integer | `5000` | Per-gem source-walk cap, counted in **method definitions** (not time): the walker stops harvesting a gem's catalog once it reaches this many `def`s, then emits `dynamic.dependency-source.budget-exceeded` and degrades the rest to `Dynamic[top]`. Range 1250–20000. |
+| `dependencies.budget_overrun_strategy` | String | `"walker_cap"` | What happens to calls on a gem that hit `budget_per_gem` (ADR-10 § 5b). `walker_cap` (default) lets methods past the cap fall through to the engine's normal user-class resolution. `dependency_silence` instead resolves any call on a class from a budget-exceeded gem to `Dynamic[top]`, silencing `call.undefined-method` on that gem's unrecorded surface at the cost of weaker static checking there. |
+
+### Execution
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `cache.path` | String | `.rigor/cache` | Persistent cache directory. See [Caching](12-caching.md). |
+| `cache.max_bytes` | Integer or `null` | `268435456` (256 MB) | LRU eviction cap for the cache directory; `null` disables eviction. See [Caching § Size and eviction](12-caching.md#size-and-eviction). |
+| `parallel.workers` | Integer | `0` | Parallel worker processes for per-file analysis (fork-based pool today; ADR-15); `0` is sequential. CLI `--workers` and `RIGOR_RACTOR_WORKERS` take precedence. |
+| `plugins_io.network` | String | `"disabled"` | Plugin network policy — `disabled` or `allowlist`. |
+| `plugins_io.allowed_paths` | Array | `[]` | Filesystem paths plugins may read. |
+| `plugins_io.allowed_url_hosts` | Array | `[]` | URL hosts plugins may fetch from when `network: allowlist`. |
+
+## A worked example
+
+```yaml
+target_ruby: "3.4"
+paths:
+  - lib
+  - app
+exclude:
+  - "**/*_pb.rb"
+plugins:
+  - rigor-activerecord
+  - rigor-rspec
+severity_profile: balanced
+severity_overrides:
+  flow.dead-assignment: warning
+baseline: .rigor-baseline.yml
+```

data/docs/manual/04-diagnostics.md

@@ -0,0 +1,206 @@
+# Diagnostics
+
+When `rigor check` finds a problem it reports a **diagnostic**:
+a file, a line and column, a severity, a rule ID, and a
+message. This page is the reference for the rule catalogue,
+the severity model, and suppression. For the *reasoning*
+behind each rule, see
+[handbook chapter 8](../handbook/08-understanding-errors.md).
+
+## Rule IDs
+
+Every rule has a two-segment `family.rule` identifier:
+
+| Family | Covers |
+| --- | --- |
+| `call` | Call sites — undefined methods, arity, argument types, nil receivers. |
+| `flow` | Control-flow proofs — always-raises, dead branches, constant conditions. |
+| `def` | Method definitions — return types, ivar writes, visibility. |
+| `assert` | `assert_type` checks. |
+| `dump` | `dump_type` notices. |
+
+`rigor explain <rule>` prints the full catalogue entry for any
+ID; `rigor explain` with no argument lists them all.
+
+### Catalogue
+
+Each rule has a stable per-rule anchor on this page
+(`#rule-<family>-<name>`, dots written as dashes) — the
+`documentation_url` field in `--format json` and `rigor explain`'s
+`Documentation:` line both point here. The `Evidence` column is
+Rigor's confidence that a firing is a true positive (see
+[Evidence tier](#evidence-tier) below).
+
+| Rule | Fires when | Evidence |
+| --- | --- | --- |
+| <a id="rule-call-undefined-method"></a>`call.undefined-method` | The method is not defined on the receiver's statically known class. | high |
+| <a id="rule-call-self-undefined-method"></a>`call.self-undefined-method` | An implicit-self call (no receiver) resolves to no method on a confidently-closed standalone class. Ships `:off`; opt in via `severity_overrides`. | low |
+| <a id="rule-call-wrong-arity"></a>`call.wrong-arity` | The positional-argument count matches no signature. | high |
+| <a id="rule-call-argument-type-mismatch"></a>`call.argument-type-mismatch` | An argument's type provably violates the parameter contract. | high |
+| <a id="rule-call-possible-nil-receiver"></a>`call.possible-nil-receiver` | The receiver is `T \| nil` and the method is not defined on `NilClass`. | high |
+| <a id="rule-call-unresolved-toplevel"></a>`call.unresolved-toplevel` | A top-level implicit-self call resolves against no same-file `def`, `pre_eval:` patch, or `Kernel` / `Object` method. | low |
+| <a id="rule-flow-always-raises"></a>`flow.always-raises` | The expression provably raises on every reachable path. | high |
+| <a id="rule-flow-unreachable-branch"></a>`flow.unreachable-branch` | An `if` / `unless` / ternary branch is statically dead. | high |
+| <a id="rule-flow-always-truthy-condition"></a>`flow.always-truthy-condition` | A condition is provably always truthy or always falsey. | medium |
+| <a id="rule-flow-dead-assignment"></a>`flow.dead-assignment` | A local is written but never read in the same method. | medium |
+| <a id="rule-flow-unreachable-clause"></a>`flow.unreachable-clause` | A `case`/`when` or `case`/`in` clause is statically dead — its subject type is disjoint with the pattern, or a prior clause already exhausted the subject. | medium |
+| <a id="rule-def-return-type-mismatch"></a>`def.return-type-mismatch` | The method body's result violates its declared RBS return type. | medium |
+| <a id="rule-def-ivar-write-mismatch"></a>`def.ivar-write-mismatch` | An instance variable is written with a type disagreeing with its first write. | high |
+| <a id="rule-def-method-visibility-mismatch"></a>`def.method-visibility-mismatch` | An explicit-receiver call reaches a private method. | high |
+| <a id="rule-def-override-visibility-reduced"></a>`def.override-visibility-reduced` | An override reduces the visibility it inherits from a project-defined ancestor. | high |
+| <a id="rule-def-override-return-widened"></a>`def.override-return-widened` | An override's declared return type widens the inherited return (covariance). | high |
+| <a id="rule-def-override-param-narrowed"></a>`def.override-param-narrowed` | An override narrows an inherited parameter type (contravariance). | high |
+| <a id="rule-rbs_extended-unsatisfied-conformance"></a>`rbs_extended.unsatisfied-conformance` | A class declares `%a{rigor:v1:conforms-to _Interface}` in its RBS but is missing a method the interface requires. Presence-based: only definitively-absent required methods fire. | — |
+| <a id="rule-assert-type-mismatch"></a>`assert.type-mismatch` | An `assert_type` expectation does not match the inferred type. | high |
+| <a id="rule-dump-type"></a>`dump.type` | A `dump_type` call — informational, prints the inferred type. | — |
+
+Plugins may contribute further families and rules; `rigor
+explain` lists whatever the active configuration loads.
+
+## Evidence tier
+
+Every rule in the catalogue above carries an **evidence tier** —
+Rigor's own confidence that a firing is a *true positive*, derived
+from the rule's firing gates. It is orthogonal to severity (impact) and to
+the severity profile: the tier never changes whether a diagnostic
+surfaces, it only routes attention.
+
+| Tier | Meaning |
+| --- | --- |
+| `high` | Fires only on a concrete, statically-known type with no metaprogramming escape. Rigor's false-positive discipline has already filtered the uncertain cases, so a firing is almost always a real problem — a consumer can act on it (or a downstream classifier can trust it) without cross-checking another tool. |
+| `medium` | Rests on a flow- or inference-level proof that inherits a documented false-positive envelope (loop / mutation / RBS-strictness modelling gaps, narrowed by the rule's *does not fire when* list). Usually right, but not literal-provable. |
+| `low` | A resolution- or coverage-gap signal: a firing frequently reflects context the analyzer cannot see (an unanalyzed file, a metaprogramming patch) rather than a definite bug. Treat as "review this" — e.g. route `call.unresolved-toplevel` to a `pre_eval:` decision. |
+
+Informational rules (`dump.type`) carry no tier. The per-rule tier
+is the single source of truth in the rule catalogue — read it with
+`rigor explain <rule>` or `rigor explain --format json`, and it is
+echoed on each diagnostic in `rigor check --format json` (below).
+
+## Severity profiles
+
+Each rule emits with an authored severity, then a **profile**
+re-stamps it for the run. Three profiles, set with the
+`severity_profile:` config key:
+
+| Profile | Stance |
+| --- | --- |
+| `lenient` | Only proven diagnostics are errors; uncertain ones drop to `warning` / `info`. For incremental adoption on legacy code. |
+| `balanced` *(default)* | Most rules `error`; `dump.type` `info`; uncertain rules `warning`. |
+| `strict` | Every rule is an `error`. CI-friendly. |
+
+For finer control, `severity_overrides:` maps a rule ID or a
+family to one of `error`, `warning`, `info`, or `off`:
+
+```yaml
+severity_profile: balanced
+severity_overrides:
+  flow.always-truthy-condition: off
+  call: warning
+```
+
+A rule-specific override beats a family override.
+
+## Machine-readable output (`--format json`)
+
+`rigor check --format json` emits the diagnostics as a JSON
+document for editors, CI, and AI agents. Each diagnostic is an
+object with **stable, structured fields** — so a consumer filters
+and groups on them directly and **never parses the human-readable
+`message`** (the wording is presentation, not contract, and may be
+reworded in a minor release):
+
+| Field | Present | Meaning |
+| --- | --- | --- |
+| `path` / `line` / `column` | always | Location (1-based line and column). |
+| `severity` | always | `error` / `warning` / `info`. |
+| `rule` | always (`null` for parse / internal errors) | The `family.rule` ID. |
+| `source_family` | always | `builtin`, `rbs_extended`, `generated.*`, or `plugin.<id>`. |
+| `message` | always | Human-readable text — *presentation, not contract*. |
+| `receiver_type` | when the rule has a receiver | The called receiver's displayed type (`String`, `Array[User]`, …). |
+| `method_name` | when the rule has a method | The called / defined method name. |
+| `project_definition_site` | `call.undefined-method` monkey-patch case | `path:line` where the project itself defines the method (ADR-17). |
+| `evidence_tier` | built-in rules with a tier | `high` / `medium` / `low` — Rigor's confidence the firing is a true positive ([Evidence tier](#evidence-tier)). |
+| `documentation_url` | built-in rules | A stable URL to the rule's entry in this catalogue. |
+
+`evidence_tier` lets a consumer prioritise without re-deriving
+confidence — e.g. surface only `high` firings in a strict CI gate,
+or route `low` firings to a human review queue:
+
+```sh
+# only the high-confidence diagnostics
+rigor check --format json \
+  | jq '[.diagnostics[] | select(.evidence_tier == "high")]'
+```
+
+### Coverage block (`--coverage`)
+
+`rigor check --coverage` adds a top-level `coverage` object so a single
+run reports both *what fired* and *how much of the analyzed surface
+Rigor could type* — useful when a large diagnostic count raises the
+question "did it analyze all my files, or only a few?". The block
+mirrors the `summary` of `rigor check`'s sibling
+[`rigor coverage`](02-cli-reference.md#rigor-coverage) (same
+precision-tier vocabulary), plus `scan_files`:
+
+```jsonc
+"coverage": {
+  "scan_files":            203,
+  "parse_errors":          0,
+  "expressions_typed":     18394,
+  "precise_count":         9847,
+  "precise_ratio":         0.535,
+  "dynamic_opaque_count":  8547,
+  "dynamic_opaque_ratio":  0.465
+}
+```
+
+It is **off by default** — computing it is a second precision pass over
+the analyzed files — so the default check path's cost is unchanged. In
+text mode `--coverage` prints a one-line summary instead. For the full
+per-file / per-tier breakdown, run `rigor coverage` directly.
+
+The `receiver_type` / `method_name` pair is populated by the
+call-family rules and the method-level `def.*` rules. Group a run
+by the called class and method with `jq`, no message parsing:
+
+```sh
+# every diagnostic that names a method, as {receiver, method, rule}
+rigor check --format json \
+  | jq '[.diagnostics[] | select(.method_name) | {receiver: .receiver_type, method: .method_name, rule}]'
+```
+
+The `check` stream is **faithful per-site** — a literal receiver
+reports its literal type (`"hi"`, `42`). For the **aggregated**
+view — counts per class/method across the whole run, with literal
+receivers folded to their class — use
+[`rigor triage`](02-cli-reference.md)'s `selectors` section.
+
+## Suppressing a diagnostic
+
+Three layers, from narrowest to broadest.
+
+**In-source, one line.** A trailing comment suppresses the
+named rules on that line:
+
+```ruby
+config.merge(extra)  # rigor:disable call.undefined-method
+```
+
+It accepts qualified IDs, family wildcards (`call`), a
+comma- or space-separated list, or `all`.
+
+**In-source, whole file.** `# rigor:disable-file <rules>`
+anywhere in a file suppresses those rules for every line;
+`# rigor:disable-file all` silences the file.
+
+**Project-wide.** The `disable:` config key turns rules off
+across the whole run:
+
+```yaml
+disable:
+  - flow.dead-assignment
+```
+
+For a *known backlog* you want to keep visible but not fail
+on, prefer a [baseline](06-baseline.md) over a blanket
+`disable:` — `disable:` also hides any new occurrences.

data/docs/manual/05-inspecting-types.md

@@ -0,0 +1,109 @@
+# Inspecting inferred types
+
+Rigor's analysis is invisible by default — it only speaks up to
+report a diagnostic. When you want to *see* what type the
+engine assigns an expression, there are four tools: two source
+helpers and two CLI commands.
+
+## `dump_type` — print a type from source
+
+`dump_type(expr)` makes Rigor emit an `info`-severity
+`dump.type` diagnostic showing the inferred type of `expr`. At
+runtime it is a no-op that returns `expr` unchanged, so it is
+safe to leave in or sprinkle freely while debugging.
+
+```ruby
+require "rigor/testing"
+include Rigor::Testing
+
+dump_type(1 + 2)   # rigor reports: dump.type — Constant<3>
+```
+
+Rigor recognises the call when it is written as `dump_type(…)`
+after `include Rigor::Testing`, or fully qualified as
+`Rigor::Testing.dump_type(…)` / `Rigor.dump_type(…)`.
+
+## `assert_type` — pin a type in source
+
+`assert_type("TypeString", expr)` compares `expr`'s inferred
+type against the literal type string. On a mismatch Rigor
+emits an `error`-severity `assert.type-mismatch` diagnostic; on
+a match it stays silent. Like `dump_type`, it returns `expr`
+unchanged at runtime.
+
+```ruby
+assert_type("Constant<3>", 1 + 2)   # silent — matches
+assert_type("Integer",     1 + 2)   # assert.type-mismatch
+```
+
+The type string is matched against the engine's short display
+form. `assert_type` is how the handbook's examples stay honest,
+and it doubles as a regression check you can keep in a
+project's own test sources.
+
+## `rigor annotate` — types in the margin
+
+`rigor annotate FILE` reprints a whole file with every line
+tagged by the type of the expression it evaluates to, as a
+trailing `#=>` comment (the xmpfilter / seeing_is_believing
+convention):
+
+```ruby
+two = 1 + 1   #=> 2
+name = gets   #=> String | nil
+```
+
+It is the fastest way to survey a file. The annotation is
+idempotent — re-running replaces the previous `#=>` comment
+(including hand-written ones, and the pre-v0.2.0
+`#=> dump_type:` spelling) rather than stacking it. Output is
+syntax-highlighted for a tty — through
+[`bat`](https://github.com/sharkdp/bat) when it is found on
+`PATH` (`--no-bat` opts out), otherwise via the built-in
+colorizer; `--no-color` (and the `NO_COLOR` environment
+variable) disable the colour.
+
+## `rigor type-of` — one position
+
+When you only need one expression's type — typically while
+chasing down why a diagnostic did or did not fire — query a
+single position:
+
+```sh
+rigor type-of lib/example.rb:12:8
+```
+
+`--format=json` emits a machine-readable result for tooling.
+This is the same query the editor integration answers on
+hover.
+
+## `rigor trace` — watch the inference happen
+
+Where `annotate` and `type-of` show the *answer*, `rigor trace
+FILE` shows the *derivation*: it re-runs the engine over the
+file and replays the recorded inference events as a
+step-through terminal animation — the moment a local enters the
+scope, the moment two branch types merge into a union, the
+moment a method call resolves (or fail-softens to
+`Dynamic[top]`).
+
+```sh
+rigor trace lib/example.rb            # step on key press
+rigor trace --delay=0.5 lib/example.rb # autoplay
+rigor trace --format=json lib/example.rb # raw event stream
+```
+
+`--verbose` adds an enter/result frame for every expression the
+typer visits; the default keeps only the three teachable event
+kinds. The JSON stream is stable enough to build course
+material or figures from.
+
+## Which to reach for
+
+| You want… | Use |
+| --- | --- |
+| One expression's type, from the shell | `rigor type-of` |
+| Every line of a file surveyed | `rigor annotate` |
+| The derivation replayed step by step | `rigor trace` |
+| A type printed mid-analysis, in context | `dump_type` |
+| A type *asserted* and regression-checked | `assert_type` |

data/docs/manual/06-baseline.md

@@ -0,0 +1,104 @@
+# Baselines
+
+A **baseline** records the diagnostics a project already has,
+so `rigor check` can stay silent about them and surface only
+what is *new*. It is the pragmatic on-ramp for adopting Rigor
+on an existing codebase: you do not have to reach zero
+diagnostics before the check becomes useful in CI.
+
+## The baseline file
+
+A baseline is a YAML file — `.rigor-baseline.yml` by
+convention — listing buckets of known diagnostics:
+
+```yaml
+version: 1
+ignored:
+  - file: app/models/user.rb
+    rule: call.undefined-method
+    count: 3
+  - file: app/lib/legacy.rb
+    rule: call.argument-type-mismatch
+    count: 1
+```
+
+Each row is a **bucket** keyed by `(file, rule)`, with a
+`count` of how many diagnostics of that rule the file is
+allowed. An optional `message:` field (a regular-expression
+source) narrows a bucket to call sites whose message matches.
+
+You do not hand-write this file — `rigor baseline generate`
+produces it.
+
+## Turning a baseline on
+
+A baseline file sitting in the project is **dormant** until
+something activates it — presence alone does nothing. Activate
+it with the config key:
+
+```yaml
+baseline: .rigor-baseline.yml
+```
+
+or per run with `rigor check --baseline=PATH`. `--no-baseline`
+ignores a configured one for a single run, and `baseline:
+false` in a config file disables a baseline inherited through
+`includes:`.
+
+## All-or-nothing per bucket
+
+When a baseline is active, each bucket is matched whole:
+
+- **current count ≤ recorded count** — every diagnostic in the
+  bucket is silenced.
+- **current count > recorded count** — every diagnostic in the
+  bucket surfaces, not just the excess.
+
+The reasoning: line numbers drift as a file is edited, so a
+partial match cannot reliably point at *which* diagnostic is
+the new one. Surfacing the whole bucket asks you to review
+that rule × file together.
+
+The baseline filter runs **last** — after `# rigor:disable`
+comments and the severity profile. A baseline never resurrects
+a diagnostic another layer has already suppressed.
+
+## The `rigor baseline` commands
+
+| Command | Use |
+| --- | --- |
+| `rigor baseline generate` | Write a fresh baseline from the current diagnostics. Refuses to clobber an existing file without `--force`. |
+| `rigor baseline regenerate` | Rewrite unconditionally — run it after fixing diagnostics so the file shrinks. |
+| `rigor baseline dump` | Print the baseline, filterable with `--rule` and `--file`. |
+| `rigor baseline drift` | Show how buckets have moved — `--only=over` for buckets that grew, `reducible` for ones you have already improved past, `cleared` for empty ones. |
+| `rigor baseline prune` | Drop buckets that match nothing any more. `--dry-run` previews. |
+
+`generate` and `regenerate` take `--match-mode=rule` (the
+default — one bucket per file × rule) or `--match-mode=message`
+(a bucket per distinct message: more precise, more churn).
+
+## Working a baseline down
+
+`rigor triage` summarises a diagnostic stream — rule
+distribution, class/method selectors, the files with the most
+diagnostics, and heuristic hints about likely causes — so you can
+decide what to tackle first:
+
+```sh
+rigor triage
+```
+
+The `selectors` section (`rigor triage --format json | jq
+'.selectors'`) is the best prioritisation signal: a class/method
+with a high `count` spread across many `files` is a systemic cause
+one fix or a `pre_eval:` entry clears in bulk, while a low-`count`
+selector is a candidate genuine bug to fix at the site.
+
+It is advisory and always exits `0`. The intended loop is
+`triage` to prioritise → fix or suppress a rule → `rigor
+baseline regenerate` to shrink the file. The
+[`rigor-baseline-reduce` skill](08-skills.md) walks this loop
+interactively.
+
+To make CI fail when the baseline *grows*, add
+`--baseline-strict` to `rigor check`.

data/docs/manual/07-plugins.md

@@ -0,0 +1,92 @@
+# Using plugins
+
+A plugin teaches Rigor about a framework, a gem, or an
+application DSL that plain inference cannot see — Rails route
+helpers, RSpec `let` bindings, dry-rb struct attributes, and
+so on. This page is about *activating* plugins. Writing one is
+covered by [`examples/`](../../examples/README.md) and the
+[`rigor-plugin-author` skill](08-skills.md).
+
+## Activating a plugin
+
+List plugins under the `plugins:` key in your config file:
+
+```yaml
+plugins:
+  - rigor-activerecord
+  - rigor-rspec
+  - rigor-rails-routes
+```
+
+Each name is a plugin that ships bundled inside the `rigortype`
+gem — no separate installation is needed. Listing a plugin under
+`plugins:` is enough to activate it. A plugin that needs
+configuration takes the object form:
+
+```yaml
+plugins:
+  - gem: rigor-activerecord
+    config:
+      schema: db/schema.rb
+```
+
+## Available plugins
+
+Rigor ships a catalogue of production plugins under
+[`plugins/`](../../plugins/README.md). The set grows between
+releases — consult that directory for the current list and
+each plugin's options — but the families today are:
+
+- **Rails** — `rigor-activerecord`, `rigor-actionpack`,
+  `rigor-rails-routes`, `rigor-rails-i18n`,
+  `rigor-actionmailer`, `rigor-activejob`,
+  `rigor-activestorage`, `rigor-actioncable`. The
+  `rigor-rails` meta-gem bundles the Rails set for Gemfile
+  convenience; you still enumerate the individual plugins you
+  want under `plugins:`.
+- **Testing** — `rigor-rspec`, `rigor-rspec-rails`,
+  `rigor-minitest`, `rigor-shoulda-matchers`,
+  `rigor-factorybot`.
+- **dry-rb** — `rigor-dry-types`, `rigor-dry-schema`,
+  `rigor-dry-struct`, `rigor-dry-validation`.
+- **Other ecosystems** — `rigor-sinatra`, `rigor-hanami`,
+  `rigor-devise`, `rigor-pundit`, `rigor-sidekiq`,
+  `rigor-graphql`, `rigor-statesman`, `rigor-sorbet`,
+  `rigor-typescript-utility-types`,
+  `rigor-activesupport-core-ext`.
+
+## `plugins/` versus `examples/`
+
+[`plugins/`](../../plugins/README.md) holds production plugins
+for real gems and frameworks — the ones you activate. The
+[`examples/`](../../examples/README.md) tree holds *tutorial*
+plugins over deliberately simplified DSLs; they are reading
+material for plugin authors, not for activation in a real
+project.
+
+## Sandboxing
+
+A plugin may want to read a file (a schema dump) or reach the
+network. Those are gated by the `plugins_io:` config keys —
+the network is `disabled` by default, and a plugin can read
+only the paths you list. See
+[Configuration](03-configuration.md).
+
+### Isolation strategy
+
+A few plugins call into their target library directly (for
+example to ask ActiveSupport's real inflector how to pluralise a
+class name). That call runs under an **isolation strategy**, set
+with the `RIGOR_PLUGIN_ISOLATION` environment variable:
+
+| Value | Behaviour |
+| --- | --- |
+| `process` (default) | Run the call in a forked, crash-contained worker, so the target library's monkey-patches and any crash never contaminate Rigor. Falls back to `none` where `fork` is unavailable (Windows / JRuby). |
+| `none` | Load the library into Rigor's own process and call it directly. |
+| `ruby_box` | Run inside an experimental `Ruby::Box` sandbox. This needs the `RUBY_BOX=1` start flag, so the `rigor` launcher re-execs itself with it set when you select this strategy. |
+
+The legacy `RIGOR_BOX` environment variable is a back-compat
+alias for `RIGOR_PLUGIN_ISOLATION=ruby_box`. The default
+(`process`) is the right choice for almost everyone; the variable
+exists for the rare platform where forking is unavailable or
+where you want stronger containment.