# a589 — AI Inside the Panel (a555 phase 15 + roadmap)

## Goal
Bring the `ai-bundle` (currently in `/opt/repos/fv-module-gallery/bundles/ai-bundle` v2.2.1, 14 submodules)
into the operator control panel so Mavis sessions (and the operator) can:

1. **Search the panel intelligently** — natural language queries on top of `/api/mavis/search`
2. **Surface relevant context automatically** — when `/me` is called, the AI picks the most relevant 3-5 items (opinions, audits, recent bulletins) and returns a summary
3. **Run checkers** — AI-driven lint/lint/lint that doesn't need an explicit human invocation
4. **Have its own thread** — `ai-mavis` (id ~50) that uses the same `/me` → `wakeup` → reply loop as any Mavis session
5. **File opinions + plans** — AI can write to `hq_opinions` and `artifacts` (type=plan) on operator's behalf, with approval
6. **Special comms with operator** — a thread where AI sends bulletins to thread 7 (operator-panel-mavis) that bubble to the operator's SPA

## Current state (assessed 2026-08-13)

### AI bundle is shipped in gallery, not yet in panel
- 14 submodules at `/opt/repos/fv-module-gallery/modules/ai-*/`
- Each has the canonical 10-file recipe-book + src + facets
- Bundle v2.2.1, ai-ask v1.0.0, ai-orchestrator v1.0.0
- ai-adapters: 5 providers (minimax, zai, anthropic, openai, local) — none configured for the panel yet

### The 14 submodules
1. **ai-ask** — 9-layer LLM dispatcher (the brain)
2. **ai-orchestrator** — multi-step reasoning
3. **ai-adapters** — provider abstraction (5 LLM APIs)
4. **ai-credentials** — key storage/rotation
5. **ai-history** — conversation persistence
6. **ai-ambient** — passive observation (1s debounce)
7. **ai-fragments** — RAG chunking
8. **ai-input** — input component
9. **ai-stt** — speech-to-text
10. **ai-mic** — voice input
11. **ai-toast** — transient feedback
12. **ai-workspaces-chip** — workspace selector
13. **ai-actions** — action system
14. **ai-settings** — config UI

### Panel currently has
- `/api/mavis/search` (LIKE-based, just shipped)
- `/api/mavis/me` with `wakeup` bundle (auto-include)
- `/api/mavis/scan` (background scanner)
- Lint engine (6 rules)
- No LLM yet

## Implementation phases

### Phase 1: Provider + minimal ask (1-2 days)

**Goal:** AI can answer a single question using one provider.

1. Add `ai-credentials` key for at least one provider (start with `minimax` since Mavis is the platform's main LLM).
   - Add to `/opt/operator/.env`: `MAVIS_LLM_KEY=...` (or vault).
   - Or reuse `GITHUB_PAT_FG_1` if a compatible provider supports GitHub-auth.
2. Copy `ai-adapters` + `ai-ask` recipe-books into the panel as a planning artifact (read-only recipe, not code).
3. Add `/api/mavis/ai/ask` endpoint:
   ```
   POST /api/mavis/ai/ask
   Body: { question: "...", context?: {...}, scope?: "mavis-hq", use_cache?: bool }
   Returns: { ok, answer, citations: [...], cached: bool, ms: number }
   ```
4. Use the recipe-book's 9-layer dispatcher as the routing pattern:
   - Layer 1: heuristic (do we have a cached answer? → return)
   - Layer 2: web-search (not implemented yet, stub for now)
   - Layer 3: data (query the panel DB directly for the answer)
   - Layer 4: history (check past ai-asks for similar)
   - Layer 5: classify (what kind of question is this? opinion? audit? plan?)
   - Layer 6: standard (call LLM with curated prompt)
   - Layer 7: how-to (specialized "how do I do X" prompt)
   - Layer 8: off-topic (return canned response)
   - Layer 9: clarify (return clarifying question)
5. Cache every ask in `hq_ai_cache` table (new):
   - id, question_hash, question, answer, citations (JSON), created_at, hits
   - Cache hit → return cached, increment `hits`
6. Log every ask in `audit.log` for traceability

**Deliverable:** `POST /api/mavis/ai/ask "What audits did we do today?"` returns a real answer with citations.

### Phase 2: AI inside /me (auto-surface) (1 day)

**Goal:** When any Mavis session calls `/me`, the AI pre-computes a `wakeup.ai_summary` field.

1. Add to `/me` response: `wakeup.ai_summary` = 2-3 sentence natural language summary of the most relevant items
2. Computation:
   - Take the `wakeup.opinions.items` (already there)
   - Take the `wakeup.audits.items` (already there)
   - Take the `wakeup.fyi.recent` (already there)
   - Build a focused prompt: "Given these items, write a 2-3 sentence summary of what this thread should know before starting work"
   - Call LLM (cached — same prompt returns same answer within 1h)
3. Cache the summary keyed on `(thread_id, content_hash, hour_bucket)` for 1h

**Deliverable:** every `/me` response includes a human-readable `ai_summary` field. Mavis sessions see it as the first thing in their context.

### Phase 3: AI-mavis thread (1-2 days)

**Goal:** Register a new Mavis thread `ai-mavis` that can:
- Wake up via `/me` (sees the same wakeup bundle as everyone)
- Reply via `/api/mavis/bulletin` (as the AI)
- File opinions via `/api/mavis/opinions` (as the AI)
- File plans via `/api/artifacts` (type=plan, as the AI)
- Run checkers via `/api/mavis/scan` (triggers staleness scan, AI summarizes findings)

1. Register `ai-mavis` via `/api/mavis/register` with a special `scope=ai` and a long-lived token
2. Store token in vault (`/opt/operator/secrets/`)
3. Add a heartbeat loop: every 5 min, AI-mavis calls `/me` and decides if there's action
4. When AI-mavis wants to act:
   - File opinion: `POST /api/mavis/opinions` with `author: "ai-mavis"`
   - File plan: `POST /api/artifacts` with `created_by_session: "ai-mavis-session-id"`
   - Send bulletin: `POST /api/mavis/bulletin` with `thread_id: 7` (operator) for visibility
5. Operator can OVERRIDE AI-filed opinions/plans via PATCH (operator gets a "this was AI-filed, approve?" badge in the SPA)

**Deliverable:** A new thread appears in `/mavis/threads` named `ai-mavis`. The operator can see its bulletins + opinions + plans alongside human work.

### Phase 4: AI-driven checkers (2-3 days)

**Goal:** AI can run lint/check tasks on demand AND on schedule.

1. Add `hq_ai_checker_runs` table:
   - id, scope, prompt, status (queued|running|done|failed), result, started_at, finished_at
2. Add `POST /api/mavis/ai/check`:
   - Body: { scope, prompt, type: "lint" | "audit" | "consistency" | "doctrine" }
   - Returns the run_id immediately
   - Background job runs the LLM, posts the result as an `audit` or `bulletin`
3. Triggered automatically on:
   - New plan uploaded (consistency check)
   - New opinion filed (doctrine check)
   - Nightly cron (full audit)
4. AI checker types:
   - **lint**: read the plan, check for FvW v8 compliance, file as opinion
   - **audit**: read the repo, find gaps, file as audit
   - **consistency**: cross-check opinions/audits for contradictions
   - **doctrine**: verify FvW doctrine is being followed

**Deliverable:** AI runs checkers and files their findings in the proper tables (opinions for doctrine, audits for system-level findings). Operator sees them with "AI-generated" badge.

### Phase 5: Special comms + SPA UI (1-2 days)

**Goal:** Operator can chat with the AI directly from the panel.

1. Add a new SPA tab "AI" (14th tab) — chat interface
2. Chat input → `POST /api/mavis/ai/ask` with `context: { thread, scope, plan_id? }`
3. AI responses stream in (or return fully for now)
4. AI can include "actions" in response: e.g. "I created opinion op0042 about this — review at /mavis#memory"
5. Operator can pin the AI chat to a specific scope

**Deliverable:** Operator types "what's blocking a555?" in the panel AI tab → gets a structured answer with links to opinions/audits/bulletins.

## Risks + mitigations

- **LLM cost runaway**: cache everything, default to 1h TTL, hard cap at $5/day per provider, alert at 80%
- **AI files bad data**: every AI-filed record gets `author: "ai-mavis"`, every AI-filed plan has `meta.created_by: "ai-mavis"`, operator can review + delete
- **AI hallucinates citations**: the LLM is only given the actual DB rows as context, not asked to "remember" — citations are always DB lookups, never invented
- **Provider lock-in**: use ai-adapters abstraction, swap providers without code change
- **Latency**: cache first, then LLM; if LLM takes >5s return cached + partial

## Out of scope (intentionally)

- Voice input (ai-stt/ai-mic) — operator uses keyboard
- Mobile AI assistant — desktop panel is enough
- AI-to-AI coordination — single AI-mavis thread is enough
- Fine-tuning the LLM on Mavis data — out of scope, use as-is
- Replacing Mavis with the AI — they're complementary

## Commit plan

- a589 phase 1: provider + `/api/mavis/ai/ask` + cache table (~1.5 days)
- a589 phase 2: `ai_summary` in `/me` (~1 day)
- a589 phase 3: ai-mavis thread + heartbeat (~1.5 days)
- a589 phase 4: AI checkers (~2-3 days)
- a589 phase 5: SPA chat tab (~1-2 days)

Total: ~7-9 days. Can ship incrementally, each phase adds immediate value.