rigortype 0.3.9 → 0.4.0

data/docs/handbook/04-tuples-and-shapes.md

@@ -184,23 +184,25 @@ final = { **defaults, **overrides }
 ## Pattern matching destructuring
 
 `case x in [a, b, c]` narrows `a` / `b` / `c` per-position
-exactly like multiple-assignment:
+exactly like multiple-assignment: the pattern binds against the
+subject's type, so a tuple subject hands each slot its element and
+an `Array[T]` subject hands each slot `T`.
 
 ```ruby
 case [10, 20, 30]
 in [first, _, third]
-  assert_type("Dynamic[top]", first)   # pattern bindings are not constant-folded
-  assert_type("Dynamic[top]", third)
+  assert_type("10", first)
+  assert_type("30", third)
 end
 ```
 
-Hash patterns work the same way:
+Hash patterns read the subject's own `deconstruct_keys` projection:
 
 ```ruby
 case { name: "Alice", age: 30 }
 in { name:, age: }
-  assert_type("Dynamic[top]", name)   # pattern bindings are not constant-folded
-  assert_type("Dynamic[top]", age)
+  assert_type("\"Alice\"", name)
+  assert_type("30", age)
 end
 ```
 

data/docs/handbook/07-rbs-and-extended.md

@@ -467,17 +467,22 @@ Notes:
   falls back to no inline-RBS contribution and analysis
   continues.
 - When a method is declared **both** in `sig/` and by an
-  inline annotation, the `.rbs` wins for that one method and
-  the inline signature is dropped — reported as a
-  `source-rbs-annotation-not-honoured` `:info` naming both
-  files. Only the overlapping member stands down; every other
-  annotation in the file still binds, and the class keeps its
-  method surface. This matters while migrating in either
-  direction: rbs and Steep merge the two sources without
-  ranking them, so left to collide they fail the class's
-  definition build and every call on it — real methods and
-  typos alike — reads `Dynamic[top]`. Delete one of the two
-  declarations to make the inline one take effect.
+  inline annotation, Rigor compares the two and one of them
+  binds. If one refines the other — `Symbol` in `sig/`,
+  `:asc | :desc` inline — the more precise one binds and
+  nothing is reported; `untyped` and `void` are consistent
+  with anything. If they contradict — a `String` parameter
+  against an `Integer` one — the `.rbs` binds and the run
+  reports `rbs.contradicting-signature`, an error, at the
+  `sig/` line: usually a stale generated signature. If Rigor
+  cannot tell, the `.rbs` binds and the dropped inline
+  signature is reported as a `source-rbs-annotation-not-honoured`
+  `:info` naming both files. Only the overlapping member is
+  affected; every other annotation in the file still binds,
+  and the class keeps its method surface. rbs and Steep merge
+  the two sources without ranking them, so left to collide
+  they fail the class's definition build and every call on it
+  — real methods and typos alike — reads `Dynamic[top]`.
 
 Full plugin documentation, configuration options (including
 the `require_magic_comment: false` host-context override the

data/docs/handbook/10-sorbet.md

@@ -277,8 +277,9 @@ warnings until the engine's case narrowing improves.
 
 ## Tier ordering — what wins on conflict
 
-When a method has both a Sorbet `sig` and an RBS sig, RBS
-wins. Sorbet sigs sit at Rigor's plugin tier:
+When a method has both a Sorbet `sig` and an RBS sig, the
+Sorbet `sig` types the call site. Sorbet sigs sit at Rigor's
+plugin tier, which answers before RBS dispatch:
 
 1. **Precision tiers** — constant fold, shape dispatch,
    block fold, etc.
@@ -289,14 +290,12 @@ wins. Sorbet sigs sit at Rigor's plugin tier:
 4. **Dependency-source inference** (ADR-10's opt-in walker).
 5. **User-class fallback** (`Object` / `Class` ancestors).
 
-The contribution merger (a v0.1.0 substrate documented in
-[`docs/internal-spec/flow-contribution-merger.md`](../internal-spec/flow-contribution-merger.md))
-keeps RBS authoritative on conflict — the Sorbet sig is
-allowed to refine but not contradict it. Users who want
-their Sorbet sig to override should remove the conflicting
-RBS, not the other way around. The reverse direction
-(Sorbet wins) would let third-party-DSL annotations
-override authored RBS, which inverts the trust model.
+A plugin's return type replaces the RBS return with no
+diagnostic ([ADR-2](../adr/2-extension-api.md) § "Amendment
+2026-09-26"), so where the two sigs disagree, callers see the
+Sorbet return. The RBS still binds the method's body, which
+is checked against the declared return. Keep the two
+signatures in agreement; remove the one you no longer mean.
 
 ## Migration patterns
 

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

@@ -9,7 +9,7 @@ tooltips, downstream consumers reading your gem's `sig/` —
 sees what Rigor sees.
 
 This chapter is a walkthrough of the command's UX, the
-classification model, the three output modes, and the
+classification model, the output modes, and the
 `--params` policy trade-off that comes straight out of
 [ADR-5](../adr/5-robustness-principle.md)'s asymmetric
 "strict on returns, lenient on parameters" rule.
@@ -67,30 +67,70 @@ By default the command writes nothing — it prints the
 proposal so you can review it. Pass `--write` to apply the
 proposal to `sig/`.
 
-## The three output modes
+## The output modes
 
 | Mode | Behaviour |
 | --- | --- |
 | `--print` (default) | Print RBS to stdout, grouped by source file + class declaration. |
 | `--diff` | Show a unified-style diff comparing the existing-declared spelling (if any) against the inferred spelling. Read-only. |
 | `--write` | Apply the proposal to `sig/<path>.rbs`. Creates files, inserts new methods into existing class declarations, appends new class blocks to files that don't declare them yet. |
+| `--check` | Run the `--write` merge without writing, print what it would change, and exit `1` if anything would change. Read-only. |
+
+The four flags are mutually exclusive; passing two different
+ones is a usage error.
 
 `--write` is the only mode that touches the filesystem. It
 operates **only** inside `configuration.signature_paths`
 (default `sig/`); anything outside that tree is reported as
 `skipped_outside_sig_root` without being written to.
 
+### Keeping `sig/` current in CI
+
+`--check` is the freshness gate. It takes the same options as
+`--write` and fails exactly when that `--write` would create or
+change a file, or would refuse one:
+
+```sh
+rigor sig-gen --check lib
+```
+
+```
+would create sig/greeter.rbs (1 method(s))
+  + def greet: (String name) -> String
+```
+
+It also fails while a method stands refused
+(`sig.skipped.inline-differs`), since `--write` refuses it
+too. It exits `0` and prints `sig/ is up to date`
+otherwise. Under `--format=json` the payload is
+`{"up_to_date": …, "results": […], "refused": […]}`: one
+entry per target in the `--write` JSON shape, with `action`
+reading `would_create` / `would_update`, and one per refused
+method.
+
+The gate follows `--write`, not `--diff`
+([ADR-112](../adr/112-extrbs-comment-channel.md) WD4 records
+the departure). A `tighter-return` against a declaration that
+already exists is a proposal `--write` declines without
+`--overwrite`, so it does not fail `--check` either: a
+reviewed, deliberately wider type must not fail the gate
+forever. `--check --overwrite`
+counts it, because `--write --overwrite` would apply it. Pass
+`--check` the `--params` and `--effect-envelopes` flags your
+`--write` uses, or it checks a different output.
+
 ## The classification model
 
-Every method `rigor sig-gen` considers lands in one of five
+Every method `rigor sig-gen` considers lands in one of six
 states:
 
 | Classification | Meaning |
 | --- | --- |
 | `new-file` | No RBS file declares the receiver class at all. |
 | `new-method` | RBS file declares the class but not this method. |
-| `tighter-return` | RBS file declares the method, but the inferred return is a strict subtype of the declared return. |
-| `equivalent` | Nothing for `sig-gen` to propose: the inferred return is identical, wider or unrelated, or it is a narrowing the generator declines (a literal under a wider declaration, anything under a declared `void`). Silently skipped. |
+| `tighter-return` | RBS file declares the method, but the inferred return is a strict subtype of the declared return. The proposal is the declared line with only its return replaced; see [Tighter returns keep the declared parameters](#tighter-returns-keep-the-declared-parameters). |
+| `inline-overwrite` | Only under `--overwrite`: a method declared inline with `# @rbs` / `#:` whose `sig/` declaration disagrees with it; the whole `sig/` member is replaced by the inline one. See [Methods declared inline](#methods-declared-inline). |
+| `equivalent` | Nothing for `sig-gen` to propose: the inferred return is identical, wider or unrelated, or it is a narrowing the generator declines (a literal under a wider declaration, anything under a declared `void`, an overloaded declaration or an `alias`), or the method is an `initialize` the class already declares. Silently skipped. |
 | `skipped` | Disqualified for one of the reasons below. |
 
 The `sig.skipped.*` reasons are:
@@ -108,6 +148,17 @@ The `sig.skipped.*` reasons are:
 - `sig.skipped.user-authored` — `--overwrite` was not set
   and the method's existing RBS declaration would have to
   be replaced.
+- `sig.skipped.inline-declared` — `.rigor.yml` sets
+  `sig_gen.inline_declared: skip` and the method is declared
+  inline. See [Methods declared inline](#methods-declared-inline).
+- `sig.skipped.inline-generic-class` — the method's class is
+  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.inline-differs` — the method is declared
+  inline and in `sig/`, and the two disagree. A refusal:
+  `--write` and `--check` exit `1`. See
+  [Methods declared inline](#methods-declared-inline).
 - `sig.skipped.unrenderable-rbs` — the signature Rigor
   rendered for this method does not parse as RBS. This one
   is a **bug in Rigor**, not a property of your code: every
@@ -119,6 +170,308 @@ The `sig.skipped.*` reasons are:
   the skipped method is reported on stderr, and it is worth
   reporting to us.
 
+### Tighter returns keep the declared parameters
+
+A `tighter-return` changes the return and nothing else. The
+visibility, the overload's annotations, the method type
+parameters, the parameter list and the block are copied from
+the declaration as written, so applying the proposal never
+changes which calls the signature accepts:
+
+```
+$ rigor sig-gen --diff lib/c.rb
+--- lib/c.rb: C#m
+- def m: (Integer x) -> untyped
++ def m: (Integer x) -> nil
+
+--- lib/c.rb: C#n
+- def n: (?) -> untyped
++ def n: (?) -> nil
+```
+
+The `-` line is the declaration the proposal replaces. A method
+declared only on an ancestor is different: the proposal adds an
+override to the method's own class, and it is written from that
+class's `def` like a new method, with `untyped` parameters. The
+ancestor's parameters describe the ancestor's `def`, and the
+override may take other arguments.
+
+Two declarations get no proposal:
+
+- One with more than one overload
+  (`def m: (Integer) -> untyped | (String) -> untyped`). The
+  body is typed once for all of its overloads, so the inferred
+  return does not say which overload returns what. Merging the
+  overloads into one line would drop them, and giving every
+  overload the same return would widen the ones you wrote
+  narrower.
+- A name the class itself declares through `alias al m`. Its
+  parameters are `m`'s, and the proposal would read as a
+  rewrite of `m`'s line. An alias only an ancestor declares is
+  overridden like any other ancestor declaration.
+
+An `initialize` your `sig/` already declares is `equivalent`
+too. sig-gen writes a constructor stub only for a class that
+does not declare one. The exception is `--params=observed`:
+when the observed argument types would replace an `untyped` the
+declaration still has, the stub is proposed so that
+`--overwrite` can apply it.
+
+## Methods declared inline
+
+A method you annotated with `# @rbs` or `#:` already has a
+contract, written next to the code. `sig-gen` does not infer
+one for it; it copies yours into `sig/`, so the generated
+signature is the whole contract your gem ships:
+
+```ruby
+class Greeter
+  # @rbs name: String
+  # @rbs return: String
+  def greet(name) = "Hello, #{name}"
+
+  #: () -> Integer
+  def count = 1
+
+  # @rbs num: Float
+  def pair(num) = [num, num.to_s]
+end
+```
+
+```
+$ rigor sig-gen
+# lib/greeter.rb
+class Greeter
+  # [new]
+  def greet: (String name) -> String
+  # [new]
+  def count: () -> Integer
+  # [new]
+  def pair: (Float num) -> [Float, String]
+end
+```
+
+`count` is written as `Integer`, not the `1` its body proves:
+the declaration is what you meant, and inference does not
+override it. `pair` declares its parameter and not its return,
+so the parameter is copied and the return comes from the body,
+the same split [ADR-107](../adr/107-checked-types-and-typeless-comments.md)
+draws between authored parameters and generated returns. An
+`initialize` is always written `-> void`, whatever its body
+ends with. A member annotation you wrote inline, such as
+`# @rbs %a{deprecated}`, is copied with it. A method with no
+annotation of its own is proposed exactly as in any other
+file.
+
+Once `sig/` holds the copy, `rigor check` reads it beside the
+inline declaration, and an identical pair is quiet
+([ADR-112](../adr/112-extrbs-comment-channel.md) WD5).
+sig-gen compares the two on every run, `attr_*` declarations
+included. They are compared as types, not text:
+parameter names, spacing, how a union is spelled (`String?`
+and `String | nil`, `Integer | String` and `String |
+Integer`, `bool` and `true | false`) and a leading `::` do
+not count. The `::` only counts when it changes what the name
+means: inside `module NS`, `Foo` is `NS::Foo` if `NS`
+declares one, and then it is not `::Foo`. Overload order does
+count, because RBS answers a call with the first overload that
+matches. When the two agree, and `sig/` carries every
+annotation you wrote inline, there is nothing to do.
+
+When they differ, sig-gen does not pick a side. The inline
+annotation may be your newer edit; the `sig/` member may be a
+reviewed contract someone changed on purpose. The method is
+refused as `sig.skipped.inline-differs`: nothing is written,
+`--write` prints a `REFUSED` line and exits `1` (under
+`--format=json` the refused methods are listed under
+`refused`), and `--check` fails, so the contradiction cannot
+pass CI unnoticed. Resolve it one of two ways:
+
+- Keep the inline declaration: re-run with `--overwrite`. The
+  whole `sig/` member is replaced by the inline line, as
+  rbs-inline reads it — a parameter you left unannotated is
+  `untyped`, an unannotated `&block` is `?{ (?) -> untyped }`
+  — and an `attr_*` declaration is replaced by the inline
+  attribute in the same spelling. The two sides are never
+  mixed slot by slot: their overloads and type variables need
+  not correspond. That also means an overload written only in
+  `sig/` is dropped, and a caller that relied on it can stop
+  type-checking; read the `--diff` first. Comments inside the
+  replaced member, and annotations already on it, are kept.
+- Keep the `sig/` member: edit or delete the inline annotation
+  to match.
+
+A `sig/` member written `def m: ... | ...` is not a copy: it
+adds overloads to the inline declaration, and sig-gen leaves it
+alone.
+
+A parameter-only annotation (`# @rbs name: String`, no
+`return:`) states the parameters and nothing else, so only the
+parameters are compared. When they match, the return in `sig/`
+is weighed like any declared return: a `-> void`, a type wider
+than what the body proves, or a literal the body happens to
+return (`-> String` over `"x"`) is left as it is, and a return
+the body proves strictly narrower is a `tighter-return`
+proposal, applied only with `--overwrite`. When the parameters
+differ, the method is refused even under `--overwrite`: the
+body is typed under the parameters the `sig/` member declares,
+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.
+
+### 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
+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
+those of classes nested in it, are skipped as
+`sig.skipped.inline-generic-class`. Declare the class in
+`sig/` with the same parameters (`class Box[T]` ... `end`) and
+sig-gen writes the members into that declaration. A `sig/`
+declaration that names them otherwise (`class Box[U]`) is
+skipped the same way: a copied `-> T` would name a parameter
+nothing binds.
+
+### Projects that run Steep on the same annotations
+
+If Steep reads your inline annotations (`check "lib", inline:
+true` beside `signature "sig"`), a copy in `sig/` is a second
+declaration of each method, and Steep rejects the class with
+`DuplicatedMethodDefinition`. Tell `sig-gen` to leave those
+methods out:
+
+```yaml
+sig_gen:
+  inline_declared: skip
+```
+
+Every method the inline reader declares is then skipped as
+`sig.skipped.inline-declared`. That includes the un-annotated
+`def`s of a file that carries any annotation, because the
+reader declares those too (as `untyped`), and so does rbs's
+own inline parser, which Steep's `inline: true` uses. A file
+with no annotation at all is not read inline by Rigor, so its
+methods are still written; if Steep reads that file inline,
+keep it out of the paths you give `sig-gen`.
+
+What the setting costs: `sig/` is no longer the whole
+contract. A consumer that reads only your shipped `sig/` —
+Rigor or Steep in a project that depends on your gem — never
+sees the skipped methods. Their inline annotations, including
+a Rigor refinement written there, take effect only where the
+source itself is analysed, which is your own project.
+
+## Emitting effect annotations
+
+If your `.rigor.yml` carries an `effects:` block, `sig-gen`
+writes one more thing: `%a{pure}`, the purity annotation rbs
+and Steep already understand, above the methods whose whole
+footprint Rigor read and found to be nothing.
+
+```ruby
+class Label
+  def render
+    parts = []
+    parts << "a"
+    parts.join
+  end
+end
+```
+
+```
+$ rigor sig-gen
+# lib/label.rb
+class Label
+  # [new]
+  %a{pure}
+  def render: () -> String
+end
+```
+
+Five conditions have to hold before an annotation is written,
+and every one of them exists to keep a wrong one off the
+page. An emitted annotation is not a hint — the effects opt-in reads
+it back as an **envelope** and enforces it on the method and
+on everything the method reaches, so a `%a{pure}` `sig-gen`
+invented would put `effect.envelope-exceeded` on code that
+is correct.
+
+- The summary must be **exhaustive**: every call the method
+  reaches was resolved. A summary that is not reads "these
+  effects, and possibly more", which is exactly the claim an
+  envelope must not make.
+- The summary must be **undischarged**: nothing in the
+  method's footprint may be invisible only because
+  `effects.tolerated:` says to ignore it. A method whose
+  whole footprint is a tolerated `telemetry` call looks
+  clean to *your* project and to nobody else — not to a
+  consumer reading your shipped `sig/`, and not to your own
+  `--no-tolerated-effects` audit.
+- Every callee must be **described by something**: a
+  catalogue row, a plugin, an envelope, or a definition in
+  your own project. "Every call resolved" and "every callee's
+  footprint is known" are different questions. A method whose
+  body is one call into a gem nobody has written a row or an
+  envelope for is exhaustive and tells you nothing, so it is
+  left bare rather than called pure.
+- The method must not **already carry a bound of its own**.
+  An annotation on the method or on its class — in `sig/` or
+  as an rbs-inline `# @rbs %a{…}` — or an `effects.envelopes:`
+  stanza selecting it by `namespace:` or by `match:`, is a
+  contract you wrote about this body; sig-gen will not replace
+  it with an inference about the same body. A bound whose
+  label is misspelled counts too: it bounds nothing, but
+  overwriting it would delete the annotation the
+  `effect.unknown-label` report points at.
+- The `≤` lane must be **empty**. A callee that states its
+  own bound puts that claim in your method's declared lane
+  without proving anything, so `rigor effects` shows
+  `[] ≤ [io.net.http]` where the proven lane is empty. Rigor
+  will not write `%a{pure}` over a claim it never proved
+  away.
+
+`--effect-envelopes` adds the labelled spelling,
+`%a{rigor:v1:effect io.db, nondet.time}`, for methods that
+do have a footprint. It is a separate flag because `%a{pure}`
+is the ecosystem's annotation and this one is Rigor's: a
+labelled envelope in your `sig/` is a Rigor-specific contract,
+and you should ask for it by name.
+
+Under `--write`, an annotation goes on the line above the
+declaration it binds. A declaration that **already** carries
+annotations is left byte-untouched and reported as
+`sig.effect.left-unreadable`: the writer cannot tell an
+annotation it wrote from one you wrote, and it has no grammar
+for merging two, so it will not rewrite that region. Decide
+what it should say and write it yourself.
+
+The `sig.effect.*` reasons are:
+
+- `sig.effect.emitted` — an annotation was rendered.
+- `sig.effect.withheld-tolerated` — the footprint is only
+  clean under `effects.tolerated:`.
+- `sig.effect.withheld-non-exhaustive` — some call the
+  method reaches could not be resolved.
+- `sig.effect.withheld-unclaimed-callee` — some call it
+  reaches resolved, and nothing anywhere says what that
+  callee does.
+- `sig.effect.withheld-declared` — the method already carries
+  an authored bound, or a label survives in the `≤` lane.
+- `sig.effect.left-unreadable` — the target declaration
+  already carries annotations, so nothing was written there.
+
+One limit worth knowing: annotations ride on the signature
+lines `sig-gen` proposes, so a method whose declaration is
+already exactly right gets none. An up-to-date `sig/` is
+therefore not annotated in place; the reader for those is
+`rigor effects --pure`, and writing them is still a hand
+edit.
+
+With no `effects:` block in `.rigor.yml`, none of this runs
+and the output is byte-for-byte what it was before.
+
 The three `sig.generated.*` identifiers
 (`sig.generated.new-file` / `new-method` / `tighter-return`)
 are emitted as JSON fields under `--format=json` so CI
@@ -219,7 +572,14 @@ list is the current state):
   RBS.
 - **`attr_reader` / `attr_writer` / `attr_accessor`** with
   literal Symbol arguments. The return type is the
-  accumulated ivar type from `Scope#class_ivars_for`. The
+  accumulated ivar type from `Scope#class_ivars_for`. A
+  writer stores whatever its caller passes, so an
+  `attr_writer` / `attr_accessor` ivar reads untyped.
+  The accessor, and any other method returning that
+  ivar, is skipped even beside a concrete write such as
+  `@logger = Logger.new`, unless `--params=observed`
+  types the constructor parameter the ivar is assigned
+  from. The
   generator emits the long-form `def name: () -> T`
   spelling so the writer's merge path applies unchanged;
   existing short-form `attr_reader name: T` declarations
@@ -243,7 +603,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 `spec/` when present), union per parameter position, erase to RBS, emit the union. |
+| `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, sig-gen says so on stderr. |
 | `observed-strict` | Reserved. Will additionally widen to capability roles (`_ToStr`, `_ToS`, …) once the role catalog ships. Currently rejected with a usage error. |
 
 The default deliberately favours `untyped` because of
@@ -261,9 +621,76 @@ parameter contract I want."* That is a correctness-
 preserving widening — every existing caller still passes —
 but it does narrow the contract relative to `untyped`.
 
+## Type aliases your project declares
+
+When a proposal's type is a union whose members are exactly
+the expansion of a `type` alias declared in your own
+`sig/`, the alias name is what gets emitted. For a method
+on `Rigor::Type::Combinator`, sig-gen emits
+
+```
+def hash_shape_keys: (untyped) -> ::Rigor::Type::t
+```
+
+rather than the twenty-two members `Rigor::Type::t`
+expands to. The name is written in its absolute form so it
+cannot rebind to a nearer constant of the same spelling.
+
+This applies wherever sig-gen renders a type, not only to
+returns: `--params=observed` parameter positions, `attr_*`
+accessors, and `Data` / `Struct` members all fold the same
+way. The `--format=json` payload carries the folded
+spelling in its `rbs` field; `inferred_return` is the
+carrier the engine computed and stays expanded.
+
+The rule is member-set equality, so a proposal missing one
+arm of the alias still prints in full — the alias names a
+type the method cannot return, and claiming it would be
+wrong rather than merely verbose.
+
+A wrong alias name is worse than a long union: it is an RBS
+claim you did not make. Four rules keep the fold from
+guessing.
+
+**Your aliases only.** The candidates come from your
+configured `signature_paths:` (or `sig/` when you
+configured none) — not from gems in your bundle, not from
+an `rbs collection` tree, and not from core or stdlib RBS.
+Core declares `Warning::category` as `:deprecated |
+:experimental | :performance`; a project that never wrote
+that alias does not get it in its proposals. A loaded
+plugin's own signature directory is subtracted even when
+you listed it in `signature_paths:` yourself — those
+aliases are the plugin's vocabulary.
+
+**Namespace proximity.** An alias is only offered to a
+method whose owner is inside the alias's own namespace, and
+the nearest such alias wins — most specific first, then
+declaration order by (file, line, name). Without this,
+`:positive | :negative` anywhere in a codebase would pick
+up any alias that happens to name that pair.
+
+**Unambiguous alias bodies only.** Some RBS forms reach the
+renderer looking like something else: an intersection can
+read as one of its members, a proc type as a bare `Proc`, a
+nested alias as whatever it expanded to. An alias whose
+body contains one of those is skipped, because a fold into
+it would put a type in your signature that the method does
+not return. Only class instances, singletons, literals,
+unions, optionals, tuples and the `nil` / `bool` / `bot`
+bases qualify.
+
+**Unions only, non-generic only.** A `type name = String`
+alias never rewrites an ordinary `String` return, and a
+generic alias (`type boxed[T] = ...`) has no fixed member
+set to match.
+
+A project that declares no aliases gets byte-for-byte the
+output it got before.
+
 ## RSpec-aware observations
 
-When you point `--observe` at a `spec/` directory, the
+When the observed test roots hold an RSpec suite, the
 generator recognises three RSpec-shaped binding patterns
 and uses them to type receivers that would otherwise
 degrade to `Dynamic[top]`:
@@ -289,6 +716,13 @@ across nested scopes are last-wins; the recogniser does not
 re-implement RSpec's full scope rules — the typical
 one-spec-file shape is the target.
 
+A Minitest suite under `test/` is observed too, with no
+recogniser of its own: a call whose receiver types to one
+class counts. A receiver assigned in `setup` is the gap —
+inside a `test_*` method it reads as `Foo | nil`, and such
+a call is not observed yet
+([#1389](https://github.com/rigortype/rigor/issues/1389)).
+
 The recogniser is part of the generator itself; you do not
 need to install `rigor-rspec` to benefit from it. If you
 already use `rigor-rspec` for diagnostics, the two run side
@@ -308,9 +742,16 @@ by side without coordination.
   tree.
 - **Will not** replace an existing method declaration
   unless `--overwrite` is set AND the candidate is a
-  `tighter-return`. Without `--overwrite`, existing
-  declarations are user-authored and the new method is
-  silently skipped.
+  `tighter-return`, and then only its return changes: the
+  rest of the declaration is kept. Without `--overwrite`,
+  existing declarations are user-authored and the new method
+  is silently skipped.
+- **Will not** change an existing method declaration that
+  disagrees with the method's inline declaration unless
+  `--overwrite` is set; it reports the method as `REFUSED`
+  and exits `1`. With `--overwrite` the whole member is
+  replaced by the inline declaration (`inline-overwrite`),
+  keeping the comments and annotations already on it.
 - **Will not** touch `attr_reader` / `attr_writer` /
   `attr_accessor` declarations in existing RBS — those are
   always treated as user-authored.
@@ -362,8 +803,8 @@ A typical iteration on a new file:
 # 1. See what Rigor would propose.
 rigor sig-gen lib/calc.rb
 
-# 2. Run with the observed-params policy to use spec/ as
-#    a parameter-type signal.
+# 2. Run with the observed-params policy to use the test
+#    roots (`test_paths:`) as a parameter-type signal.
 rigor sig-gen --params=observed lib/calc.rb
 
 # 3. Compare against the current sig/ tree.