rigortype 0.2.1 → 0.2.2

data/lib/rigor/inference/method_dispatcher/shape_dispatch.rb

@@ -88,6 +88,7 @@ module Rigor
           to_h: :tuple_to_h,
           zip: :tuple_zip,
           :[] => :tuple_index,
+          slice: :tuple_index,
           fetch: :tuple_index,
           dig: :tuple_dig,
           values_at: :tuple_values_at,
@@ -842,7 +843,10 @@ module Rigor
 
           # `tuple.min` / `tuple.max` — fold when every element is
           # a `Constant` whose values share a Ruby-comparable
-          # domain. Empty tuples fold to `Constant[nil]`.
+          # domain. Empty tuples fold to `Constant[nil]`. The 1-arg
+          # `min(n)` / `max(n)` form folds to a `Tuple` of the n
+          # edge-most values in Ruby's order (`min(n)` ascending,
+          # `max(n)` descending) — the n-arg sibling of `first(n)`.
           def tuple_min(tuple, _method_name, args)
             tuple_minmax(tuple, args, :min)
           end
@@ -852,7 +856,7 @@ module Rigor
           end
 
           def tuple_minmax(tuple, args, edge)
-            return nil unless args.empty?
+            return tuple_minmax_n(tuple, args.first, edge) unless args.empty?
             return Type::Combinator.constant_of(nil) if tuple.elements.empty?
 
             values = constant_values(tuple.elements)
@@ -864,6 +868,25 @@ module Rigor
             nil
           end
 
+          # `tuple.min(n)` / `tuple.max(n)` — a `Tuple` of the n
+          # edge-most element values, delegating to Ruby's
+          # `Array#min` / `#max` for the ordering. Declines on a
+          # non-static / negative count or non-Constant elements.
+          # The result is bounded by the tuple's known arity, so no
+          # extra size cap is needed.
+          def tuple_minmax_n(tuple, arg, edge)
+            return nil unless arg.is_a?(Type::Constant) && arg.value.is_a?(Integer)
+            return nil if arg.value.negative?
+
+            values = constant_values(tuple.elements)
+            return nil if values.nil?
+
+            picked = values.public_send(edge, arg.value)
+            Type::Combinator.tuple_of(*picked.map { |v| Type::Combinator.constant_of(v) })
+          rescue StandardError
+            nil
+          end
+
           # `tuple.minmax` — the `[min, max]` pair as a 2-slot
           # `Tuple[Constant[min], Constant[max]]`, mirroring the
           # `Range#minmax` fold. Every element must be a `Constant`
@@ -1201,6 +1224,13 @@ module Rigor
           # indices still fall through because the same handler serves
           # `fetch`, while statically nil slices can be represented
           # precisely for `[]`.
+          # `[]` and its exact alias `slice` share the index / Range /
+          # start-length folding. `fetch` routes here too but stays
+          # integer-index-only: the Range and start-length branches gate
+          # on this selector set, which `fetch` is deliberately not in.
+          SLICE_SELECTORS = Set[:[], :slice].freeze
+          private_constant :SLICE_SELECTORS
+
           def tuple_index(tuple, method_name, args)
             case args.size
             when 1 then tuple_single_index(tuple, method_name, args.first)
@@ -1211,17 +1241,18 @@ module Rigor
           def tuple_single_index(tuple, method_name, arg)
             return nil unless arg.is_a?(Type::Constant)
 
-            return tuple_range_slice(tuple, arg.value) if method_name == :[] && arg.value.is_a?(Range)
-            return nil unless arg.value.is_a?(Integer)
+            value = arg.value
+            return tuple_range_slice(tuple, value) if SLICE_SELECTORS.include?(method_name) && value.is_a?(Range)
+            return nil unless value.is_a?(Integer)
 
-            idx = normalise_index(arg.value, tuple.elements.size)
+            idx = normalise_index(value, tuple.elements.size)
             return nil unless idx
 
             tuple.elements[idx]
           end
 
           def tuple_start_length_slice(tuple, method_name, args)
-            return nil unless method_name == :[]
+            return nil unless SLICE_SELECTORS.include?(method_name)
 
             start, length = args
             return nil unless start.is_a?(Type::Constant) && length.is_a?(Type::Constant)

data/lib/rigor/inference/scope_indexer.rb

@@ -118,10 +118,12 @@ module Rigor
         # table to suppress false positives for methods the
         # user has defined but no RBS sig describes. Merged
         # UNDER the cross-file pre-pass seed; details: merge_project_method_indexes.
-        discovered_methods = deep_merge_class_methods(
-          default_scope.discovered_methods, build_discovered_methods(root)
-        )
-        seeded_scope = seeded_scope.with_discovery(seeded_scope.discovery.with(discovered_methods: discovered_methods))
+        # One combined descent yields both the discovered-methods existence
+        # table and the instance def-node table — see
+        # {#build_methods_and_def_nodes}. `seed_discovered_methods` seeds the
+        # former onto the scope and returns the def-node table for
+        # `merge_project_method_indexes` below.
+        seeded_scope, file_def_nodes = seed_discovered_methods(seeded_scope, default_scope, root)
 
         # v0.0.2 #5 + ADR-24 slice 2 — record per-instance-method
         # def nodes, the class -> superclass map, and the
@@ -134,7 +136,7 @@ module Rigor
         # table. Seeded inside `merge_project_method_indexes` so the
         # per-file visibilities merge OVER the cross-file project seed
         # rather than overwriting it.
-        seeded_scope = merge_project_method_indexes(seeded_scope, default_scope, root)
+        seeded_scope = merge_project_method_indexes(seeded_scope, default_scope, root, file_def_nodes)
 
         table = {}.compare_by_identity
         table.default = seeded_scope
@@ -160,6 +162,19 @@ module Rigor
         table
       end
 
+      # Runs the combined methods/def-nodes descent (one walk of the file),
+      # seeds the discovered-methods existence table onto `seeded_scope`
+      # (merged UNDER the cross-file pre-pass seed `default_scope` carries),
+      # and returns `[scope, file_def_nodes]` so the caller can thread the
+      # def-node table into {#merge_project_method_indexes} without walking
+      # the file a second time.
+      def seed_discovered_methods(seeded_scope, default_scope, root)
+        file_methods, file_def_nodes = build_methods_and_def_nodes(root)
+        discovered_methods = deep_merge_class_methods(default_scope.discovered_methods, file_methods)
+        scope = seeded_scope.with_discovery(seeded_scope.discovery.with(discovered_methods: discovered_methods))
+        [scope, file_def_nodes]
+      end
+
       # ADR-48 Struct slice 3 — installs the top-level fold-safe-local set
       # ({Inference::StructFoldSafety}). Struct member layouts of constant
       # receivers are resolved through the side-table the seeded scope carries.
@@ -179,9 +194,9 @@ module Rigor
       # `discovered_def_index_for_paths` seed carried on
       # `default_scope` — same-file declarations win per entry,
       # the cross-file seed supplies sibling-file ancestors.
-      def merge_project_method_indexes(seeded_scope, default_scope, root)
+      def merge_project_method_indexes(seeded_scope, default_scope, root, file_def_nodes)
         def_nodes = default_scope.discovered_def_nodes.merge(
-          build_discovered_def_nodes(root)
+          file_def_nodes
         ) { |_class, cross_file, per_file| cross_file.merge(per_file) }
         singleton_def_nodes = default_scope.discovered_singleton_def_nodes.merge(
           build_discovered_singleton_def_nodes(root)
@@ -1406,16 +1421,29 @@ module Rigor
         Type::Combinator.singleton_of(full)
       end
 
-      # Slice 7 phase 12 — in-source method discovery pre-pass.
-      # Walks every class/module body and records the methods
-      # introduced via `Prism::DefNode` (instance + singleton)
-      # and via recognised `define_method(:name) { ... }` calls.
-      # The returned table maps qualified class name to a
-      # `Hash[Symbol, :instance | :singleton]`.
-      def build_discovered_methods(root)
-        accumulator = {}
-        walk_methods(root, [], false, accumulator)
-        accumulator.transform_values(&:freeze).freeze
+      # Slice 7 phase 12 — in-source method discovery pre-pass, fused with
+      # the instance-method def-node pre-pass (v0.0.2 #5). One descent
+      # produces BOTH tables the per-file `index` and the cross-file
+      # pre-pass each need together:
+      #
+      #   - `methods`   : `{class_name => {method => :instance | :singleton}}`
+      #     for every `def` / `define_method(:name)` / `attr_*` / `alias` /
+      #     Data/Struct-member reader (the undefined-method existence table).
+      #   - `def_nodes` : `{class_name => {method => Prism::DefNode}}` for
+      #     every instance-side `def` (the inter-procedural return-inference
+      #     table; singleton defs and `define_method` are intentionally
+      #     skipped — `record_def_node` filters them).
+      #
+      # `walk_methods` and `walk_def_nodes` had byte-identical class /
+      # module / singleton / meta-block descents (both stop at `DefNode`),
+      # so a single combined walk records both accumulators at once instead
+      # of traversing every file twice.
+      def build_methods_and_def_nodes(root)
+        methods = {}
+        def_nodes = {}
+        walk_methods_and_def_nodes(root, [], false, methods, def_nodes)
+        apply_alias_def_nodes(root, def_nodes)
+        [methods.transform_values(&:freeze).freeze, def_nodes.transform_values(&:freeze).freeze]
       end
 
       # Merges two `class_name => { method => kind }` tables, unioning
@@ -1431,7 +1459,14 @@ module Rigor
       end
 
       # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize, Metrics/PerceivedComplexity
-      def walk_methods(node, qualified_prefix, in_singleton_class, accumulator)
+      # Combined `walk_methods` + `walk_def_nodes` descent. The two walks
+      # had identical class / module / singleton-class / meta-block
+      # traversals and both stopped at `DefNode`; the only divergences are
+      # leaf actions (recorded into the right accumulator) and the original
+      # `walk_methods` returning at `AliasMethodNode` (its symbol-only
+      # children carry no def / class node, so not descending them is
+      # byte-identical for `def_nodes` too). See {#build_methods_and_def_nodes}.
+      def walk_methods_and_def_nodes(node, qualified_prefix, in_singleton_class, methods_acc, def_nodes_acc)
         return unless node.is_a?(Prism::Node)
 
         case node
@@ -1439,40 +1474,40 @@ module Rigor
           name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             child_prefix = qualified_prefix + [name]
-            record_meta_superclass_members(node, child_prefix, accumulator) if node.is_a?(Prism::ClassNode)
-            walk_methods(node.body, child_prefix, false, accumulator) if node.body
+            record_meta_superclass_members(node, child_prefix, methods_acc) if node.is_a?(Prism::ClassNode)
+            walk_methods_and_def_nodes(node.body, child_prefix, false, methods_acc, def_nodes_acc) if node.body
             return
           end
         when Prism::SingletonClassNode
           if node.body
             singleton_prefix = singleton_class_prefix(node, qualified_prefix)
             if singleton_prefix
-              walk_methods(node.body, singleton_prefix, true, accumulator)
+              walk_methods_and_def_nodes(node.body, singleton_prefix, true, methods_acc, def_nodes_acc)
               return
             end
           end
         when Prism::ConstantWriteNode
           if meta_new_block_body(node)
             child_prefix = qualified_prefix + [node.name.to_s]
-            walk_methods(meta_new_block_body(node), child_prefix, false, accumulator)
+            walk_methods_and_def_nodes(meta_new_block_body(node), child_prefix, false, methods_acc, def_nodes_acc)
             return
           end
         when Prism::DefNode
-          record_def_method(node, qualified_prefix, in_singleton_class, accumulator)
+          record_def_method(node, qualified_prefix, in_singleton_class, methods_acc)
+          record_def_node(node, qualified_prefix, in_singleton_class, def_nodes_acc)
           return
         when Prism::AliasMethodNode
-          record_alias_method(node, qualified_prefix, in_singleton_class, accumulator)
+          record_alias_method(node, qualified_prefix, in_singleton_class, methods_acc)
           return
         when Prism::CallNode
-          record_define_method(node, qualified_prefix, in_singleton_class, accumulator) if node.name == :define_method
+          record_define_method(node, qualified_prefix, in_singleton_class, methods_acc) if node.name == :define_method
           if ATTR_MACROS.include?(node.name)
-            record_attr_methods(node, qualified_prefix, in_singleton_class,
-                                accumulator)
+            record_attr_methods(node, qualified_prefix, in_singleton_class, methods_acc)
           end
         end
 
         node.compact_child_nodes.each do |child|
-          walk_methods(child, qualified_prefix, in_singleton_class, accumulator)
+          walk_methods_and_def_nodes(child, qualified_prefix, in_singleton_class, methods_acc, def_nodes_acc)
         end
       end
 
@@ -1606,57 +1641,6 @@ module Rigor
         end
       end
 
-      # v0.0.2 #5 — instance-side def-node recording. Walks
-      # class bodies the same way as `build_discovered_methods`
-      # but records the actual `Prism::DefNode` for each
-      # **instance** method so `ExpressionTyper` can re-type
-      # the body at the call site for inter-procedural return
-      # inference. Singleton methods and `define_method` calls
-      # are intentionally skipped: the inference path needs a
-      # statically introspectable body, and singleton dispatch
-      # has its own complications (Class / Module ancestry)
-      # the first-iteration rule does not yet model.
-      def build_discovered_def_nodes(root)
-        accumulator = {}
-        walk_def_nodes(root, [], false, accumulator)
-        apply_alias_def_nodes(root, accumulator)
-        accumulator.transform_values(&:freeze).freeze
-      end
-
-      def walk_def_nodes(node, qualified_prefix, in_singleton_class, accumulator)
-        return unless node.is_a?(Prism::Node)
-
-        case node
-        when Prism::ClassNode, Prism::ModuleNode
-          name = Source::ConstantPath.qualified_name(node.constant_path)
-          if name
-            child_prefix = qualified_prefix + [name]
-            walk_def_nodes(node.body, child_prefix, false, accumulator) if node.body
-            return
-          end
-        when Prism::SingletonClassNode
-          if node.body
-            singleton_prefix = singleton_class_prefix(node, qualified_prefix)
-            if singleton_prefix
-              walk_def_nodes(node.body, singleton_prefix, true, accumulator)
-              return
-            end
-          end
-        when Prism::ConstantWriteNode
-          if meta_new_block_body(node)
-            child_prefix = qualified_prefix + [node.name.to_s]
-            walk_def_nodes(meta_new_block_body(node), child_prefix, false, accumulator)
-            return
-          end
-        when Prism::DefNode
-          record_def_node(node, qualified_prefix, in_singleton_class, accumulator)
-          return
-        end
-
-        node.compact_child_nodes.each do |child|
-          walk_def_nodes(child, qualified_prefix, in_singleton_class, accumulator)
-        end
-      end
       # v0.0.3 A — sentinel key under which `record_def_node`
       # files DefNodes that live outside any class / module
       # body (top-level helpers, `def`s nested inside DSL
@@ -2385,7 +2369,13 @@ module Rigor
       # the override-visibility-reduced rule can read an ancestor's
       # visibility declared in a sibling file.
       def accumulate_project_index(acc, path, root)
-        merge_discovered_defs(acc[:def_nodes], acc[:def_sources], path, root)
+        # One combined descent yields both the methods existence table and
+        # the def-node table; the latter is also consumed by
+        # `record_class_sources`, so a def-dense file is walked once here
+        # instead of three times (methods + def-nodes ×2). See
+        # {#build_methods_and_def_nodes}.
+        file_methods, file_def_nodes = build_methods_and_def_nodes(root)
+        merge_discovered_defs(acc[:def_nodes], acc[:def_sources], path, file_def_nodes)
         build_discovered_singleton_def_nodes(root).each do |class_name, methods|
           (acc[:singleton_def_nodes][class_name] ||= {}).merge!(methods)
         end
@@ -2395,20 +2385,28 @@ module Rigor
         includes.each do |class_name, mods|
           acc[:includes][class_name] = ((acc[:includes][class_name] || []) + mods).uniq
         end
-        record_class_sources(acc[:class_sources], path, root, superclasses, includes)
-        merge_class_keyed_index_tables(acc, root)
+        record_class_sources(acc[:class_sources], path, root, superclasses, includes, file_def_nodes)
+        merge_class_keyed_index_tables(acc, root, file_methods)
+        merge_member_layout_tables(acc, root)
+      end
+
+      # Folds one file's Data + Struct member-layout tables into the
+      # cross-file accumulator (kept out of {#accumulate_project_index} to
+      # hold its ABC budget).
+      def merge_member_layout_tables(acc, root)
         acc[:data_member_layouts].merge!(build_data_member_layouts(root))
         acc[:struct_member_layouts].merge!(build_struct_member_layouts(root))
       end
 
       # Folds the per-class method-visibility and method-existence tables of
       # one file into the cross-file accumulator (kept out of
-      # {#accumulate_project_index} to hold its ABC budget).
-      def merge_class_keyed_index_tables(acc, root)
+      # {#accumulate_project_index} to hold its ABC budget). `file_methods`
+      # is the existence table from the combined methods/def-nodes descent.
+      def merge_class_keyed_index_tables(acc, root, file_methods)
         build_discovered_method_visibilities(root).each do |class_name, table|
           (acc[:method_visibilities][class_name] ||= {}).merge!(table)
         end
-        build_discovered_methods(root).each do |class_name, table|
+        file_methods.each do |class_name, table|
           (acc[:methods][class_name] ||= {}).merge!(table)
         end
       end
@@ -2423,13 +2421,13 @@ module Rigor
       # dependency recording (ADR-46). The class-declaration walk
       # (`collect_class_decls`) catches bodyless / def-less reopenings the
       # other three builders miss.
-      def record_class_sources(class_sources, path, root, superclasses, includes)
+      def record_class_sources(class_sources, path, root, superclasses, includes, file_def_nodes)
         names = Set.new
         collect_class_decls(root, [], decls = {})
         names.merge(decls.keys)
         names.merge(superclasses.keys)
         names.merge(includes.keys)
-        names.merge(build_discovered_def_nodes(root).keys)
+        names.merge(file_def_nodes.keys)
         names.each { |name| (class_sources[name] ||= Set.new) << path }
       end
 
@@ -2438,8 +2436,8 @@ module Rigor
       # seen `"path:line"` definition site in `def_sources` (ADR-17 —
       # the un-registered-project-patch signal `call.undefined-method`
       # and `rigor triage` key on).
-      def merge_discovered_defs(def_nodes, def_sources, path, root)
-        build_discovered_def_nodes(root).each do |class_name, methods|
+      def merge_discovered_defs(def_nodes, def_sources, path, file_def_nodes)
+        file_def_nodes.each do |class_name, methods|
           (def_nodes[class_name] ||= {}).merge!(methods)
           sources = (def_sources[class_name] ||= {})
           methods.each do |method_name, def_node|

data/lib/rigor/plugin/isolation.rb

@@ -12,13 +12,13 @@ module Rigor
     # `exe/rigor` launcher maps `.rigor.yml`'s `plugins_isolation:` onto it
     # before re-exec). Three backends behind one interface:
     #
-    # - `none` (**default**) — load into the main space and call directly.
-    #   Lowest cost; no isolation. Fine for the common case because the
-    #   invoked library is trusted + pure.
+    # - `none` — load into the main space and call directly.
+    #   Lowest cost; no isolation. Used as the fallback where fork is
+    #   unavailable; fine because the invoked library is trusted + pure.
     # - `ruby_box` — call inside a {Box} (`Ruby::Box`, `RUBY_BOX=1`). Isolates
     #   core-class monkey-patches + lets gem versions coexist, but a native
     #   crash in the boxed work still takes the process down (in-process).
-    # - `process` — call in a forked worker ({Process}); returns data over a
+    # - `process` (**default**) — call in a forked worker ({Process}); returns data over a
     #   pipe. The strongest: a child crash (even `SIGSEGV`) is contained —
     #   the parent survives and declines. Higher cost (fork + IPC).
     #
@@ -73,7 +73,7 @@ module Rigor
       end
 
       # `none` — load the trusted library into the main space and call it
-      # directly. No isolation; lowest cost; the current default behaviour.
+      # directly. No isolation; lowest cost; the fork-unavailable fallback.
       module Direct
         module_function
 

data/lib/rigor/plugin/loader.rb

@@ -183,8 +183,10 @@ module Rigor
           Plugin.registered_for(newly_registered.first)
         else
           raise LoadError.new(
-            "plugin gem #{entry[:gem].inspect} registered multiple plugins " \
-            "(#{newly_registered.sort.inspect}); disambiguate with an explicit `id:` field",
+            "plugin gem #{entry[:gem].inspect} bundles #{newly_registered.size} plugins " \
+            "(#{newly_registered.sort.inspect}) and cannot be activated as a single `plugins:` entry — " \
+            "it is a convenience meta-gem. List the individual plugin gems you want in `plugins:` " \
+            "(e.g. `rigor-#{newly_registered.min}`), or select one with an explicit `id:` field.",
             plugin_ref: entry[:gem]
           )
         end

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/skills/rigor-ask/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: rigor-ask
+description: |
+  Rigor is a niche, fast-moving Ruby type checker; its rules, flags, and type behaviour are version-specific, so what you "remember" about it is likely wrong or stale — do NOT answer from memory or guess. For ANY question about Rigor, use this skill and investigate procedurally: run `rigor docs` (handbook + manual, bundled OFFLINE and version-matched), `rigor explain` for a diagnostic id, and for the user's own code `rigor check` / `annotate` / `type-of`, then answer only from what you read. Covers: why a line is flagged or if it's a false positive; the type model (narrowing, refinements, `Dynamic`, RBS); config keys, flags, baselines; comparisons to Sorbet, Steep, mypy, PHPStan; whether it handles Rails, RSpec, or a gem; writing an RBS signature; "what is Rigor / why use it / is it right for us?". Trigger on any Rigor mention seeking understanding — even casual, comparative, or grumbling. Skip only when Rigor isn't mentioned, or it's purely "set it up / fix / reduce it for me" (→ rigor-next-steps).
+license: MPL-2.0
+metadata:
+  version: 0.2.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Ask Rigor anything
+
+Someone has a question about Rigor. It might be about a diagnostic, the
+type model, a flag, how Rigor stacks up against another type checker,
+whether Rigor can handle their framework, how to type a method — or just
+"what is this, and should I use it?" Whatever it is, **answer from the
+source, not from memory.**
+
+Two things make that easy, and you have both offline:
+
+- **Rigor's own docs ship inside the gem.** `rigor docs` serves the full
+  handbook and manual, always matching the user's installed version, no
+  network. This is the authoritative copy: a rule's exact firing
+  condition, a flag's spelling, a config default — all drift release to
+  release, and `rigor docs` is the copy that shipped with *this* install,
+  so an answer drawn from it cannot disagree with the binary they run.
+- **Rigor can read the user's actual code.** When the question is about
+  *their* program — "why is this flagged?", "what type does Rigor see
+  here?", "how well-typed is my project?" — `rigor check` / `annotate` /
+  `type-of` / `triage` / `coverage` answer from what Rigor inferred. A
+  concrete inferred type beats any abstract explanation.
+
+This is the user's shortcut: they only ever need to remember two skills —
+**`rigor-next-steps`** ("what should we do next?") and **`rigor-ask`**
+("answer this about Rigor"). They ask in plain language; *you* turn it
+into the right lookup or analysis so they never have to remember the
+command.
+
+## The toolbox
+
+Everything here is read-only and needs no network.
+
+### Reading the docs
+
+| Command | Use |
+| --- | --- |
+| `rigor docs` | The offline doc index (`llms.txt`) — the map. Start here when you don't know which page. |
+| `rigor docs --list [manual\|handbook]` | List every bundled page with its path (optionally one category). |
+| `rigor docs <name>` | Print a page. `<name>` is a category-qualified path (`handbook/03-narrowing`), a prefixed basename (`03-narrowing`), or a unique short name (`narrowing`). Pages that exist in **both** trees (e.g. `plugins`) must be qualified — `manual/07-plugins` vs `handbook/09-plugins`. |
+| `rigor explain <rule>` | The catalogue entry for a diagnostic id (`rigor explain call.undefined-method`) — what it means, why it fires, how to address it. |
+
+### Grounding the answer in the user's code
+
+| Command | Use |
+| --- | --- |
+| `rigor check <path>` | Run the analysis. Scope it to a file or directory for a quick answer — don't analyse the whole project just to settle one question. `--format json` exposes structured fields (`receiver_type`, `method_name`, `evidence_tier`, …). |
+| `rigor annotate <file>` | Reprint the file with the inferred type of each line in the margin — *what Rigor actually sees*. |
+| `rigor type-of <file>:<line>:<col>` | The inferred type at one position. |
+| `rigor triage` | Cluster the project's diagnostics by rule / receiver / method — for "what's the shape of my errors?". |
+| `rigor coverage [--protection]` | Type / type-protection coverage — for "how well-typed is this?" and "where are the holes?". |
+| `rigor plugins` | Which plugins are installed and enabled *here* — the honest answer to "does Rigor support <gem/framework>?". |
+| `rigor sig-gen <path>` | Generate RBS for code — for "how do I type this?". Offer it and show the result; this project prefers sig-gen over hand-written RBS. |
+
+## Where the answer lives
+
+Classify the question, then go to the page(s) — and, for anything about
+*their* code, the command(s) — that own it. When unsure where a page is,
+`rigor docs` (the index) or `rigor docs --list handbook` routes you.
+
+| The question is about… | Go to |
+| --- | --- |
+| **A specific diagnostic** — "why is this flagged?", "what does this error mean?", "is this a false positive?" | `rigor explain <rule>`, then `rigor docs diagnostics`. If it's *their* code, also `rigor annotate <file>` / `rigor type-of` to see the inferred types the rule fired on. |
+| **The type model / a concept** — narrowing, refinements, tuple & hash shapes, `Dynamic`, RBS interop, lightweight HKT | The handbook: `rigor docs --list handbook`, then the chapter — `handbook/03-narrowing`, `04-tuples-and-shapes`, `07-rbs-and-extended`, `12-lightweight-hkt`, … |
+| **Operating Rigor** — a config key, CLI flag, baseline, plugins, CI, caching | The manual: `rigor docs configuration`, `cli-reference`, `baseline`, `manual/07-plugins`, `ci`, `caching`, `troubleshooting`. |
+| **How Rigor compares to another tool** — Sorbet, Steep, RBS, TypeScript, mypy, PHPStan, TypeProf, Go, Rust, Java/C# | The chapter/appendix written for exactly that: `handbook/10-sorbet`, `appendix-steep`, `appendix-typescript`, `appendix-mypy`, `appendix-phpstan`, `appendix-typeprof`, `appendix-rust`, `appendix-go`, `appendix-java-csharp` (`rigor docs --list handbook` shows them all). |
+| **Whether Rigor can do X** — generics, Rails, RSpec, a specific gem, concurrency | The handbook for the language feature; for framework/gem support, **`rigor plugins`** (what's actually available in *this* install) plus the per-plugin page `rigor docs rigor-<gem>` (e.g. `rigor docs rigor-sidekiq`) and the catalogue `rigor docs --list manual`. |
+| **Writing a type / RBS** — "how do I type this?", an annotation, a signature | Handbook `07-rbs-and-extended` + `11-sig-gen`; manual `rbs-extended-annotations`. Then offer `rigor sig-gen <path>` to generate it (preferred over hand-RBS) and show the output. |
+| **What Rigor is / why use it / is it right for me** | Handbook `01-getting-started` for the pitch, `handbook/02-everyday-types` for a quick mental model of the type zoo. Ground "is it right for *my* project" in a scoped `rigor check` / `rigor coverage` so they see Rigor on their real code. |
+
+## Answer from the page, name the page
+
+Quote or paraphrase the relevant passage and **say which page you drew
+from** (e.g. "per `rigor docs handbook/03-narrowing` …"), so the user can
+re-read it with the same command. Prefer the doc's own wording over a
+remembered approximation. When you ran a command against their code, show
+the relevant line of output — a concrete inferred type is more convincing
+than prose, and it proves the answer rather than asserting it.
+
+## When the question is really "do X for me"
+
+Some questions are a task in disguise: *"how do I get Rigor into CI?"*,
+*"how do I shrink this baseline?"*, *"how do I set Rigor up here?"* The
+useful reply is **short**: orient the user — what the thing is, the one
+decision that actually matters, the rough shape of it — then **hand the
+doing to the skill built for it.** Resist pasting the full procedure
+inline (the entire CI workflow YAML, the whole baseline-reduction loop):
+that skill owns the steps, keeps them correct, and updates as the tool
+moves, so duplicating them here only bloats the answer and drifts out of
+date. The line is *explaining* the thing (yours) versus *wiring it in*
+(the setup skill's).
+
+A good hand-off is two or three sentences of orientation plus the pointer:
+
+- setup / "what next?" → **`rigor-next-steps`** (it probes the project and routes)
+- CI → **`rigor-ci-setup`** · editor → **`rigor-editor-setup`** · MCP agent → **`rigor-mcp-setup`**
+- baseline reduction → **`rigor-baseline-reduce`** · coverage holes → **`rigor-protection-uplift`**
+- a missing gem/DSL → **`rigor-plugin-author`** · monkey-patch clusters → **`rigor-monkeypatch-resolve`**
+
+When in doubt, give less and point — it respects the user's "two skills
+to remember" promise and keeps each answer to the part only `rigor-ask`
+can give.
+
+## If the docs don't cover it
+
+The bundled set is the **drive-Rigor** corpus (manual + handbook). The
+normative **type specification**, the internal spec, and the ADRs are
+contributor-facing and stay web-only — they are *not* in `rigor docs`; if
+a question genuinely needs them, say so and point at
+<https://rigor.typedduck.fail/llms.txt> rather than guessing.
+
+But before you defer, remember Rigor installs from RubyGems **with its
+full source** — the per-plugin pages under the gem's `docs/manual/plugins/`,
+the analyzer and plugin code under `lib/`. For a detail no doc page spells
+out (a plugin's exact rule, a default baked into the code), reading the
+bundled file directly is a perfectly good way to ground the answer, and
+beats a guess. The rule that never bends: **never invent a flag, rule id,
+config key, behaviour, or command output** — read the page, read the
+source, or run the command, and quote only output you actually saw. A
+confident wrong answer about a type checker is worse than "let me check."
+
+## Examples
+
+**A diagnostic on their code** — *"Why is Rigor flagging `s.lenght`?"*
+
+```sh
+rigor explain call.undefined-method   # what the rule means and why it fires
+rigor annotate demo.rb                # the inferred type of `s` on that line
+```
+
+Answer from both: Rigor inferred a concrete `String` receiver for `s`,
+and `String` has no `lenght` (a typo for `length`) — grounded in what
+`annotate` showed, not in a guess.
+
+**A comparison** — *"How is Rigor different from Sorbet?"*
+
+```sh
+rigor docs handbook/10-sorbet         # the chapter written for this
+```
+
+Answer from the chapter's framing (RBS-superset, gradual `Dynamic`,
+inference-first) rather than a remembered summary, and name it so they
+can read on.
+
+**A capability** — *"Does Rigor understand our Sidekiq workers?"*
+
+```sh
+rigor plugins                          # is rigor-sidekiq enabled in THIS project?
+rigor docs rigor-sidekiq               # the per-plugin page: what it teaches Rigor
+```
+
+Answer from what's actually installed, plus — if useful — a scoped
+`rigor check app/workers` so they see Rigor on their real workers.
+
+**Authoring** — *"How do I type this method?"*
+
+```sh
+rigor sig-gen path/to/file.rb          # generate the RBS, show it
+rigor docs handbook/07-rbs-and-extended
+```
+
+Generate it, show the signature, and explain it from the handbook —
+preferring sig-gen's output over hand-written RBS.