rigortype 0.3.8 → 0.4.0

data/docs/manual/18-removing-dead-code.md

@@ -80,14 +80,16 @@ partition `declared` — they sum to 1497. **`reachable only from tests`
 is a subset of `reachable`**, not a fifth bucket, so do not add it in.
 
 Read `roots` first. A root is a declaration something outside your code
-reaches — an entry point, a route, a framework convention.
-Reachability is computed *from* roots, so a thin root set inflates
-everything below it. The pathological case is a Rails application with
-`0 from plugins`: nothing in Ruby source names a controller, so every
-controller you own appears dead. There is no published healthy ratio
-to compare against; what you are checking is whether the number is
-plausible for your framework, and `0 from plugins` on a framework app
-never is.
+reaches — an entry point, a route, a framework convention. The
+`(… from plugins, …)` parenthetical is omitted entirely when no plugin
+contributed a root, so a bare `roots: N` with no such note is itself
+the signal. Reachability is computed *from* roots, so a thin root set
+inflates everything below it. The pathological case is a Rails
+application with no `from plugins` note at all: nothing in Ruby source
+names a controller, so every controller you own appears dead. There is
+no published healthy ratio to compare against; what you are checking
+is whether the number is plausible for your framework, and a missing
+`from plugins` note on a framework app never is.
 
 ## Getting the number down
 

data/docs/manual/19-effect-labels.md

@@ -214,6 +214,16 @@ rigor effects --pure
 436 methods on Redmine, and they are your `%a{pure}` candidates — the on-ramp to
 the last section of this chapter.
 
+You do not have to write them all out by hand. With the `effects:` block in
+place, `rigor sig-gen` annotates the methods in this set whose signature it is
+proposing anyway: `%a{pure}` above every method that is exhaustive, undischarged,
+free of surviving `≤` labels, not already carrying a bound you wrote, and calling
+nothing the analyzer had no description for; and, under `--effect-envelopes`, the labelled spelling for the methods that
+do have a footprint. A method that is clean only because `effects.tolerated:`
+says so is deliberately left bare — the annotation would travel to readers who
+do not share your tolerated list. See
+[handbook chapter 11](../handbook/11-sig-gen.md#emitting-effect-annotations).
+
 ### Asking it a question
 
 **By label.** The question this chapter opens with, in one command:

data/docs/manual/plugins/README.md

@@ -54,6 +54,9 @@ The full catalogue, with a one-line scope for every plugin, is
   `Result` / `Option` unwrap types and synthesises `Enum` variants.
 - [rigor-pundit](rigor-pundit.md) — policy-class existence and
   `authorize(record, :action)` predicate validation.
+- [rigor-active-model-serializers](rigor-active-model-serializers.md) —
+  types the `object` reader inside a serializer as the serializer's
+  model (no diagnostics).
 - [rigor-sidekiq](rigor-sidekiq.md) — Sidekiq `Worker.perform_*`
   argument arity against the discovered `#perform`.
 - [rigor-actioncable](rigor-actioncable.md) — `broadcast_to` channel
@@ -62,6 +65,10 @@ The full catalogue, with a one-line scope for every plugin, is
   through Minitest / Test::Unit assertions and spec matchers.
 - [rigor-graphql](rigor-graphql.md) — GraphQL-Ruby type / enum / input
   / mutation table publication (cross-plugin facts, no diagnostics).
+- [rigor-grape](rigor-grape.md) — types the `Grape::API` endpoint DSL
+  (`params`, `namespace`, verb macros, `desc`, `route_setting`) and
+  `Grape::Entity` `expose` declarations, including the `instance_eval`'d
+  block `self` bindings.
 - [rigor-rspec-rails](rigor-rspec-rails.md) — `have_http_status`
   argument validation (out-of-range codes, unknown status symbols).
 - [rigor-shoulda-matchers](rigor-shoulda-matchers.md) — shoulda matcher

data/docs/manual/plugins/rigor-actioncable.md

@@ -36,7 +36,7 @@ ActionCable.server.broadcast("chat_room_42", body: "hi")    # warning: no such s
 | `plugin.actioncable.broadcast-stream` | info | `ActionCable.server.broadcast("...", ...)` matched a registered `stream_from` literal |
 | `plugin.actioncable.unknown-channel` | error | the receiver ends in `Channel` but is not in the index (with a did-you-mean) |
 | `plugin.actioncable.unknown-stream` | warning | the literal stream name matched no `stream_from` registration (with a did-you-mean) |
-| `plugin.actioncable.load-error` | warning | channel discovery failed (parse/read error) — once per file |
+| `plugin.actioncable.load-error` | warning | channel discovery failed (parse/read error) — once per run, on `.rigor.yml` |
 
 The `unknown-stream` check is **suppressed** when any discovered
 channel registers a dynamic stream (`stream_from interpolated_string`
@@ -100,6 +100,13 @@ default.
 - **The `#receive` contract is path-scoped, not class-scoped** (ADR-28):
   any `def receive(data)` defined anywhere under `channel_search_paths`
   is typed, even on a class that isn't an ActionCable channel.
+- **The "failed to discover channels" warning is run-scoped.** It is
+  a fact about your configuration, not about any one source file, so
+  it is reported once per run on `.rigor.yml` rather than repeated on
+  every analysed file. It is `:warning`, so if you baselined it at its
+  old position that entry no longer matches and the row fails a
+  `--fail-on=warning` run — regenerate with `rigor baseline
+  regenerate`.
 
 ## Plugin internals
 

data/docs/manual/plugins/rigor-actionmailer.md

@@ -69,6 +69,13 @@ plugins:
   which the report already records. Rooting every class under
   `app/mailers` instead would mark a mailer nothing sends reachable
   forever on no evidence.
+- **The "failed to discover mailers" warning is run-scoped.** It is
+  a fact about your configuration, not about any one source file, so
+  it is reported once per run on `.rigor.yml` rather than repeated on
+  every analysed file. It is `:warning`, so if you baselined it at its
+  old position that entry no longer matches and the row fails a
+  `--fail-on=warning` run — regenerate with `rigor baseline
+  regenerate`.
 
 ## Plugin internals
 

data/docs/manual/plugins/rigor-actionpack.md

@@ -54,6 +54,7 @@ plugins:
     config:
       controller_search_paths: ["app/controllers"]  # default
       view_search_paths: ["app/views"]               # default
+      view_type_checks: false                        # default
 ```
 
 ## What it types
@@ -93,8 +94,268 @@ so *can* fold a condition — and `Mime::NullType`, the value `format`
 returns when there is no format, answers `nil?` with `true` while
 being a real object. Typing it needs a nil-aware answer.
 
+## Framework constants resolve
+
+The plugin ships a small bundled signature naming the
+`ActionController` namespace and the errors controllers rescue —
+`ParameterMissing`, `UnpermittedParameters`, `RoutingError`,
+`BadRequest`, `UnknownFormat`, `InvalidAuthenticityToken` and their
+siblings. A `rescue ActionController::ParameterMissing => e` now types
+`e` as that class instead of leaving it opaque.
+
+The signature names **only** those. `ActionController::Base` and
+`ActionController::API` are left undeclared on purpose: every
+controller in the app inherits from one of them, and an incomplete
+declaration of a superclass turns every member it omits — `render`,
+`before_action`, `head` — into a report on working code. For the same
+reason `ActionController::Parameters` and the `ActionDispatch` readers
+above stay undeclared; their leniency is what makes the `params`
+typing safe.
+
+## ERB templates as effect units
+
+Every `app/views/**/*.erb` is compiled to Ruby and analysed as one
+**effect unit**, keyed `view:users/show.html` — Rails' own logical
+name with the handler dropped, so an ERB → Haml rewrite is not a
+rename. Nothing has to be enabled: activating the plugin is what
+claims the templates.
+
+What that buys is the answer to *"what does this request actually
+do"* past the `render` line. A partial that calls `@user.update`
+reports `io.db.write` at `app/views/users/_card.html.erb`, a
+`Time.now` in a layout fragment reports `nondet.time`, a leftover
+`puts` reports `io.output.stdout` — all of it in `rigor effects` and
+in the snapshot, so a template that starts writing shows up in a
+diff.
+
+```
+$ rigor effects
+view:users/_card.html: [mutate.local, nondet.time] ≤ [io.db.write] …?
+view:users/show.html:  [mutate.local]              ≤ [io.db.read]  …?
+```
+
+**The compiler** is Erubi when it resolves in your project's bundle
+— Rails' own — and stdlib `ERB` otherwise. Erubi is never added to
+your Gemfile and is not a Rigor dependency
+([ADR-90](../../adr/90-target-library-resolution-from-project-bundle.md)).
+Either way the line map is measured rather than assumed, so a
+finding names the template's own line; the column is always 1,
+because a compiler rewrites the text of each line and a column of
+the compiled Ruby would name nothing you wrote.
+
+**What `self` is.** `ActionView::Base`, declared so the name
+resolves and **open** so its method surface stays lenient. That is
+what keeps `link_to`, `form_with`, `t`, `content_for`, your own
+`ApplicationHelper` methods and every route helper from drawing a
+finding per line.
+
+**What is in scope.** `@ivars` are seeded from the controller
+actions that render the template — the implicit render
+(`UsersController#show` → `users/show`) and explicit
+`render :edit` / `render "admin/form"`. Two restrictions keep a seed
+from claiming a type the template will not find. Only assignments
+whose right-hand side is one record and cannot be `nil` contribute:
+`User.find(id)` and `Model.new` do; `find_by` never does, nor a call
+written to return several records — `User.find(a, b)`,
+`User.find([1, 2])`, `User.find(*ids)`, `User.create([…])` or a
+`find` with a block. A single argument that only holds an Array at
+runtime (`User.find(ids)`) still seeds the model. And only
+assignments the action reaches on **every** path contribute — not
+one inside an `if`, a `case`, a `rescue`, a loop or a block, and
+nothing from a `before_action` carrying `if:` / `unless:`. Anything
+else leaves the ivar unseeded, which reads as `Dynamic` and is
+silent. A partial inherits the assigns of its own directory, because
+an ivar is not a local. Locals come from the Rails 7.1 strict-locals
+comment:
+
+```erb
+<%# locals: (user:, admin: false) %>
+```
+
+**`call.*` findings are off inside templates by default**, while the
+synthesised receivers are still coarse — measured on redmine and
+mastodon, the feature adds **zero** new findings to either
+([the measurement note](../../notes/20260917-erb-template-units.md)).
+Set `view_type_checks: true` to opt in and have `@user.nmae` in
+`show.html.erb` reported like any other call.
+
+`flow.*` **reports in a template like anywhere else.** It was
+suppressed alongside `call.*` for one measured reason — a partial's
+optional-local preamble (`<% path = nil unless defined? path %>`)
+really did assign nil, because nothing told the unit its render site
+had bound `path`. Render-site `locals:` are traced now, and the same
+two projects re-measured with the family reporting are byte-identical
+to the runs with it suppressed ([the #1047 note](../../notes/20260917-render-locals-and-layouts.md)).
+
+### Locals come from the render site
+
+A partial's parameters are bound by whoever renders it, and every
+spelling of that is read — on both sides of the render:
+
+```erb
+<%= render partial: "card", locals: { user: @user } %>
+<%= render "card", user: @user %>          <%# a view's trailing hash IS locals %>
+<%= render partial: "card", collection: @users, as: :row %>
+<%= render partial: "card", object: @user %>
+```
+
+`collection:` binds `row`, `row_counter` and `row_iteration`;
+`object:` and `as:` bind one local named after the partial or after
+`as:`. A controller's `render partial: …, locals: …` is read the same
+way — but a controller's *trailing hash* is options, so
+`render :show, status: :ok` binds nothing.
+
+A partial rendered from several sites gets the **union** of the
+names. A name only some of them pass is still bound, typed
+`Dynamic` — absence is what produced the false positives above.
+A **type** is claimed only where every site agrees on one it could
+settle from the call itself (`User.find(1)`, or an ivar the rendering
+action's own seeds typed); anything else is `Dynamic`. A
+strict-locals comment still wins where a template carries one.
+
+A partial's **own** optional-local test counts too:
+`<% size = nil unless defined?(size) %>`, `local_assigns[:size]` and
+`local_assigns.key?(:size)` bind `size` even when no render site the
+plugin can read passes it — a `locals: opts` hash, a `render` from a
+helper, or a local with a default nobody passes. A name a helper under
+`app/helpers` defines is left alone, so
+`<% if defined?(current_user) %>` stays a helper call. A helper that a
+gem or a concern defines is not seen by that scan, and its name is
+bound as a `Dynamic` local instead.
+
+### The controller → template edge
+
+A controller action's summary **includes what its template does**.
+`render :show`, `render "show"`, `render "admin/form"`,
+`render template:`, `render action:`, `render partial:` (with or
+without `collection:`) and the implicit render of
+`<controller>/<action>` all reach the template's own unit, and a
+template reaches the partials *it* renders — so an `io.db.write` in
+`app/views/users/_card.html.erb` shows up on `UsersController#show`
+three hops away, and `rigor effects explain` prints the path.
+
+A partial is looked up in the rendering template's own format, with
+the one fallback Action View itself hard-codes: a `.js.erb` template
+reaches `_list.js.erb` where it exists and `_list.html.erb`
+otherwise, which is how "a JS response that injects rendered HTML"
+works at all. Only one of the two is joined, never both. A `.json`,
+`.xml` or `.turbo_stream` template gets no fallback — what those fall
+back to depends on the request's `Accept` header, which the source
+does not say — and neither does a render site that names its format
+(`formats: [:js]`, `render "list.js"`) or a controller-side `render`.
+
+The fallback stops at a template that **exists and produced no
+unit**: a `_list.js.haml`, or a `_list.js.erb` whose compiled Ruby
+does not parse. Rails runs that file, so the `.html` one's effects
+are not what the render produces, and the taint stays. That is why
+this plugin claims `app/views/**/*.{haml,slim,jbuilder,builder,rabl,ruby}`
+and compiles none of them: the claim is how the engine learns a
+template is there. A handler outside that list is invisible, and a
+render of one still falls back.
+
+Two approximations ride along, and each costs labels rather than a
+taint. A partial reached *through* the fallback renders its own
+partials in `html`, while Action View's context is still
+`[:js, :html]`; where a nested partial exists in both formats, the
+`.js` template gets the `.html` one's labels. And a template whose
+name carries no format at all (`_row.jbuilder`) blocks nothing, since
+its key has no format to block — which happens to agree with Rails,
+which ranks a formatted template above it. Both are zero occurrences
+on the measured corpus.
+
+The `template-not-analysed` taint on a `render` is discharged
+exactly when the edge lands on a real unit. It **stays** when it
+does not, and both cases are common enough to name:
+
+- the target is computed — `render params[:view]`, or
+  `render formats: some_format`. The render site is read from
+  literals only, so anything computed keeps the honest "and possibly
+  more";
+- the target names no template this plugin compiled — a `render
+  partial: @thing`, or a partial that exists in neither the requested
+  format nor its fallback;
+- the template is outside `app/views/**/*.erb` — a Haml, Slim or
+  Jbuilder view, which this plugin does not claim.
+
+`render json:`, `render plain:` and the rest of the non-template
+family are left alone: they render no template, the rule declines,
+and the row reads exactly as it did before.
+
+An action that answered for itself is **not** edged to the
+conventional template. `redirect_to`, `head`, `send_data` and
+`send_file` each mean the implicit render did not happen, and
+attributing `users/away` to an action that redirects would be a view
+it never runs.
+
+### Holding views to an effect budget
+
+A view unit is an `effects.envelopes:` subject like any class, and a
+finding is positioned in the template:
+
+```yaml
+effects:
+  envelopes:
+    - match: "app/views/**/*"
+      effect: [mutate.local]
+```
+
+A bound judges only what Rigor proved by reading code, so what this
+catches in a view is what Rigor's own catalogue proves: a `puts`
+(`io.output.stdout`) or a `Time.now` (`nondet.time`).
+
+**Plugin-sourced labels are never judged by an envelope.** A plugin's
+statement about a framework method — `User.find` is `io.db.read`,
+`@user.update` is `io.db.write`, `perform_later` is `job.enqueue` —
+rides the declared (`≤`) lane, and the envelope check reads the proven
+one. Listing `io.db.read` in a view's envelope, or leaving it out,
+changes nothing: the lazy `<%= user.posts.count %>` is not a finding
+either way. That is a property of the whole Rails effect layer rather
+than of views ([ADR-103](../../adr/103-effect-labels.md) WD17, ruled
+in [#1059](https://github.com/rigortype/rigor/issues/1059)).
+
+What notices a view that starts reading the database is the effect
+snapshot. With `.rigor-effects.yml` committed, `rigor effects check`
+fails by default on drift in either lane, and a template that gains a
+query shows up in the diff as a declared-lane addition:
+
+```
+view:users/show.html  ≤+ io.db.read
+```
+
+That is a ratchet on the whole project's recorded effects, reviewed as a
+diff — not a policy scoped to `app/views/**/*`. See
+[Effect labels](../19-effect-labels.md#what-a-bound-can-and-cannot-see).
+
 ## Limitations
 
+- **A controller's own layout is not edged.** A layout is a unit
+  now, and a `render layout:` *inside a view* reaches it — but the
+  layout Rails wraps an action's template in (`layouts/application`,
+  or whatever `layout "base"` named) is not attributed to that
+  action. A callee rule may read the call's literals, the unit's
+  owner and the unit's key, and a layout's name is none of those:
+  it is a class-body declaration plus a convention lookup against
+  the view tree. So the layout's own effects reach a view that
+  renders it explicitly and no further.
+- **`yield` in a layout is a `String` and nothing more.** The
+  keyword is rewritten into a declared call on the view context so
+  the body parses; what the inner template produced is never
+  modelled.
+- **Unsaved render sites are not read in the editor.** The
+  render-site index reads templates and controllers from disk, so a
+  `locals:` you have typed but not saved does not reach the partial
+  until the save. A keystroke recompiles only the buffer, and a save
+  rebuilds the project's analysis as it always has. A view changed on
+  disk *without* a save the editor sees (a `git checkout`, a
+  formatter run elsewhere) recompiles every view on the next
+  publish, because a partial's locals can come from any of them. A
+  full `rigor check` does
+  the same compile work it did before — the index hands its compiled
+  sources to the unit transform rather than compiling twice.
+- **ERB only, under `app/views`.** `template_globs:` is a manifest
+  row, read without running plugin code, so it cannot consult
+  `view_search_paths:`. Haml, Slim and Jbuilder are the same seam
+  behind a different compiler and are not claimed.
 - **Implicit-self helpers only.** `*_path` / `*_url` calls with an
   explicit receiver (`Rails.application.routes.url_helpers.x_path`)
   are passed through.

data/docs/manual/plugins/rigor-active-model-serializers.md

@@ -0,0 +1,153 @@
+# rigor-active-model-serializers
+
+Teaches Rigor what `object` is inside an ActiveModel::Serializer
+subclass, so the reads below it — `object.username`,
+`object.account.display_name` — resolve against your model instead of
+dispatching on an unknown receiver. It reads source only; no
+ActiveModelSerializers runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`, alongside
+`rigor-activerecord`, which is what tells this plugin which models exist
+and what they answer:
+
+```yaml
+plugins:
+  - rigor-activerecord
+  - rigor-active-model-serializers
+```
+
+## What it does — no diagnostics
+
+The plugin emits nothing of its own. It contributes one return type and
+the gem's framework constants, so that
+
+```ruby
+class REST::AccountSerializer < ActiveModel::Serializer
+  attributes :id, :username, :display_name
+
+  def display_name
+    object.display_name
+  end
+end
+```
+
+types `object` as `Account`, and `object.display_name` as the
+`accounts.display_name` column's type. What you notice is the diagnostics
+that now CAN fire — a typo below a serializer's `object` used to be
+invisible:
+
+```text
+app/serializers/errors_serializer.rb:11:23: error: undefined method `nickname' for String [call.undefined-method]
+```
+
+and `rigor coverage` reporting a larger share of `app/serializers` as
+precise. On Mastodon that share went from 51.1 % to 53.2 % with no change
+at all to the diagnostic set
+([the measurement](../../notes/20260917-ams-object-recognizer.md)).
+
+## When `object` is typed, and when it is not
+
+Nothing in a serializer's source states which class it serializes — AMS
+binds the resource when the serializer is constructed. So the type is
+always DERIVED, and two independent things have to agree before the
+plugin contributes one:
+
+1. **The name resolves.** `<Model>Serializer` names exactly one model
+   your project has — `REST::AccountSerializer` → `Account`.
+2. **The model answers the serializer.** Every name the serializer will
+   read off its resource — the `attributes` / `attribute` / `has_many` /
+   `has_one` / `belongs_to` declarations it does not define itself, plus
+   every `object.<name>` in its body — is a column, per-column predicate,
+   association, enum, alias, scope or macro-defined method of that model,
+   or a method your project defines on it or an ancestor.
+
+One unanswered name declines the whole serializer, because the resource
+is then something else — commonly a presenter or a decorator around the
+model, which shares most of its surface and is given away by the one or
+two names that differ. On Mastodon that check is what stops
+`REST::ConversationSerializer` typing as `Conversation` when its resource
+is an `AccountConversation`.
+
+| your code | `object` types as |
+| --- | --- |
+| `REST::AccountSerializer`, `Account` exists and answers it | `Account` |
+| `Admin::AccountSerializer`, where `Admin::Account` and `Account` both exist | unchanged — the reading is ambiguous and nothing here ranks one above the other |
+| `ConversationSerializer` whose declarations `Conversation` cannot answer | unchanged (`Dynamic`) |
+| a serializer that reads nothing off its resource | unchanged — there is nothing to check the name against |
+| `ContextSerializer`, and no `Context` **model** exists | unchanged (`Dynamic`) |
+| a serializer you listed in `model_overrides` | the model you named |
+| `object` written outside a serializer, or over your own `def object` | unchanged (`Dynamic`) |
+
+A serializer is a class under `serializer_search_paths` whose superclass
+chain reaches `ActiveModel::Serializer` — including through your own base
+serializer (`class ApplicationSerializer < ActiveModel::Serializer`, then
+`class AccountSerializer < ApplicationSerializer`). A class the chain does
+not reach is not a serializer here whatever it is called: `object` is an
+ordinary method name, and a `Json::ConversationSerializer` of your own is
+entitled to define it.
+
+`class << self` and `def self.` bodies are left alone. An `object` read
+there is a `NoMethodError` at run time — AMS's reader is an instance
+method — so there is nothing to type and nothing the plugin should say
+about it.
+
+**The plugin never guesses.** Where the resource cannot be established it
+contributes nothing and `object` keeps the answer it had, because a wrong
+class here would turn every read on it into a false
+`call.undefined-method` on working code.
+
+It also does nothing at all without `rigor-activerecord`, or on a project
+with no `db/schema.rb` / `db/structure.sql`: the model set it resolves and
+checks against comes from that plugin, and is withheld when the schema is
+missing.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-active-model-serializers
+    config:
+      serializer_search_paths: ["app/serializers", "app/lib"]
+      serializer_base_classes: ["ActiveModel::Serializer"]
+      model_overrides:
+        REST::InstanceSerializer: InstancePresenter
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `serializer_search_paths` | `["app/serializers", "app/lib"]` | Where to look for serializer classes. `app/lib` is in the default set because a base serializer routinely lives outside `app/serializers` — Mastodon's `ActivityPub::Serializer`, the parent of 60 of its serializers, is one. A directory you do not have costs one probe. |
+| `serializer_base_classes` | `["ActiveModel::Serializer"]` | The roots the ancestry walk starts from. |
+| `model_overrides` | `{}` | Serializer class name → resource class name, for a serializer the derivation cannot reach — a presenter, a decorator, or a class named for a JSON shape. Your assertion; it is not re-checked. |
+
+## Limitations
+
+- **SimpleForm inputs.** `SimpleForm::Inputs::Base#object` shares the name
+  and nothing else — its resource comes from the `simple_form_for` call
+  site, not from the input class.
+- **`serializer:` / `each_serializer:` options.** They name the
+  serializer for an association, never the model for a serializer.
+- **Model surface your schema and source do not state.** A method the
+  model gets from `method_missing`, from a gem's macro `rigor-activerecord`
+  does not recognise, or from a module included at runtime is invisible to
+  the model index, so a serializer reading one is declined.
+  `rigor-activerecord` reads `delegate`, the associations a concern
+  declares in its `included do`, the Paperclip / Active Storage attachment
+  macros and `enum` value predicates
+  ([#1049](https://github.com/rigortype/rigor/issues/1049)); anything else
+  a macro defines is not folded yet.
+- **Some ways of reading the resource.** `object[:key]`, `object.title =`,
+  `object.try(:name)`, `object.present?` and an `attribute(:x) { ... }`
+  block are not read as evidence, so a serializer using one may decline
+  even where the model is right. Always the safe direction — a decline,
+  never a wrong type.
+- **Serializers for plain objects** — `ActiveModelSerializers::Model`
+  subclasses, Structs, presenters. Use `model_overrides` where the class
+  you want is a real constant you are happy to have checked.
+
+## Plugin internals
+
+The serializer discoverer / index, the ancestry closure and the contract
+surfaces this plugin exercises are in the
+[plugin's README](../../../plugins/rigor-active-model-serializers/README.md).
+To write a plugin, see [`examples/`](../../../examples/README.md) and the
+[`rigor-plugin-author`](../08-skills.md) skill.

data/docs/manual/plugins/rigor-activejob.md

@@ -95,6 +95,13 @@ nothing loads Solid Queue.
   evidence. A schedule loaded from Ruby rather than from a file under
   `recurring_paths` supplies nothing, by the same "read only what is
   written" rule.
+- **The "failed to discover jobs" warning is run-scoped.** It is
+  a fact about your configuration, not about any one source file, so
+  it is reported once per run on `.rigor.yml` rather than repeated on
+  every analysed file. It is `:warning`, so if you baselined it at its
+  old position that entry no longer matches and the row fails a
+  `--fail-on=warning` run — regenerate with `rigor baseline
+  regenerate`.
 
 ## Plugin internals