feat(m14): AI assistant — explain diagnostics, opt-in (Ollama or Claude) — 0.27.0

New optional module (D24): explains the collected findings in plain language,
contacted ONLY on an explicit user action (never automatic).

- core/ai.py: provider chosen explicitly (no default) — ollama (local) or claude
  (Anthropic Messages API via stdlib urllib; key in keyring). Grounded prompt;
  HTTP error parsing; one-shot (no thinking/caching — snappy).
- core/ai_knowledge.py: curated reference KB (Xid/SMART/Proton/tunables),
  exact keyword/code match ("RAG-lite", no embeddings) injected into the prompt —
  lifts local models, sharpens Claude. No fine-tuning.
- config: ai_provider/ai_model/ai_endpoint + keyring-backed AI key (generalized
  the token keyring helpers).
- GUI: Settings → AI assistant (provider radios, model/endpoint/key, Save/Test);
  "Explain with AI" button on the diagnostic dialog (consent prompt for cloud).
- CLI: `rigdoctor ai status|test|explain`.
- Docs: D24, SPEC/MODULES/ROADMAP (Phase 7); tests for providers/grounding/parse.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/DECISIONS.md

@@ -249,9 +249,24 @@ duplicated what the GUI already shows and added surface area. Concretely:
   (preserves fish/ls/git theming), full-screen-able, with the guest read-only unless the host
   ticks "Allow the guest to type" (the D9 consent exception). Account-gated by the Gitea token.
 
+### D24 — AI assistant module (M14) — *DECIDED 2026-05-22; adds to D14*
+A new optional module that **explains the collected diagnostics in plain language** (likely
+root cause + suggested next steps). Adds M14 to the D14 set.
+- **Strictly opt-in, never automatic.** The model is contacted **only** on an explicit user
+  action (an "Explain with AI" button / `rigdoctor ai explain`) — never on launch, after a
+  diagnostic, in the sample/record loop, or in the background. **Configuring** a provider does
+  not trigger any call.
+- **Local-first.** Defaults to a local **Ollama** server (data never leaves the machine, no
+  key, stdlib `urllib`). An **OpenAI-compatible** endpoint (cloud or local) can be used with a
+  key (stored in the keyring like the update token). Cloud use shows a "this sends your data to
+  X" consent before the first call.
+- **Grounded & advisory.** The prompt carries only the findings we collected; output is framed
+  as suggestions (consistent with D9 — it explains/recommends, applying fixes stays
+  consent-gated). No new runtime dependency (HTTP via stdlib).
+
 ## Open
 
-None currently — all tracked decisions (D1–D23) are resolved. New questions will be added
+None currently — all tracked decisions (D1–D24) are resolved. New questions will be added
 here as they arise. Remaining detail to flesh out during build: the tray's supporting-action
 set (D13), per-module apt package names, M12's tunnel/token specifics, and M13's
 update mechanism (APT repo vs. self-installed `.deb`).

docs/MODULES.md

@@ -20,6 +20,7 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
 | M9 | Installer | (meta) | none | all | P1 | 🟨 |
 | M12 | Session sharing (shared terminal) | Sharing | none (relay) | all | P3 | ✅ |
 | M13 | Auto-update | (core) | none (stdlib; user-local file swap) | all | P3 | ✅ |
+| M14 | AI assistant (explain diagnostics) | (optional) | none (stdlib urllib; Ollama or Claude) | all | P3 | ✅ |
 | ~~M7~~ | ~~Stress / repro~~ | — | — | — | — | ❌ dropped (D7) |
 
 ## Notes per module
@@ -117,6 +118,15 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
   atomic symlink swap → restart, incl. the daemon). HTTPS-only, version-check-only (no
   telemetry), opt-out-able. Surfaced in the GUI; `rigdoctor update` in the CLI. (`.deb` users
   update via apt instead.)
+- **M14 AI assistant** (D24) — optional, **strictly opt-in, never automatic**: explains the
+  collected diagnostics in plain language only when the user presses **"Explain with AI"**
+  (`core/ai.py`, GUI button on the diagnostic dialog, `rigdoctor ai explain`). The user picks a
+  provider explicitly (no default): **Ollama** (local, private, no key) or **Claude** (Anthropic
+  Messages API, key in the keyring; consent prompt before sending). Answers are **grounded** —
+  we pass the actual findings plus matched reference facts from a curated knowledge base
+  (`core/ai_knowledge.py`, "RAG-lite": exact keyword/code match, no embeddings, stdlib only),
+  which lifts a small local model and sharpens Claude. Stdlib `urllib` (no pip deps); output is
+  advisory (D9). Configure in **Settings → AI assistant**.
 
 ## Bundles (final — D14)
 - **Essential:** M1 + M3 + M4  *(the MVP, NVIDIA-only — D5)*
@@ -124,6 +134,7 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
 - **Diagnostics:** M5 + M6
 - **Desktop UI:** M10 + M11  *(adds PySide6)*
 - **Sharing:** M12  *(session sharing / remote assist — D16)*
+- **AI:** M14  *(optional AI explanations — D24)*
 
 ## MVP candidate — *confirmed (D5)*
 **M1 + M3 + M4 (Essential), NVIDIA-only, CLI-first.** Gives a working tool that captures the

docs/ROADMAP.md

@@ -89,6 +89,14 @@ Ubuntu + NVIDIA first; `.deb` distribution (see `DECISIONS.md`).
 - [removed] The read-only stats view (`share serve`) and bundle export — dropped per D23; the
       shared terminal is the only sharing mode.
 
+## Phase 7 — AI assistant  (M14, D24)
+- [x] **Explain diagnostics with AI** — opt-in, never automatic (`core/ai.py`, "Explain with AI"
+      button + `rigdoctor ai explain`). Provider chosen explicitly: **Ollama** (local) or
+      **Claude** (Anthropic). Grounded with a curated reference KB (`core/ai_knowledge.py`,
+      RAG-lite, exact match — no embeddings); stdlib `urllib`. Settings → AI assistant.
+- [ ] *Possible follow-ups:* interactive chat grounded in the data; more reference-KB entries;
+      an "Explain" button on the System Health page.
+
 > **Out of scope:** stress/repro module (D7); multi-distro support and packaging beyond
 > Ubuntu/apt + `.deb` (D15) — a thin seam is kept but not built out.
 

docs/SPEC.md

@@ -152,6 +152,16 @@ type too (e.g. a sudo password, which stays local and is never sent to B). Accou
 Gitea token; per-session share code. The shared terminal preserves colors/theming and can be
 viewed full-screen. *(The earlier read-only stats view / bundle export were dropped — D23.)*
 
+### M14 — AI assistant (D24)
+Optional module that explains the collected diagnostics in plain language. **Strictly opt-in and
+never automatic** — the model is contacted only when the user presses "Explain with AI" (GUI) or
+runs `rigdoctor ai explain`; configuring it contacts nothing. The user explicitly chooses a
+provider (no default): **Ollama** (local, private, no key) or **Claude** (Anthropic Messages
+API, key in the keyring, with a consent prompt before sending data). Answers are **grounded** in
+the actual findings plus matched reference facts from a curated, exact-match knowledge base
+("RAG-lite" — no embeddings/vector store, stdlib only); no fine-tuning. HTTP via stdlib `urllib`
+(no new core dependency); output is advisory (consistent with D9).
+
 ## 5. Non-functional requirements
 - **Zero hard deps for the core/CLI/daemon** — Python stdlib + tools already present. **Qt
   (PySide6) is required only by the GUI (M10) and tray (M11) modules**, declared in the