rigortype 0.2.1 → 0.2.3

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/triage/catalogue.rb

@@ -87,12 +87,27 @@ module Rigor
       GENUINE_BUG_MAX_COUNT = 5    # rule total ≤ N → "likely genuine bug"
       private_constant :SYSTEMIC_THRESHOLD, :MONKEY_PATCH_MIN_FILES, :GENUINE_BUG_MAX_COUNT
 
+      # WD6 (ADR-23): H5 (systemic cluster) and H6 (genuine bugs) are
+      # the only count-based, severity-agnostic recognisers, so they
+      # alone risk reading plugin recognition trace (`:info`
+      # `*.model-call` / `*.helper`, …) as a "systemic cluster" or a
+      # "genuine bug" — frightening working code. They are guarded
+      # against `:info` unless `include_info` restores the pre-v0.2.3
+      # behaviour. Every other recogniser keys on an error/warning rule
+      # (H1/H2/H2K/H4/H7) or intentionally reads an info notice
+      # (H3 — the `gem-without-rbs` `rbs.coverage.missing-gem`), so the
+      # full pool is correct for them.
+      INFO_GUARDED = %i[h5_systemic_cluster h6_genuine_bugs].freeze
+      private_constant :INFO_GUARDED
+
       # @param diagnostics [Array<Analysis::Diagnostic>]
+      # @param include_info [Boolean] let H5/H6 see `:info` diagnostics
       # @return [Array<Hint>]
-      def recognise(diagnostics)
+      def recognise(diagnostics, include_info: false)
         claimed = {}.compare_by_identity
         recognisers.filter_map do |recogniser|
           pool = diagnostics.reject { |d| claimed[d] }
+          pool = pool.reject { |d| d.severity == :info } if INFO_GUARDED.include?(recogniser) && !include_info
           hint, matched = send(recogniser, pool)
           next unless hint
 

data/lib/rigor/triage.rb

@@ -26,21 +26,40 @@ module Rigor
     # receiver); `files` is the distinct-file count (a systemic vs.
     # localised signal); `rules` is the per-rule breakdown.
     Selector = Data.define(:receiver, :method_name, :count, :files, :rules)
-    Report = Data.define(:summary, :distribution, :selectors, :hotspots, :hints)
+    Report = Data.define(:summary, :distribution, :selectors, :hotspots, :hints, :include_info)
 
     module_function
 
+    # WD6 (ADR-23): the volume views — distribution / selectors /
+    # hotspots — route only the *actionable* diagnostics (error +
+    # warning) by default. Plugin-emitted `:info` diagnostics are
+    # overwhelmingly recognition trace (`plugin.activerecord.model-call`,
+    # `plugin.rails-routes.helper`, …) — positive "Rigor resolved this
+    # call" records, not problems — and on a real Rails app they swamp
+    # the genuine error/warning signal (the field trip: 257 of 267
+    # diagnostics were such trace) and invert the hotspot ranking
+    # towards the files with the *most working* code. The summary still
+    # reports the full info count, and `include_info: true` (the
+    # `--include-info` flag) restores the pre-v0.2.3 behaviour. Hints
+    # always see the full stream so the `gem-without-rbs` notice (an
+    # info-severity `rbs.coverage.missing-gem`) survives; the
+    # count-based H5/H6 recognisers guard against info themselves so
+    # recognition trace never reads as a bug.
+    #
     # @param diagnostics [Array<Analysis::Diagnostic>]
     # @param top [Integer] hotspot-file cap
     # @param hints [Boolean] run the heuristic catalogue
+    # @param include_info [Boolean] route info into the volume views
     # @return [Report]
-    def analyze(diagnostics, top: 10, hints: true)
+    def analyze(diagnostics, top: 10, hints: true, include_info: false)
+      routed = include_info ? diagnostics : diagnostics.reject { |d| d.severity == :info }
       Report.new(
         summary: build_summary(diagnostics),
-        distribution: build_distribution(diagnostics),
-        selectors: build_selectors(diagnostics),
-        hotspots: build_hotspots(diagnostics, top),
-        hints: hints ? Catalogue.recognise(diagnostics) : []
+        distribution: build_distribution(routed),
+        selectors: build_selectors(routed),
+        hotspots: build_hotspots(routed, top),
+        hints: hints ? Catalogue.recognise(diagnostics, include_info: include_info) : [],
+        include_info: include_info
       )
     end
 
@@ -150,7 +169,11 @@ module Rigor
         "hotspots" => report.hotspots.map do |h|
           { "file" => h.file, "count" => h.count, "by_rule" => h.by_rule }
         end,
-        "hints" => report.hints.map(&:to_h)
+        "hints" => report.hints.map(&:to_h),
+        # WD6: false means distribution / selectors / hotspots above
+        # exclude `:info` (their counts will not sum to summary.total);
+        # the summary's `info` field still reports the full count.
+        "include_info" => report.include_info
       }
     end
   end

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 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.

data/skills/rigor-doctor/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: rigor-doctor
+description: |
+  Validate that a project's Rigor setup is actually healthy — config parses with no silently-inert values, every configured plugin loads, the baseline is not stale, and the bundled paths resolve — by running Rigor's existing validators and interpreting them. Triggers: "is my Rigor setup correct?", "check my rigor config", "rigor diagnostics look wrong / suspicious", "validate rigor setup", "why is rigor reporting nothing / everything?". NOT for first-time setup (use rigor-project-init) or for working real diagnostics down (use rigor-baseline-reduce).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Doctor
+
+`rigor skill describe` reports what *exists* (presence checks). This skill
+goes a level deeper: it *runs* Rigor's validators to confirm the setup is
+actually working — the difference between "a `.rigor.yml` is present" and
+"it parses, loads its plugins, and analyses the right files." Use it when
+the diagnostics look wrong (suspiciously zero, or suspiciously many) or
+after editing the config.
+
+It needs **no special command** — it orchestrates checks Rigor already
+ships and interprets the results.
+
+## Checks
+
+### 1. Config resolves with nothing silently inert
+
+```sh
+rigor check --format json   # read the `config_warnings` array
+```
+
+`rigor check` audits the config and emits `config_warnings` for the typo
+class whose only symptom is a confusing downstream error: a
+`signature_paths:` that is missing / not a directory / holds no `.rbs`
+(which would turn every covered call into a false `call.undefined-method`
+at `evidence_tier: high`), a `libraries:` name RBS does not recognise, a
+`disable:` / `severity_overrides:` id naming no real rule, or a missing
+`bundler` / `rbs_collection` path. **Each warning here is a real
+misconfiguration — fix it.** None appearing is the healthy state.
+
+### 2. Every configured plugin loads
+
+```sh
+rigor plugins --strict
+```
+
+Reports the activation status of each plugin in `plugins:`; `--strict`
+exits non-zero on any failure. A failure is usually a misspelled id or a
+plugin whose `signature_paths:` did not resolve. Fix it, or the plugin's
+type knowledge is silently absent.
+
+### 3. The baseline is not stale (if one exists)
+
+```sh
+rigor baseline drift
+```
+
+Shows whether the live diagnostics have drifted from `.rigor-baseline.yml`
+— entries the baseline ignores that no longer occur (safe to prune) and
+new diagnostics outside the envelope. A large drift means the baseline
+needs regenerating (often after an upgrade — see `rigor-upgrade`).
+
+### 4. The analysis is actually seeing your code
+
+```sh
+rigor check --format json   # check the "Ruby source files" count
+```
+
+If the file count is `0` or far below your project size, `paths:` /
+`exclude:` are mis-scoped, or the command is running from the wrong
+directory. The analysis is only as good as the files it reads.
+
+## Interpreting the result
+
+- **All clean** → the setup is healthy; any diagnostics are about the
+  code, not the configuration. Move on to `rigor-baseline-reduce` or
+  `rigor-protection-uplift`.
+- **A `config_warning` or a plugin failure** → that is the real problem;
+  fixing it usually resolves a whole cluster of confusing downstream
+  diagnostics at once.
+
+For deeper symptoms (hover shows `untyped` everywhere, completion empty,
+LSP silent) see the manual's troubleshooting:
+<https://github.com/rigortype/rigor/blob/master/docs/manual/13-troubleshooting.md>
+
+## Next step
+
+Re-run `rigor skill describe` for the recommended next move.

data/skills/rigor-editor-setup/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: rigor-editor-setup
+description: |
+  Wire Rigor's bundled language server (`rigor lsp`) into the developer's editor for live diagnostics, hover-to-type, outline, and type-aware completion. The per-editor config snippets live in the manual; this skill identifies the editor, applies the right one, and verifies the server attaches. Triggers: "set up Rigor in my editor", "rigor LSP / language server", "live Rigor diagnostics in VS Code / Neovim / Helix / Emacs", "hover types in my editor". NOT for CI integration (use rigor-ci-setup) or first-time project setup (use rigor-project-init).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Editor Setup
+
+`rigor lsp` is the in-process Language Server bundled with the
+`rigortype` gem. It speaks LSP over stdio and turns Rigor's analyzer
+into a live editor experience: diagnostics as you type, hover-to-type,
+an outline view, and type-aware completion. This skill wires it into the
+developer's editor.
+
+The authoritative, per-editor configuration lives in the manual. With
+Rigor installed, read it **offline** with no network round-trip:
+
+```sh
+rigor docs editor-integration
+```
+
+(Web fallback, only before Rigor is installed:
+**[Rigor LSP — Editor Integration](https://github.com/rigortype/rigor/blob/master/docs/manual/09-editor-integration.md)**.)
+This skill is the *workflow* around it (identify the editor → apply the
+manual's snippet → verify), so it does not duplicate (and cannot
+stale-out) the config details.
+
+## When to use
+
+- A developer wants Rigor feedback live in their editor, not just from
+  `rigor check` on the command line.
+- A project commits a shared editor config (e.g. `.vscode/`) and you want
+  to add Rigor's LSP to it so the whole team gets it.
+
+## When NOT to use
+
+- Wiring Rigor into CI — that is `rigor-ci-setup`.
+- The project has no Rigor config yet — run `rigor-project-init` first
+  (the LSP uses the same `.rigor.yml` discovery as `rigor check`).
+
+## The one stable fact
+
+Every editor snippet simply launches **`rigor lsp`** (stdio) and needs
+**`rigor` on the editor's `PATH`** — the same executable `rigor check`
+uses. For GUI editors that do not inherit your shell, the `mise` shim
+path is the most reliable channel (see `rigor docs install`, or
+[Installing Rigor](https://github.com/rigortype/rigor/blob/master/docs/install.md)
+on the web). Do **not** add `rigortype` to the project's `Gemfile` — it
+is a tool, not a library.
+
+## Procedure
+
+### Phase 1 — confirm the analyzer works from the CLI first
+
+```sh
+rigor check <a-file-or-dir>
+```
+
+The LSP shares `rigor check`'s config discovery and analysis. If `check`
+works from the project root, the LSP will too; if it fails, fix that
+first — the editor would only surface the same failure.
+
+### Phase 2 — identify the editor
+
+Ask the developer which editor they use, or detect it (a committed
+`.vscode/`, a Neovim `init.lua`, `~/.config/helix/`, an Emacs config).
+The manual chapter covers:
+
+- **Neovim** (nvim-lspconfig)
+- **VS Code** (generic LSP-client wrapper / minimal extension)
+- **Helix** (`languages.toml`)
+- **Emacs** (Eglot and lsp-mode)
+
+### Phase 3 — apply the matching config
+
+Open the manual's **Editor wiring** section and apply the snippet for
+the developer's editor verbatim:
+
+```sh
+rigor docs editor-integration
+```
+
+(or, pre-install, the web copy:
+<https://github.com/rigortype/rigor/blob/master/docs/manual/09-editor-integration.md>)
+
+All snippets invoke `rigor lsp` directly. (Only if the project still
+uses a legacy bundler-local install do you swap in
+`bundle exec rigor lsp` — the manual notes this per editor.)
+
+If the project commits a shared editor config (e.g. `.vscode/`), add the
+Rigor LSP wiring there and commit it, so every contributor gets the same
+setup rather than configuring it individually.
+
+### Phase 4 — verify
+
+Open a Ruby file inside a Rigor-configured project and confirm:
+
+- diagnostics appear (on save / as you type), and
+- hover over a method or local shows its inferred type.
+
+If the server starts but nothing appears, work the manual's
+**Troubleshooting** section (most often: `rigor` not on the editor's
+PATH, or no `.rigor.yml` at the project root). Capture the LSP log with
+`rigor lsp --log=/tmp/rigor-lsp.log` when filing an issue.
+
+## Next step
+
+Re-run `rigor skill describe` for the next move — with live feedback in
+the editor, raising protection (`rigor-protection-uplift`) or reducing a
+baseline (`rigor-baseline-reduce`) is a tighter loop.

data/skills/rigor-mcp-setup/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: rigor-mcp-setup
+description: |
+  Wire Rigor's bundled MCP server (`rigor mcp`) into an AI coding agent (Claude Code, Claude Desktop, Cursor, Cline) so the agent can call Rigor's read-only analysis tools — rigor_check, rigor_type_of, rigor_triage, rigor_coverage, and more — during a session. The per-client config lives in the manual; this skill identifies the client, applies the right one, and verifies the handshake. Triggers: "set up rigor mcp", "give my AI agent Rigor tools", "wire Rigor into Claude Code / Cursor / Cline", "rigor MCP server". NOT for editor LSP integration (use rigor-editor-setup) or CI (use rigor-ci-setup).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor MCP Setup
+
+`rigor mcp` is the Model Context Protocol server bundled with the
+`rigortype` gem. It exposes Rigor's analysis as JSON-RPC tool calls over
+stdio, so an AI coding agent can call Rigor directly during a session —
+check types before a refactor, look up the type at a cursor, or triage a
+project's diagnostics as review context. All tools are **read-only**
+(write-side commands like `rigor init` / `sig-gen --write` are
+deliberately excluded — modifying files stays the developer's call).
+
+The authoritative, per-client configuration lives in the manual. With
+Rigor installed, read it **offline** with no network round-trip:
+
+```sh
+rigor docs mcp-server
+```
+
+(Web fallback, only before Rigor is installed:
+**[Rigor MCP Server — AI Agent Integration](https://github.com/rigortype/rigor/blob/master/docs/manual/10-mcp-server.md)**.)
+This skill is the *workflow* around it (identify the client → apply the
+manual's snippet → verify the handshake), so it does not duplicate (and
+cannot stale-out) the config details.
+
+## When to use
+
+- A developer wants their AI agent to call Rigor's tools mid-session.
+- A project commits a shared MCP config (`.mcp.json`, `.cursor/mcp.json`)
+  and you want to add Rigor to it for the whole team.
+
+## When NOT to use
+
+- Editor (human) integration — that is `rigor-editor-setup` (`rigor lsp`).
+- The project has no Rigor config yet — run `rigor-project-init` first
+  (the MCP tools use the same `.rigor.yml` discovery as `rigor check`).
+
+## The tools you are wiring in
+
+`rigor_check`, `rigor_type_of`, `rigor_triage`, `rigor_annotate`,
+`rigor_sig_gen`, `rigor_explain`, `rigor_coverage` — each the JSON form
+of the matching `rigor` CLI command. See the manual's **Tool reference**
+for inputs and outputs.
+
+## The one stable fact
+
+Every client config simply launches **`rigor mcp`** (stdio) and needs
+**`rigor` on the agent's `PATH`** — the same executable `rigor check`
+uses. For agents that do not inherit your shell, the `mise` shim path is
+the most reliable channel (see `rigor docs install`, or
+[Installing Rigor](https://github.com/rigortype/rigor/blob/master/docs/install.md)
+on the web). Do **not** add `rigortype` to the project's `Gemfile` — it
+is a tool, not a library.
+
+## Procedure
+
+### Phase 1 — confirm the analyzer works from the CLI first
+
+```sh
+rigor check <a-file-or-dir>
+```
+
+The MCP tools share `rigor check`'s config discovery. If `check` works
+from the project root, the tools will too.
+
+### Phase 2 — identify the client and apply the config
+
+Ask the developer which agent they use, or detect a committed config
+(`.mcp.json`, `.cursor/mcp.json`, `.claude/settings.json`). Apply the
+matching snippet from the manual's **Client wiring** section verbatim —
+it covers Claude Desktop, Claude Code CLI, Cursor, Cline, and a generic
+stdio client:
+
+```sh
+rigor docs mcp-server
+```
+
+(or, pre-install, the web copy:
+<https://github.com/rigortype/rigor/blob/master/docs/manual/10-mcp-server.md>)
+
+Each snippet is the same shape — `{"command": "rigor", "args": ["mcp"]}`.
+If the project commits a shared MCP config, add the Rigor entry there and
+commit it so every contributor gets it.
+
+**Working-directory gotcha (from the manual's Troubleshooting):** the
+server discovers config from the directory it is launched in. If the
+client starts `rigor mcp` from `$HOME` or a temp dir, no `.rigor.yml` is
+found and tools return an empty set. Pin it with
+`"args": ["mcp", "--config=/abs/path/.rigor.yml"]`, or pass absolute
+`paths` in the tool call.
+
+### Phase 3 — verify the handshake
+
+Confirm `rigor mcp` answers the MCP `initialize` request:
+
+```sh
+echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' | rigor mcp
+```
+
+A JSON `result` with `serverInfo.name: "rigor"` means it works; nothing
+or a shell error means `rigor` is not on the PATH the client uses. Then
+restart the client and confirm the `rigor_*` tools appear in its tool
+palette.
+
+## Next step
+
+Re-run `rigor skill describe` for the next move — with the agent able to
+call Rigor's tools, raising protection (`rigor-protection-uplift`) or
+reducing a baseline (`rigor-baseline-reduce`) is a tighter loop.