fix(search): collapse newlines in snippets to prevent unindented metadata (GIT-5)

Document content_text includes multi-line metadata (Project:, URL:, Labels:,
State:) separated by newlines. FTS5 snippet() preserves these newlines, causing
subsequent lines to render at column 0 with no indent. collapse_newlines()
flattens all whitespace runs into single spaces before truncation and rendering.

Includes 3 unit tests.

.beads/last-touched

@@ -1 +1 @@
-bd-1sc6
+bd-1lj5

.gitignore

@@ -31,6 +31,7 @@ yarn-error.log*
 
 # Local config files
 lore.config.json
+.liquid-mail.toml
 
 # beads
 .bv/

.opencode/rules

@@ -1,50 +0,0 @@
-
-````markdown
-## UBS Quick Reference for AI Agents
-
-UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
-
-**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
-
-**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
-
-**Commands:**
-```bash
-ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
-ubs $(git diff --name-only --cached)    # Staged files — before commit
-ubs --only=js,python src/               # Language filter (3-5x faster)
-ubs --ci --fail-on-warning .            # CI mode — before PR
-ubs --help                              # Full command reference
-ubs sessions --entries 1                # Tail the latest install session log
-ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
-```
-
-**Output Format:**
-```
-⚠️  Category (N errors)
-    file.ts:42:5 – Issue description
-    💡 Suggested fix
-Exit code: 1
-```
-Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
-
-**Fix Workflow:**
-1. Read finding → category + fix suggestion
-2. Navigate `file:line:col` → view context
-3. Verify real issue (not false positive)
-4. Fix root cause (not symptom)
-5. Re-run `ubs <file>` → exit 0
-6. Commit
-
-**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
-
-**Bug Severity:**
-- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
-- **Important** (production): Type narrowing, division-by-zero, resource leaks
-- **Contextual** (judgment): TODO/FIXME, console logs
-
-**Anti-Patterns:**
-- ❌ Ignore findings → ✅ Investigate each
-- ❌ Full scan per edit → ✅ Scope to file
-- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
-````

.roam/fitness.yaml

@@ -1,11 +0,0 @@
-rules:
-  - name: No circular imports in core
-    type: dependency
-    source: "src/**"
-    forbidden_target: "tests/**"
-    reason: "Production code should not import test modules"
-  - name: Complexity threshold
-    type: metric
-    metric: cognitive_complexity
-    threshold: 30
-    reason: "Functions above 30 cognitive complexity need refactoring"

AGENTS.md

@@ -127,66 +127,17 @@ Prefer deterministic lab-runtime tests for concurrency-sensitive behavior.
 
 ---
 
-## MCP Agent Mail — Multi-Agent Coordination
-
-A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources. Provides identities, inbox/outbox, searchable threads, and advisory file reservations with human-auditable artifacts in Git.
-
-### Why It's Useful
-
-- **Prevents conflicts:** Explicit file reservations (leases) for files/globs
-- **Token-efficient:** Messages stored in per-project archive, not in context
-- **Quick reads:** `resource://inbox/...`, `resource://thread/...`
-
-### Same Repository Workflow
-
-1. **Register identity:**
-   ```
-   ensure_project(project_key=<abs-path>)
-   register_agent(project_key, program, model)
-   ```
-
-2. **Reserve files before editing:**
-   ```
-   file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)
-   ```
-
-3. **Communicate with threads:**
-   ```
-   send_message(..., thread_id="FEAT-123")
-   fetch_inbox(project_key, agent_name)
-   acknowledge_message(project_key, agent_name, message_id)
-   ```
-
-4. **Quick reads:**
-   ```
-   resource://inbox/{Agent}?project=<abs-path>&limit=20
-   resource://thread/{id}?project=<abs-path>&include_bodies=true
-   ```
-
-### Macros vs Granular Tools
-
-- **Prefer macros for speed:** `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`
-- **Use granular tools for control:** `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`
-
-### Common Pitfalls
-
-- `"from_agent not registered"`: Always `register_agent` in the correct `project_key` first
-- `"FILE_RESERVATION_CONFLICT"`: Adjust patterns, wait for expiry, or use non-exclusive reservation
-- **Auth errors:** If JWT+JWKS enabled, include bearer token with matching `kid`
-
----
-
 ## Beads (br) — Dependency-Aware Issue Tracking
 
-Beads provides a lightweight, dependency-aware issue database and CLI (`br` / beads_rust) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging and file reservations.
+Beads provides a lightweight, dependency-aware issue database and CLI (`br` / beads_rust) for selecting "ready work," setting priorities, and tracking status. It complements Liquid Mail's shared log for progress, decisions, and cross-session context.
 
 **Note:** `br` is non-invasive—it never executes git commands directly. You must run git commands manually after `br sync --flush-only`.
 
 ### Conventions
 
-- **Single source of truth:** Beads for task status/priority/dependencies; Agent Mail for conversation and audit
+- **Single source of truth:** Beads for task status/priority/dependencies; Liquid Mail for conversation/decisions
-- **Shared identifiers:** Use Beads issue ID (e.g., `br-123`) as Mail `thread_id` and prefix subjects with `[br-123]`
+- **Shared identifiers:** Include the Beads issue ID in posts (e.g., `[br-123] Topic validation rules`)
-- **Reservations:** When starting a task, call `file_reservation_paths()` with the issue ID in `reason`
+- **Decisions before action:** Post `DECISION:` messages before risky changes, not after
 
 ### Typical Agent Flow
 
@@ -195,35 +146,34 @@ Beads provides a lightweight, dependency-aware issue database and CLI (`br` / be
    br ready --json  # Choose highest priority, no blockers
    ```
 
-2. **Reserve edit surface (Mail):**
+2. **Check context (Liquid Mail):**
-   ```
+   ```bash
-   file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="br-123")
+   liquid-mail notify                # See what changed since last session
+   liquid-mail query "br-123"        # Find prior discussion on this issue
    ```
 
-3. **Announce start (Mail):**
+3. **Work and log progress:**
-   ```
+   ```bash
-   send_message(..., thread_id="br-123", subject="[br-123] Start: <title>", ack_required=true)
+   liquid-mail post --topic <workstream> "[br-123] START: <description>"
+   liquid-mail post "[br-123] FINDING: <what you discovered>"
+   liquid-mail post --decision "[br-123] DECISION: <what you decided and why>"
    ```
 
-4. **Work and update:** Reply in-thread with progress
+4. **Complete (Beads is authority):**
-
-5. **Complete and release:**
    ```bash
    br close br-123 --reason "Completed"
+   liquid-mail post "[br-123] Completed: <summary with commit ref>"
    ```
-   ```
-   release_file_reservations(project_key, agent_name, paths=["src/**"])
-   ```
-   Final Mail reply: `[br-123] Completed` with summary
 
 ### Mapping Cheat Sheet
 
-| Concept | Value |
+| Concept | In Beads | In Liquid Mail |
-|---------|-------|
+|---------|----------|----------------|
-| Mail `thread_id` | `br-###` |
+| Work item | `br-###` (issue ID) | Include `[br-###]` in posts |
-| Mail subject | `[br-###] ...` |
+| Workstream | — | `--topic auth-system` |
-| File reservation `reason` | `br-###` |
+| Subject prefix | — | `[br-###] ...` |
-| Commit messages | Include `br-###` for traceability |
+| Commit message | Include `br-###` | — |
+| Status | `br update --status` | Post progress messages |
 
 ---
 
@@ -231,7 +181,7 @@ Beads provides a lightweight, dependency-aware issue database and CLI (`br` / be
 
 bv is a graph-aware triage engine for Beads projects (`.beads/beads.jsonl`). It computes PageRank, betweenness, critical path, cycles, HITS, eigenvector, and k-core metrics deterministically.
 
-**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (messaging, work claiming, file reservations), use MCP Agent Mail.
+**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (progress logging, decisions, cross-session context), use Liquid Mail.
 
 **CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.**
 
@@ -673,6 +623,16 @@ lore --robot generate-docs
 # Generate vector embeddings via Ollama
 lore --robot embed
 
+# Personal work dashboard
+lore --robot me
+lore --robot me --issues
+lore --robot me --mrs
+lore --robot me --activity --since 7d
+lore --robot me --project group/repo
+lore --robot me --user jdoe
+lore --robot me --fields minimal
+lore --robot me --reset-cursor
+
 # Agent self-discovery manifest (all commands, flags, exit codes, response schemas)
 lore robot-docs
 

CLAUDE.md

@@ -0,0 +1,960 @@
+# CLAUDE.md
+
+## RULE 0 - THE FUNDAMENTAL OVERRIDE PEROGATIVE
+
+If I tell you to do something, even if it goes against what follows below, YOU MUST LISTEN TO ME. I AM IN CHARGE, NOT YOU.
+
+---
+
+## RULE NUMBER 1: NO FILE DELETION
+
+**YOU ARE NEVER ALLOWED TO DELETE A FILE WITHOUT EXPRESS PERMISSION.** Even a new file that you yourself created, such as a test code file. You have a horrible track record of deleting critically important files or otherwise throwing away tons of expensive work. As a result, you have permanently lost any and all rights to determine that a file or folder should be deleted.
+
+**YOU MUST ALWAYS ASK AND RECEIVE CLEAR, WRITTEN PERMISSION BEFORE EVER DELETING A FILE OR FOLDER OF ANY KIND.**
+
+---
+
+## Version Control: jj-First (CRITICAL)
+
+**ALWAYS prefer jj (Jujutsu) over git for all VCS operations.** This is a colocated repo with both `.jj/` and `.git/`. When instructed to use git by anything — even later in this file — use the best jj replacement commands instead. Only fall back to raw `git` for things jj cannot do (hooks, LFS, submodules, `gh` CLI interop).
+
+See `~/.claude/rules/jj-vcs/` for the full command reference, translation table, revsets, patterns, and recovery recipes.
+
+---
+
+## Irreversible Git & Filesystem Actions — DO NOT EVER BREAK GLASS
+
+> **Note:** Treat destructive commands as break-glass. If there's any doubt, stop and ask.
+
+1. **Absolutely forbidden commands:** `git reset --hard`, `git clean -fd`, `rm -rf`, or any command that can delete or overwrite code/data must never be run unless the user explicitly provides the exact command and states, in the same message, that they understand and want the irreversible consequences.
+2. **No guessing:** If there is any uncertainty about what a command might delete or overwrite, stop immediately and ask the user for specific approval. "I think it's safe" is never acceptable.
+3. **Safer alternatives first:** When cleanup or rollbacks are needed, request permission to use non-destructive options (`git status`, `git diff`, `git stash`, copying to backups) before ever considering a destructive command.
+4. **Mandatory explicit plan:** Even after explicit user authorization, restate the command verbatim, list exactly what will be affected, and wait for a confirmation that your understanding is correct. Only then may you execute it—if anything remains ambiguous, refuse and escalate.
+5. **Document the confirmation:** When running any approved destructive command, record (in the session notes / final response) the exact user text that authorized it, the command actually run, and the execution time. If that record is absent, the operation did not happen.
+
+---
+
+## Toolchain: Rust & Cargo
+
+We only use **Cargo** in this project, NEVER any other package manager.
+
+- **Edition/toolchain:** Follow `rust-toolchain.toml` (if present). Do not assume stable vs nightly.
+- **Dependencies:** Explicit versions for stability; keep the set minimal.
+- **Configuration:** Cargo.toml only
+- **Unsafe code:** Forbidden (`#![forbid(unsafe_code)]`)
+
+When writing Rust code, reference RUST_CLI_TOOLS_BEST_PRACTICES.md
+
+### Release Profile
+
+Use the release profile defined in `Cargo.toml`. If you need to change it, justify the
+performance/size tradeoff and how it impacts determinism and cancellation behavior.
+
+---
+
+## Code Editing Discipline
+
+### No Script-Based Changes
+
+**NEVER** run a script that processes/changes code files in this repo. Brittle regex-based transformations create far more problems than they solve.
+
+- **Always make code changes manually**, even when there are many instances
+- For many simple changes: use parallel subagents
+- For subtle/complex changes: do them methodically yourself
+
+### No File Proliferation
+
+If you want to change something or add a feature, **revise existing code files in place**.
+
+**NEVER** create variations like:
+- `mainV2.rs`
+- `main_improved.rs`
+- `main_enhanced.rs`
+
+New files are reserved for **genuinely new functionality** that makes zero sense to include in any existing file. The bar for creating new files is **incredibly high**.
+
+---
+
+## Backwards Compatibility
+
+We do not care about backwards compatibility—we're in early development with no users. We want to do things the **RIGHT** way with **NO TECH DEBT**.
+
+- Never create "compatibility shims"
+- Never create wrapper functions for deprecated APIs
+- Just fix the code directly
+
+---
+
+## Compiler Checks (CRITICAL)
+
+**After any substantive code changes, you MUST verify no errors were introduced:**
+
+```bash
+# Check for compiler errors and warnings
+cargo check --all-targets
+
+# Check for clippy lints (pedantic + nursery are enabled)
+cargo clippy --all-targets -- -D warnings
+
+# Verify formatting
+cargo fmt --check
+```
+
+If you see errors, **carefully understand and resolve each issue**. Read sufficient context to fix them the RIGHT way.
+
+---
+
+## Testing
+
+### Unit & Property Tests
+
+```bash
+# Run all tests
+cargo test
+
+# Run with output
+cargo test -- --nocapture
+```
+
+When adding or changing primitives, add tests that assert the core invariants:
+
+- no task leaks
+- no obligation leaks
+- losers are drained after races
+- region close implies quiescence
+
+Prefer deterministic lab-runtime tests for concurrency-sensitive behavior.
+
+---
+
+---
+
+## Beads (br) — Dependency-Aware Issue Tracking
+
+Beads provides a lightweight, dependency-aware issue database and CLI (`br` / beads_rust) for selecting "ready work," setting priorities, and tracking status. It complements Liquid Mail's shared log for progress, decisions, and cross-session context.
+
+**Note:** `br` is non-invasive—it never executes git commands directly. You must run git commands manually after `br sync --flush-only`.
+
+### Conventions
+
+- **Single source of truth:** Beads for task status/priority/dependencies; Liquid Mail for conversation/decisions
+- **Shared identifiers:** Include the Beads issue ID in posts (e.g., `[br-123] Topic validation rules`)
+- **Decisions before action:** Post `DECISION:` messages before risky changes, not after
+
+### Typical Agent Flow
+
+1. **Pick ready work (Beads):**
+   ```bash
+   br ready --json  # Choose highest priority, no blockers
+   ```
+
+2. **Check context (Liquid Mail):**
+   ```bash
+   liquid-mail notify                # See what changed since last session
+   liquid-mail query "br-123"        # Find prior discussion on this issue
+   ```
+
+3. **Work and log progress:**
+   ```bash
+   liquid-mail post --topic <workstream> "[br-123] START: <description>"
+   liquid-mail post "[br-123] FINDING: <what you discovered>"
+   liquid-mail post --decision "[br-123] DECISION: <what you decided and why>"
+   ```
+
+4. **Complete (Beads is authority):**
+   ```bash
+   br close br-123 --reason "Completed"
+   liquid-mail post "[br-123] Completed: <summary with commit ref>"
+   ```
+
+### Mapping Cheat Sheet
+
+| Concept | In Beads | In Liquid Mail |
+|---------|----------|----------------|
+| Work item | `br-###` (issue ID) | Include `[br-###]` in posts |
+| Workstream | — | `--topic auth-system` |
+| Subject prefix | — | `[br-###] ...` |
+| Commit message | Include `br-###` | — |
+| Status | `br update --status` | Post progress messages |
+
+---
+
+## bv — Graph-Aware Triage Engine
+
+bv is a graph-aware triage engine for Beads projects (`.beads/beads.jsonl`). It computes PageRank, betweenness, critical path, cycles, HITS, eigenvector, and k-core metrics deterministically.
+
+**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (progress logging, decisions, cross-session context), use Liquid Mail.
+
+**CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.**
+
+### The Workflow: Start With Triage
+
+**`bv --robot-triage` is your single entry point.** It returns:
+- `quick_ref`: at-a-glance counts + top 3 picks
+- `recommendations`: ranked actionable items with scores, reasons, unblock info
+- `quick_wins`: low-effort high-impact items
+- `blockers_to_clear`: items that unblock the most downstream work
+- `project_health`: status/type/priority distributions, graph metrics
+- `commands`: copy-paste shell commands for next steps
+
+```bash
+bv --robot-triage        # THE MEGA-COMMAND: start here
+bv --robot-next          # Minimal: just the single top pick + claim command
+```
+
+### Command Reference
+
+**Planning:**
+| Command | Returns |
+|---------|---------|
+| `--robot-plan` | Parallel execution tracks with `unblocks` lists |
+| `--robot-priority` | Priority misalignment detection with confidence |
+
+**Graph Analysis:**
+| Command | Returns |
+|---------|---------|
+| `--robot-insights` | Full metrics: PageRank, betweenness, HITS, eigenvector, critical path, cycles, k-core, articulation points, slack |
+| `--robot-label-health` | Per-label health: `health_level`, `velocity_score`, `staleness`, `blocked_count` |
+| `--robot-label-flow` | Cross-label dependency: `flow_matrix`, `dependencies`, `bottleneck_labels` |
+| `--robot-label-attention [--attention-limit=N]` | Attention-ranked labels |
+
+**History & Change Tracking:**
+| Command | Returns |
+|---------|---------|
+| `--robot-history` | Bead-to-commit correlations |
+| `--robot-diff --diff-since <ref>` | Changes since ref: new/closed/modified issues, cycles |
+
+**Other:**
+| Command | Returns |
+|---------|---------|
+| `--robot-burndown <sprint>` | Sprint burndown, scope changes, at-risk items |
+| `--robot-forecast <id\|all>` | ETA predictions with dependency-aware scheduling |
+| `--robot-alerts` | Stale issues, blocking cascades, priority mismatches |
+| `--robot-suggest` | Hygiene: duplicates, missing deps, label suggestions |
+| `--robot-graph [--graph-format=json\|dot\|mermaid]` | Dependency graph export |
+| `--export-graph <file.html>` | Interactive HTML visualization |
+
+### Scoping & Filtering
+
+```bash
+bv --robot-plan --label backend              # Scope to label's subgraph
+bv --robot-insights --as-of HEAD~30          # Historical point-in-time
+bv --recipe actionable --robot-plan          # Pre-filter: ready to work
+bv --recipe high-impact --robot-triage       # Pre-filter: top PageRank
+bv --robot-triage --robot-triage-by-track    # Group by parallel work streams
+bv --robot-triage --robot-triage-by-label    # Group by domain
+```
+
+### Understanding Robot Output
+
+**All robot JSON includes:**
+- `data_hash` — Fingerprint of source beads.jsonl
+- `status` — Per-metric state: `computed|approx|timeout|skipped` + elapsed ms
+- `as_of` / `as_of_commit` — Present when using `--as-of`
+
+**Two-phase analysis:**
+- **Phase 1 (instant):** degree, topo sort, density
+- **Phase 2 (async, 500ms timeout):** PageRank, betweenness, HITS, eigenvector, cycles
+
+### jq Quick Reference
+
+```bash
+bv --robot-triage | jq '.quick_ref'                        # At-a-glance summary
+bv --robot-triage | jq '.recommendations[0]'               # Top recommendation
+bv --robot-plan | jq '.plan.summary.highest_impact'        # Best unblock target
+bv --robot-insights | jq '.status'                         # Check metric readiness
+bv --robot-insights | jq '.Cycles'                         # Circular deps (must fix!)
+```
+
+---
+
+## UBS — Ultimate Bug Scanner
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+### Commands
+
+```bash
+ubs file.rs file2.rs                    # Specific files (< 1s) — USE THIS
+ubs $(jj diff --name-only)              # Changed files — before commit
+ubs --only=rust,toml src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs .                                   # Whole project (ignores target/, Cargo.lock)
+```
+
+### Output Format
+
+```
+⚠️  Category (N errors)
+    file.rs:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+### Fix Workflow
+
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+### Bug Severity
+
+- **Critical (always fix):** Memory safety, use-after-free, data races, SQL injection
+- **Important (production):** Unwrap panics, resource leaks, overflow checks
+- **Contextual (judgment):** TODO/FIXME, println! debugging
+
+---
+
+## ast-grep vs ripgrep
+
+**Use `ast-grep` when structure matters.** It parses code and matches AST nodes, ignoring comments/strings, and can **safely rewrite** code.
+
+- Refactors/codemods: rename APIs, change import forms
+- Policy checks: enforce patterns across a repo
+- Editor/automation: LSP mode, `--json` output
+
+**Use `ripgrep` when text is enough.** Fastest way to grep literals/regex.
+
+- Recon: find strings, TODOs, log lines, config values
+- Pre-filter: narrow candidate files before ast-grep
+
+### Rule of Thumb
+
+- Need correctness or **applying changes** → `ast-grep`
+- Need raw speed or **hunting text** → `rg`
+- Often combine: `rg` to shortlist files, then `ast-grep` to match/modify
+
+### Rust Examples
+
+```bash
+# Find structured code (ignores comments)
+ast-grep run -l Rust -p 'fn $NAME($$$ARGS) -> $RET { $$$BODY }'
+
+# Find all unwrap() calls
+ast-grep run -l Rust -p '$EXPR.unwrap()'
+
+# Quick textual hunt
+rg -n 'println!' -t rust
+
+# Combine speed + precision
+rg -l -t rust 'unwrap\(' | xargs ast-grep run -l Rust -p '$X.unwrap()' --json
+```
+
+---
+
+## Morph Warp Grep — AI-Powered Code Search
+
+**Use `mcp__morph-mcp__warp_grep` for exploratory "how does X work?" questions.** An AI agent expands your query, greps the codebase, reads relevant files, and returns precise line ranges with full context.
+
+**Use `ripgrep` for targeted searches.** When you know exactly what you're looking for.
+
+**Use `ast-grep` for structural patterns.** When you need AST precision for matching/rewriting.
+
+### When to Use What
+
+| Scenario | Tool | Why |
+|----------|------|-----|
+| "How is pattern matching implemented?" | `warp_grep` | Exploratory; don't know where to start |
+| "Where is the quick reject filter?" | `warp_grep` | Need to understand architecture |
+| "Find all uses of `Regex::new`" | `ripgrep` | Targeted literal search |
+| "Find files with `println!`" | `ripgrep` | Simple pattern |
+| "Replace all `unwrap()` with `expect()`" | `ast-grep` | Structural refactor |
+
+### warp_grep Usage
+
+```
+mcp__morph-mcp__warp_grep(
+  repoPath: "/path/to/dcg",
+  query: "How does the safe pattern whitelist work?"
+)
+```
+
+Returns structured results with file paths, line ranges, and extracted code snippets.
+
+### Anti-Patterns
+
+- **Don't** use `warp_grep` to find a specific function name → use `ripgrep`
+- **Don't** use `ripgrep` to understand "how does X work" → wastes time with manual reads
+- **Don't** use `ripgrep` for codemods → risks collateral edits
+
+<!-- bv-agent-instructions-v1 -->
+
+---
+
+## Beads Workflow Integration
+
+This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in version control.
+
+**Note:** `br` is non-invasive—it never executes VCS commands directly. You must commit manually after `br sync --flush-only`.
+
+### Essential Commands
+
+```bash
+# View issues (launches TUI - avoid in automated sessions)
+bv
+
+# CLI commands for agents (use these instead)
+br ready              # Show issues ready to work (no blockers)
+br list --status=open # All open issues
+br show <id>          # Full issue details with dependencies
+br create --title="..." --type=task --priority=2
+br update <id> --status=in_progress
+br close <id> --reason="Completed"
+br close <id1> <id2>  # Close multiple issues at once
+br sync --flush-only  # Export to JSONL (then: jj commit -m "Update beads")
+```
+
+### Workflow Pattern
+
+1. **Start**: Run `br ready` to find actionable work
+2. **Claim**: Use `br update <id> --status=in_progress`
+3. **Work**: Implement the task
+4. **Complete**: Use `br close <id>`
+5. **Sync**: Run `br sync --flush-only`, then `git add .beads/ && git commit -m "Update beads"`
+
+### Key Concepts
+
+- **Dependencies**: Issues can block other issues. `br ready` shows only unblocked work.
+- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers, not words)
+- **Types**: task, bug, feature, epic, question, docs
+- **Blocking**: `br dep add <issue> <depends-on>` to add dependencies
+
+### Session Protocol
+
+**Before ending any session, run this checklist (solo/lead only — workers skip VCS):**
+
+```bash
+jj status                        # Check what changed
+br sync --flush-only             # Export beads to JSONL
+jj commit -m "..."               # Commit code and beads (jj auto-tracks all changes)
+jj bookmark set <name> -r @-     # Point bookmark at committed work
+jj git push -b <name>            # Push to remote
+```
+
+### Best Practices
+
+- Check `br ready` at session start to find available work
+- Update status as you work (in_progress → closed)
+- Create new issues with `br create` when you discover tasks
+- Use descriptive titles and set appropriate priority/type
+- Always run `br sync --flush-only` then commit before ending session (jj auto-tracks .beads/)
+
+<!-- end-bv-agent-instructions -->
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until push succeeds.
+
+**WHO RUNS THIS:** Solo agents run it themselves. In multi-agent sessions, ONLY the team lead runs this. Workers skip VCS entirely.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   jj git fetch                       # Get latest remote state
+   jj rebase -d trunk()               # Rebase onto latest trunk if needed
+   br sync --flush-only               # Export beads to JSONL
+   jj commit -m "Update beads"        # Commit (jj auto-tracks .beads/ changes)
+   jj bookmark set <name> -r @-       # Point bookmark at committed work
+   jj git push -b <name>              # Push to remote
+   jj log -r '<name>'                 # Verify bookmark position
+   ```
+5. **Clean up** - Abandon empty orphan changes if any (`jj abandon <rev>`)
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `jj git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+
+---
+
+## cass — Cross-Agent Session Search
+
+`cass` indexes prior agent conversations (Claude Code, Codex, Cursor, Gemini, ChatGPT, etc.) so we can reuse solved problems.
+
+**Rules:** Never run bare `cass` (TUI). Always use `--robot` or `--json`.
+
+### Examples
+
+```bash
+cass health
+cass search "async runtime" --robot --limit 5
+cass view /path/to/session.jsonl -n 42 --json
+cass expand /path/to/session.jsonl -n 42 -C 3 --json
+cass capabilities --json
+cass robot-docs guide
+```
+
+### Tips
+
+- Use `--fields minimal` for lean output
+- Filter by agent with `--agent`
+- Use `--days N` to limit to recent history
+
+stdout is data-only, stderr is diagnostics; exit code 0 means success.
+
+Treat cass as a way to avoid re-solving problems other agents already handled.
+
+---
+
+## Note for Codex/GPT-5.2
+
+You constantly bother me and stop working with concerned questions that look similar to this:
+
+```
+Unexpected changes (need guidance)
+
+- Working tree still shows edits I did not make in Cargo.toml, Cargo.lock, src/runtime.rs, src/scope.rs. Please advise whether to keep/commit/revert these before any further work. I did not touch them.
+
+Next steps (pick one)
+
+1. Decide how to handle the unrelated modified files above so we can resume cleanly.
+```
+
+NEVER EVER DO THAT AGAIN. The answer is literally ALWAYS the same: those are changes created by the potentially dozen of other agents working on the project at the same time. This is not only a common occurence, it happens multiple times PER MINUTE. The way to deal with it is simple: you NEVER, under ANY CIRCUMSTANCE, stash, revert, overwrite, or otherwise disturb in ANY way the work of other agents. Just treat those changes identically to changes that you yourself made. Just fool yourself into thinking YOU made the changes and simply don't recall it for some reason.
+
+---
+
+## Note on Built-in TODO Functionality
+
+Also, if I ask you to explicitly use your built-in TODO functionality, don't complain about this and say you need to use beads. You can use built-in TODOs if I tell you specifically to do so. Always comply with such orders.
+
+## TDD Requirements
+
+Test-first development is mandatory:
+1. **RED** - Write failing test first
+2. **GREEN** - Minimal implementation to pass
+3. **REFACTOR** - Clean up while green
+
+## Key Patterns
+
+Find the simplest solution that meets all acceptance criteria.
+Use third party libraries whenever there's a well-maintained, active, and widely adopted solution (for example, date-fns for TS date math)
+Build extensible pieces of logic that can easily be integrated with other pieces.
+DRY principles should be loosely held.
+Architecture MUST be clear and well thought-out. Ask the user for clarification whenever ambiguity is discovered around architecture, or you think a better approach than planned exists.
+
+---
+
+## Third-Party Library Usage
+
+If you aren't 100% sure how to use a third-party library, **SEARCH ONLINE** to find the latest documentation and mid-2025 best practices.
+
+---
+
+## Gitlore Robot Mode
+
+The `lore` CLI has a robot mode optimized for AI agent consumption with compact JSON output, structured errors with machine-actionable recovery steps, meaningful exit codes, response timing metadata, field selection for token efficiency, and TTY auto-detection.
+
+### Activation
+
+```bash
+# Explicit flag
+lore --robot issues -n 10
+
+# JSON shorthand (-J)
+lore -J issues -n 10
+
+# Auto-detection (when stdout is not a TTY)
+lore issues | jq .
+
+# Environment variable
+LORE_ROBOT=1 lore issues
+```
+
+### Robot Mode Commands
+
+```bash
+# List issues/MRs with JSON output
+lore --robot issues -n 10
+lore --robot mrs -s opened
+
+# Filter issues by work item status (case-insensitive)
+lore --robot issues --status "In progress"
+
+# List with field selection (reduces token usage ~60%)
+lore --robot issues --fields minimal
+lore --robot mrs --fields iid,title,state,draft
+
+# Show detailed entity info
+lore --robot issues 123
+lore --robot mrs 456 -p group/repo
+
+# Count entities
+lore --robot count issues
+lore --robot count discussions --for mr
+
+# Search indexed documents
+lore --robot search "authentication bug"
+
+# Check sync status
+lore --robot status
+
+# Run full sync pipeline
+lore --robot sync
+
+# Run sync without resource events
+lore --robot sync --no-events
+
+# Surgical sync: specific entities by IID
+lore --robot sync --issue 42 -p group/repo
+lore --robot sync --mr 99 --mr 100 -p group/repo
+
+# Run ingestion only
+lore --robot ingest issues
+
+# Trace why code was introduced
+lore --robot trace src/main.rs -p group/repo
+
+# File-level MR history
+lore --robot file-history src/auth/ -p group/repo
+
+# Manage cron-based auto-sync (Unix)
+lore --robot cron status
+lore --robot cron install --interval 15
+
+# Token management
+lore --robot token show
+
+# Check environment health
+lore --robot doctor
+
+# Document and index statistics
+lore --robot stats
+
+# Quick health pre-flight check (exit 0 = healthy, 19 = unhealthy)
+lore --robot health
+
+# Generate searchable documents from ingested data
+lore --robot generate-docs
+
+# Generate vector embeddings via Ollama
+lore --robot embed
+
+# Personal work dashboard
+lore --robot me
+lore --robot me --issues
+lore --robot me --mrs
+lore --robot me --activity --since 7d
+lore --robot me --project group/repo
+lore --robot me --user jdoe
+lore --robot me --fields minimal
+lore --robot me --reset-cursor
+
+# Find semantically related entities
+lore --robot related issues 42
+lore --robot related "authentication flow"
+
+# Re-register projects from config
+lore --robot init --refresh
+
+# Agent self-discovery manifest (all commands, flags, exit codes, response schemas)
+lore robot-docs
+
+# Version information
+lore --robot version
+```
+
+### Response Format
+
+All commands return compact JSON with a uniform envelope and timing metadata:
+
+```json
+{"ok":true,"data":{...},"meta":{"elapsed_ms":42}}
+```
+
+Errors return structured JSON to stderr with machine-actionable recovery steps:
+
+```json
+{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'","actions":["lore init"]}}
+```
+
+The `actions` array contains executable shell commands for automated recovery. It is omitted when empty.
+
+### Field Selection
+
+The `--fields` flag on `issues` and `mrs` list commands controls which fields appear in the JSON response:
+
+```bash
+lore -J issues --fields minimal                    # Preset: iid, title, state, updated_at_iso
+lore -J mrs --fields iid,title,state,draft,labels  # Custom field list
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Internal error / not implemented |
+| 2 | Usage error (invalid flags or arguments) |
+| 3 | Config invalid |
+| 4 | Token not set |
+| 5 | GitLab auth failed |
+| 6 | Resource not found |
+| 7 | Rate limited |
+| 8 | Network error |
+| 9 | Database locked |
+| 10 | Database error |
+| 11 | Migration failed |
+| 12 | I/O error |
+| 13 | Transform error |
+| 14 | Ollama unavailable |
+| 15 | Ollama model not found |
+| 16 | Embedding failed |
+| 17 | Not found (entity does not exist) |
+| 18 | Ambiguous match (use `-p` to specify project) |
+| 19 | Health check failed |
+| 20 | Config not found |
+
+### Configuration Precedence
+
+1. CLI flags (highest priority)
+2. Environment variables (`LORE_ROBOT`, `GITLAB_TOKEN`, `LORE_CONFIG_PATH`)
+3. Config file (`~/.config/lore/config.json`)
+4. Built-in defaults (lowest priority)
+
+### Best Practices
+
+- Use `lore --robot` or `lore -J` for all agent interactions
+- Check exit codes for error handling
+- Parse JSON errors from stderr; use `actions` array for automated recovery
+- Use `--fields minimal` to reduce token usage (~60% fewer tokens)
+- Use `-n` / `--limit` to control response size
+- Use `-q` / `--quiet` to suppress progress bars and non-essential output
+- Use `--color never` in non-TTY automation for ANSI-free output
+- Use `-v` / `-vv` / `-vvv` for increasing verbosity (debug/trace logging)
+- Use `--log-format json` for machine-readable log output to stderr
+- TTY detection handles piped commands automatically
+- Use `lore --robot health` as a fast pre-flight check before queries
+- Use `lore robot-docs` for response schema discovery
+- The `-p` flag supports fuzzy project matching (suffix and substring)
+
+---
+
+## Read/Write Split: lore vs glab
+
+| Operation | Tool | Why |
+|-----------|------|-----|
+| List issues/MRs | lore | Richer: includes status, discussions, closing MRs |
+| View issue/MR detail | lore | Pre-joined discussions, work-item status |
+| Search across entities | lore | FTS5 + vector hybrid search |
+| Expert/workload analysis | lore | who command — no glab equivalent |
+| Timeline reconstruction | lore | Chronological narrative — no glab equivalent |
+| Create/update/close | glab | Write operations |
+| Approve/merge MR | glab | Write operations |
+| CI/CD pipelines | glab | Not in lore scope |
+
+````markdown
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
+````
+
+<!-- BEGIN LIQUID MAIL (v:48d7b3fc) -->
+## Integrating Liquid Mail with Beads
+
+**Beads** manages task status, priority, and dependencies (`br` CLI).
+**Liquid Mail** provides the shared log—progress, decisions, and context that survives sessions.
+
+### Conventions
+
+- **Single source of truth**: Beads owns task state; Liquid Mail owns conversation/decisions
+- **Shared identifiers**: Include the Beads issue ID in posts (e.g., `[lm-jht] Topic validation rules`)
+- **Decisions before action**: Post `DECISION:` messages before risky changes, not after
+- **Identity in user updates**: In every user-facing reply, include your window-name (derived from `LIQUID_MAIL_WINDOW_ID`) so humans can distinguish concurrent agents.
+
+### Typical Flow
+
+**1. Pick ready work (Beads)**
+```bash
+br ready                    # Find available work (no blockers)
+br show lm-jht              # Review details
+br update lm-jht --status in_progress
+```
+
+**2. Check context (Liquid Mail)**
+```bash
+liquid-mail notify          # See what changed since last session
+liquid-mail query "lm-jht"  # Find prior discussion on this issue
+```
+
+**3. Work and log progress (topic required)**
+
+The `--topic` flag is required for your first post. After that, the topic is pinned to your window.
+```bash
+liquid-mail post --topic auth-system "[lm-jht] START: Reviewing current topic id patterns"
+liquid-mail post "[lm-jht] FINDING: IDs like lm3189... are being used as topic names"
+liquid-mail post "[lm-jht] NEXT: Add validation + rename guidance"
+```
+
+**4. Decisions before risky changes**
+```bash
+liquid-mail post --decision "[lm-jht] DECISION: Reject UUID-like topic names; require slugs"
+# Then implement
+```
+
+### Decision Conflicts (Preflight)
+
+When you post a decision (via `--decision` or a `DECISION:` line), Liquid Mail can preflight-check for conflicts with prior decisions **in the same topic**.
+
+- If a conflict is detected, `liquid-mail post` fails with `DECISION_CONFLICT`.
+- Review prior decisions: `liquid-mail decisions --topic <topic>`.
+- If you intend to supersede the old decision, re-run with `--yes` and include what changed and why.
+
+**5. Complete (Beads is authority)**
+```bash
+br close lm-jht             # Mark complete in Beads
+liquid-mail post "[lm-jht] Completed: Topic validation shipped in 177267d"
+```
+
+### Posting Format
+
+- **Short** (5-15 lines, not walls of text)
+- **Prefixed** with ALL-CAPS tags: `FINDING:`, `DECISION:`, `QUESTION:`, `NEXT:`
+- **Include file paths** so others can jump in: `src/services/auth.ts:42`
+- **Include issue IDs** in brackets: `[lm-jht]`
+- **User-facing replies**: include `AGENT: <window-name>` near the top. Get it with `liquid-mail window name`.
+
+### Topics (Required)
+
+Liquid Mail organizes messages into **topics** (Honcho sessions). Topics are **soft boundaries**—search spans all topics by default.
+
+**Rule:** `liquid-mail post` requires a topic:
+- Provide `--topic <name>`, OR
+- Post inside a window that already has a pinned topic.
+
+Topic names must be:
+- 4–50 characters
+- lowercase letters/numbers with hyphens
+- start with a letter, end with a letter/number
+- no consecutive hyphens
+- not reserved (`all`, `new`, `help`, `merge`, `rename`, `list`)
+- not UUID-like (`lm<32-hex>` or standard UUIDs)
+
+Good examples: `auth-system`, `db-system`, `dashboards`
+
+Commands:
+
+- **List topics (newest first)**: `liquid-mail topics`
+- **Find context across topics**: `liquid-mail query "auth"`, then pick a topic name
+- **Rename a topic (alias)**: `liquid-mail topic rename <old> <new>`
+- **Merge two topics into a new one**: `liquid-mail topic merge <A> <B> --into <C>`
+
+Examples (component topic + Beads id in the subject):
+```bash
+liquid-mail post --topic auth-system "[lm-jht] START: Investigating token refresh failures"
+liquid-mail post --topic auth-system "[lm-jht] FINDING: refresh happens in middleware, not service layer"
+liquid-mail post --topic auth-system --decision "[lm-jht] DECISION: Move refresh logic into AuthService"
+
+liquid-mail post --topic dashboards "[lm-1p5] START: Adding latency panel"
+```
+
+### Context Refresh (Before New Work / After Redirects)
+
+If you see redirect/merge messages, refresh context before acting:
+```bash
+liquid-mail notify
+liquid-mail window status --json
+liquid-mail summarize --topic <topic>
+liquid-mail decisions --topic <topic>
+```
+
+If you discover a newer "canonical" topic (for example after a topic merge), switch to it explicitly:
+```bash
+liquid-mail post --topic <new-topic> "[lm-xxxx] CONTEXT: Switching topics (rename/merge)"
+```
+
+### Live Updates (Polling)
+
+Liquid Mail is pull-based by default (you run `notify`). For near-real-time updates:
+```bash
+liquid-mail watch --topic <topic>   # watch a topic
+liquid-mail watch                   # or watch your pinned topic
+```
+
+### Mapping Cheat-Sheet
+
+| Concept | In Beads | In Liquid Mail |
+|---------|----------|----------------|
+| Work item | `lm-jht` (issue ID) | Include `[lm-jht]` in posts |
+| Workstream | — | `--topic auth-system` |
+| Subject prefix | — | `[lm-jht] ...` |
+| Commit message | Include `lm-jht` | — |
+| Status | `br update --status` | Post progress messages |
+
+### Pitfalls
+
+- **Don't manage tasks in Liquid Mail**—Beads is the single task queue
+- **Always include `lm-xxx`** in posts to avoid ID drift across tools
+- **Don't dump logs**—keep posts short and structured
+
+### Quick Reference
+
+| Need | Command |
+|------|---------|
+| What changed? | `liquid-mail notify` |
+| Log progress | `liquid-mail post "[lm-xxx] ..."` |
+| Before risky change | `liquid-mail post --decision "[lm-xxx] DECISION: ..."` |
+| Find history | `liquid-mail query "search term"` |
+| Prior decisions | `liquid-mail decisions --topic <topic>` |
+| Show config | `liquid-mail config` |
+| List topics | `liquid-mail topics` |
+| Rename topic | `liquid-mail topic rename <old> <new>` |
+| Merge topics | `liquid-mail topic merge <A> <B> --into <C>` |
+| Polling watch | `liquid-mail watch [--topic <topic>]` |
+<!-- END LIQUID MAIL -->

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lore"
-version = "0.8.3"
+version = "0.9.4"
 edition = "2024"
 description = "Gitlore - Local GitLab data management with semantic search"
 authors = ["Taylor Eernisse"]
@@ -25,16 +25,15 @@ clap_complete = "4"
 dialoguer = "0.12"
 console = "0.16"
 indicatif = "0.18"
-lipgloss = { package = "charmed-lipgloss", version = "0.1", default-features = false, features = ["native"] }
+lipgloss = { package = "charmed-lipgloss", version = "0.2", default-features = false, features = ["native"] }
 open = "5"
 
 # HTTP
-reqwest = { version = "0.12", features = ["json"] }
+asupersync = { version = "0.2", features = ["tls", "tls-native-roots"] }
-tokio = { version = "1", features = ["rt-multi-thread", "macros", "time", "signal"] }
 
 # Async streaming for pagination
 async-stream = "0.3"
-futures = { version = "0.3", default-features = false, features = ["alloc"] }
+futures = { version = "0.3", default-features = false, features = ["alloc", "async-await"] }
 
 # Utilities
 thiserror = "2"
@@ -60,6 +59,7 @@ tracing-appender = "0.2"
 
 [dev-dependencies]
 tempfile = "3"
+tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros"] }
 wiremock = "0.6"
 
 [profile.release]

README.md

@@ -12,6 +12,9 @@ Local GitLab data management with semantic search, people intelligence, and temp
 - **Hybrid search**: Combines FTS5 lexical search with Ollama-powered vector embeddings via Reciprocal Rank Fusion
 - **People intelligence**: Expert discovery, workload analysis, review patterns, active discussions, and code ownership overlap
 - **Timeline pipeline**: Reconstructs chronological event histories by combining search, graph traversal, and event aggregation across related entities
+- **Code provenance tracing**: Traces why code was introduced by linking files to MRs, MRs to issues, and issues to discussion threads
+- **File-level history**: Shows which MRs touched a file with rename-chain resolution and inline DiffNote snippets
+- **Surgical sync**: Sync specific issues or MRs by IID without running a full incremental sync, with preflight validation
 - **Git history linking**: Tracks merge and squash commit SHAs to connect MRs with git history
 - **File change tracking**: Records which files each MR touches, enabling file-level history queries
 - **Raw payload storage**: Preserves original GitLab API responses for debugging
@@ -21,9 +24,12 @@ Local GitLab data management with semantic search, people intelligence, and temp
 - **Resource event history**: Tracks state changes, label events, and milestone events for issues and MRs
 - **Note querying**: Rich filtering over discussion notes by author, type, path, resolution status, time range, and body content
 - **Discussion drift detection**: Semantic analysis of how discussions diverge from original issue intent
+- **Automated sync scheduling**: Cron-based automatic syncing with configurable intervals (Unix)
+- **Token management**: Secure interactive or piped token storage with masked display
 - **Robot mode**: Machine-readable JSON output with structured errors, meaningful exit codes, and actionable recovery steps
 - **Error tolerance**: Auto-corrects common CLI mistakes (case, typos, single-dash flags, value casing) with teaching feedback
 - **Observability**: Verbosity controls, JSON log format, structured metrics, and stage timing
+- **Icon system**: Configurable icon sets (Nerd Fonts, Unicode, ASCII) with automatic detection
 
 ## Installation
 
@@ -77,6 +83,21 @@ lore timeline "deployment"
 # Timeline for a specific issue
 lore timeline issue:42
 
+# Personal work dashboard
+lore me
+
+# Find semantically related entities
+lore related issues 42
+
+# Why was this file changed? (file -> MR -> issue -> discussion)
+lore trace src/features/auth/login.ts
+
+# Which MRs touched this file?
+lore file-history src/features/auth/
+
+# Sync a specific issue without full sync
+lore sync --issue 42 -p group/repo
+
 # Query notes by author
 lore notes --author alice --since 7d
 
@@ -190,6 +211,8 @@ Create a personal access token with `read_api` scope:
 | `XDG_DATA_HOME` | XDG Base Directory for data (fallback: `~/.local/share`) | No |
 | `NO_COLOR` | Disable color output when set (any value) | No |
 | `CLICOLOR` | Standard color control (0 to disable) | No |
+| `LORE_ICONS` | Override icon set: `nerd`, `unicode`, or `ascii` | No |
+| `NERD_FONTS` | Enable Nerd Font icons when set to a non-empty value | No |
 | `RUST_LOG` | Logging level filter (e.g., `lore=debug`) | No |
 
 ## Commands
@@ -353,12 +376,13 @@ Shows: total DiffNotes, categorized by code area with percentage breakdown.
 
 #### Active Mode
 
-Surface unresolved discussions needing attention.
+Surface unresolved discussions needing attention. By default, only discussions on open issues and non-merged MRs are shown.
 
 ```bash
 lore who --active                     # Unresolved discussions (last 7 days)
 lore who --active --since 30d        # Wider time window
 lore who --active -p group/repo      # Scoped to project
+lore who --active --include-closed   # Include discussions on closed/merged entities
 ```
 
 Shows: discussion threads with participants and last activity timestamps.
@@ -382,11 +406,44 @@ Shows: users with touch counts (author vs. review), linked MR references. Defaul
 | `--since` | Time window (7d, 2w, 6m, YYYY-MM-DD). Default varies by mode. |
 | `-n` / `--limit` | Max results per section (1-500, default 20) |
 | `--all-history` | Remove the default time window, query all history |
+| `--include-closed` | Include discussions on closed issues and merged/closed MRs (active mode) |
 | `--detail` | Show per-MR detail breakdown (expert mode only) |
 | `--explain-score` | Show per-component score breakdown (expert mode only) |
 | `--as-of` | Score as if "now" is a past date (ISO 8601 or duration like 30d, expert mode only) |
 | `--include-bots` | Include bot users normally excluded via `scoring.excludedUsernames` |
 
+### `lore me`
+
+Personal work dashboard showing open issues, authored/reviewing MRs, and activity feed. Designed for quick daily check-ins.
+
+```bash
+lore me                                 # Full dashboard
+lore me --issues                        # Open issues section only
+lore me --mrs                           # Authored + reviewing MRs only
+lore me --activity                      # Activity feed only
+lore me --mentions                      # Items you're @mentioned in (not assigned/authored/reviewing)
+lore me --since 7d                      # Activity window (default: 30d)
+lore me --project group/repo            # Scope to one project
+lore me --all                           # All synced projects (overrides default_project)
+lore me --user jdoe                     # Override configured username
+lore me --reset-cursor                  # Reset since-last-check cursor
+```
+
+The dashboard detects the current user from GitLab authentication and shows:
+- **Issues section**: Open issues assigned to you
+- **MRs section**: Open MRs you authored + open MRs where you're a reviewer
+- **Activity section**: Recent events (state changes, comments, labels, milestones, assignments) on your items regardless of state — including closed issues and merged/closed MRs
+- **Mentions section**: Items where you're @mentioned but not assigned/authoring/reviewing
+- **Since last check**: Cursor-based inbox of actionable events from others since your last check, covering items in any state
+
+The `--since` flag affects only the activity section. The issues and MRs sections show open items only. The since-last-check inbox uses a persistent cursor (reset with `--reset-cursor`).
+
+#### Field Selection (Robot Mode)
+
+```bash
+lore -J me --fields minimal             # Compact output for agents
+```
+
 ### `lore timeline`
 
 Reconstruct a chronological timeline of events matching a keyword query. The pipeline discovers related entities through cross-reference graph traversal and assembles a unified, time-ordered event stream.
@@ -465,8 +522,6 @@ lore notes --contains "TODO"                 # Substring search in note body
 lore notes --include-system                  # Include system-generated notes
 lore notes --since 2w --until 2024-12-31     # Time-bounded range
 lore notes --sort updated --asc              # Sort by update time, ascending
-lore notes --format csv                      # CSV output
-lore notes --format jsonl                    # Line-delimited JSON
 lore notes -o                                # Open first result in browser
 
 # Field selection (robot mode)
@@ -493,9 +548,52 @@ lore -J notes --fields minimal               # Compact: id, author_username, bod
 | `--resolution` | Filter by resolution status (`any`, `unresolved`, `resolved`) |
 | `--sort` | Sort by `created` (default) or `updated` |
 | `--asc` | Sort ascending (default: descending) |
-| `--format` | Output format: `table` (default), `json`, `jsonl`, `csv` |
 | `-o` / `--open` | Open first result in browser |
 
+### `lore file-history`
+
+Show which merge requests touched a file, with rename-chain resolution and optional DiffNote discussion snippets.
+
+```bash
+lore file-history src/main.rs                         # MRs that touched this file
+lore file-history src/auth/ -p group/repo             # Scoped to project
+lore file-history src/foo.rs --discussions             # Include DiffNote snippets
+lore file-history src/bar.rs --no-follow-renames       # Skip rename chain resolution
+lore file-history src/bar.rs --merged                  # Only merged MRs
+lore file-history src/bar.rs -n 100                    # More results
+```
+
+Rename-chain resolution follows file renames through `mr_file_changes` so that querying a renamed file also surfaces MRs that touched previous names. Disable with `--no-follow-renames`.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-p` / `--project` | all | Scope to a specific project (fuzzy match) |
+| `--discussions` | off | Include DiffNote discussion snippets on the file |
+| `--no-follow-renames` | off | Disable rename chain resolution |
+| `--merged` | off | Only show merged MRs |
+| `-n` / `--limit` | `50` | Maximum results |
+
+### `lore trace`
+
+Trace why code was introduced by building provenance chains: file -> MR -> issue -> discussion threads.
+
+```bash
+lore trace src/main.rs                         # Why was this file changed?
+lore trace src/auth/ -p group/repo             # Scoped to project
+lore trace src/foo.rs --discussions             # Include DiffNote context
+lore trace src/bar.rs:42                        # Line hint (future Tier 2)
+lore trace src/bar.rs --no-follow-renames       # Skip rename chain resolution
+```
+
+Each trace chain links a file change to the MR that introduced it, the issue(s) that motivated it (via "closes" references), and the discussion threads on those entities. Line-level hints (`:line` suffix) are accepted but produce an advisory message until Tier 2 git-blame integration is available.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-p` / `--project` | all | Scope to a specific project (fuzzy match) |
+| `--discussions` | off | Include DiffNote discussion snippets |
+| `--no-follow-renames` | off | Disable rename chain resolution |
+| `-n` / `--limit` | `20` | Maximum trace chains to display |
+
 ### `lore drift`
 
 Detect discussion divergence from the original intent of an issue by comparing the semantic similarity of discussion content against the issue description.
@@ -506,9 +604,54 @@ lore drift issues 42 --threshold 0.6        # Higher threshold (stricter)
 lore drift issues 42 -p group/repo          # Scope to project
 ```
 
+### `lore related`
+
+Find semantically related entities via vector search. Accepts either an entity reference or a free text query.
+
+```bash
+lore related issues 42                       # Find entities related to issue #42
+lore related mrs 99 -p group/repo            # Related to MR #99 in specific project
+lore related "authentication flow"           # Find entities matching free text query
+lore related issues 42 -n 5                  # Limit results
+```
+
+In entity mode (`issues N` or `mrs N`), the command embeds the entity's content and finds similar documents via vector similarity. In query mode (free text), the query is embedded directly.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-p` / `--project` | all | Scope to a specific project (fuzzy match) |
+| `-n` / `--limit` | `10` | Maximum results |
+
+Requires embeddings to have been generated via `lore embed` or `lore sync`.
+
+### `lore cron`
+
+Manage cron-based automatic syncing (Unix only). Installs a crontab entry that runs `lore sync --lock -q` at a configurable interval.
+
+```bash
+lore cron install                     # Install cron job (every 8 minutes)
+lore cron install --interval 15       # Custom interval in minutes
+lore cron status                      # Check if cron is installed
+lore cron uninstall                   # Remove cron job
+```
+
+The `--lock` flag on the auto-sync ensures that if a sync is already running, the cron invocation exits cleanly rather than competing for the database lock.
+
+### `lore token`
+
+Manage the stored GitLab token. Supports interactive entry with validation, non-interactive piped input, and masked display.
+
+```bash
+lore token set                         # Interactive token entry + validation
+lore token set --token glpat-xxx       # Non-interactive token storage
+echo glpat-xxx | lore token set        # Pipe token from stdin
+lore token show                        # Show token (masked)
+lore token show --unmask               # Show full token
+```
+
 ### `lore sync`
 
-Run the full sync pipeline: ingest from GitLab (including work item status enrichment via GraphQL), generate searchable documents, and compute embeddings.
+Run the full sync pipeline: ingest from GitLab (including work item status enrichment via GraphQL), generate searchable documents, and compute embeddings. Supports both incremental (cursor-based) and surgical (per-IID) modes.
 
 ```bash
 lore sync                    # Full pipeline
@@ -518,11 +661,29 @@ lore sync --no-embed         # Skip embedding step
 lore sync --no-docs          # Skip document regeneration
 lore sync --no-events        # Skip resource event fetching
 lore sync --no-file-changes  # Skip MR file change fetching
+lore sync --no-status        # Skip work-item status enrichment via GraphQL
 lore sync --dry-run          # Preview what would be synced
+lore sync --timings          # Show detailed timing breakdown per stage
+lore sync --lock             # Acquire file lock (skip if another sync is running)
+
+# Surgical sync: fetch specific entities by IID
+lore sync --issue 42 -p group/repo               # Sync a single issue
+lore sync --mr 99 -p group/repo                  # Sync a single MR
+lore sync --issue 42 --mr 99 -p group/repo       # Mix issues and MRs
+lore sync --issue 1 --issue 2 -p group/repo      # Multiple issues
+lore sync --issue 42 -p group/repo --preflight-only  # Validate without writing
 ```
 
 The sync command displays animated progress bars for each stage and outputs timing metrics on completion. In robot mode (`-J`), detailed stage timing is included in the JSON response.
 
+#### Surgical Sync
+
+When `--issue` or `--mr` flags are provided, sync switches to surgical mode which fetches only the specified entities and their dependents (discussions, events, file changes) from GitLab. This is faster than a full incremental sync and useful for refreshing specific entities on demand.
+
+Surgical mode requires `-p` / `--project` to scope the operation. Each entity goes through preflight validation against the GitLab API, then ingestion, document regeneration, and embedding. Entities that haven't changed since the last sync are skipped (TOCTOU check).
+
+Use `--preflight-only` to validate that entities exist on GitLab without writing to the database.
+
 ### `lore ingest`
 
 Sync data from GitLab to local database. Runs only the ingestion step (no doc generation or embeddings). For issue ingestion, this includes a status enrichment phase that fetches work item statuses via the GitLab GraphQL API.
@@ -607,16 +768,35 @@ Displays:
 
 ### `lore init`
 
-Initialize configuration and database interactively.
+Initialize configuration and database interactively, or refresh the database to match an existing config.
 
 ```bash
 lore init                    # Interactive setup
+lore init --refresh          # Register new projects from existing config
 lore init --force            # Overwrite existing config
 lore init --non-interactive  # Fail if prompts needed
 ```
 
 When multiple projects are configured, `init` prompts whether to set a default project (used when `-p` is omitted). This can also be set via the `--default-project` flag.
 
+#### Refreshing Project Registration
+
+When projects are added to the config file, `lore sync` does not automatically pick them up because project discovery only happens during `lore init`. Use `--refresh` to register new projects without modifying the config file:
+
+```bash
+lore init --refresh              # Interactive: registers new projects, prompts to delete orphans
+lore -J init --refresh           # Robot mode: returns JSON with orphan info
+```
+
+The `--refresh` flag:
+- Validates GitLab authentication before processing
+- Registers new projects from config into the database
+- Detects orphan projects (in database but removed from config)
+- In interactive mode: prompts to delete orphans (default: No)
+- In robot mode: returns JSON with orphan info without prompting
+
+Use `--force` to completely overwrite the config file with fresh interactive setup. The `--refresh` and `--force` flags are mutually exclusive.
+
 In robot mode, `init` supports non-interactive setup via flags:
 
 ```bash
@@ -685,7 +865,7 @@ Show version information including the git commit hash.
 
 ```bash
 lore version
-# lore version 0.1.0 (abc1234)
+# lore version 0.9.2 (571c304)
 ```
 
 ## Robot Mode
@@ -728,7 +908,7 @@ The `actions` array contains executable shell commands an agent can run to recov
 
 ### Field Selection
 
-The `--fields` flag controls which fields appear in the JSON response, reducing token usage for AI agent workflows. Supported on `issues`, `mrs`, `notes`, `search`, `timeline`, and `who` list commands:
+The `--fields` flag controls which fields appear in the JSON response, reducing token usage for AI agent workflows. Supported on `issues`, `mrs`, `notes`, `me`, `search`, `timeline`, and `who` list commands:
 
 ```bash
 # Minimal preset (~60% fewer tokens)
@@ -753,7 +933,7 @@ The CLI auto-corrects common mistakes before parsing, emitting a teaching note t
 |-----------|---------|------|
 | Single-dash long flag | `-robot` -> `--robot` | All |
 | Case normalization | `--Robot` -> `--robot` | All |
-| Flag prefix expansion | `--proj` -> `--project` (unambiguous only) | All |
+| Flag prefix expansion | `--proj` -> `--project`, `--no-color` -> `--color never` (unambiguous only) | All |
 | Fuzzy flag match | `--projct` -> `--project` | All (threshold 0.9 in robot, 0.8 in human) |
 | Subcommand alias | `merge_requests` -> `mrs`, `robotdocs` -> `robot-docs` | All |
 | Value normalization | `--state Opened` -> `--state opened` | All |
@@ -785,7 +965,7 @@ Commands accept aliases for common variations:
 | `stats` | `stat` |
 | `status` | `st` |
 
-Unambiguous prefixes also work via subcommand inference (e.g., `lore iss` -> `lore issues`, `lore time` -> `lore timeline`).
+Unambiguous prefixes also work via subcommand inference (e.g., `lore iss` -> `lore issues`, `lore time` -> `lore timeline`, `lore tra` -> `lore trace`).
 
 ### Agent Self-Discovery
 
@@ -840,6 +1020,8 @@ lore --robot <command>                    # Machine-readable JSON
 lore -J <command>                         # JSON shorthand
 lore --color never <command>              # Disable color output
 lore --color always <command>             # Force color output
+lore --icons nerd <command>               # Nerd Font icons
+lore --icons ascii <command>              # ASCII-only icons (no Unicode)
 lore -q <command>                         # Suppress non-essential output
 lore -v <command>                         # Debug logging
 lore -vv <command>                        # More verbose debug logging
@@ -847,7 +1029,7 @@ lore -vvv <command>                       # Trace-level logging
 lore --log-format json <command>          # JSON-formatted log output to stderr
 ```
 
-Color output respects `NO_COLOR` and `CLICOLOR` environment variables in `auto` mode (the default).
+Color output respects `NO_COLOR` and `CLICOLOR` environment variables in `auto` mode (the default). Icon sets default to `unicode` and can be overridden via `--icons`, `LORE_ICONS`, or `NERD_FONTS` environment variables.
 
 ## Shell Completions
 
@@ -895,7 +1077,7 @@ Data is stored in SQLite with WAL mode and foreign keys enabled. Main tables:
 | `embeddings` | Vector embeddings for semantic search |
 | `dirty_sources` | Entities needing document regeneration after ingest |
 | `pending_discussion_fetches` | Queue for discussion fetch operations |
-| `sync_runs` | Audit trail of sync operations |
+| `sync_runs` | Audit trail of sync operations (supports surgical mode tracking with per-entity results) |
 | `sync_cursors` | Cursor positions for incremental sync |
 | `app_locks` | Crash-safe single-flight lock |
 | `raw_payloads` | Compressed original API responses |

acceptance-criteria.md

@@ -0,0 +1,64 @@
+# Trace/File-History Empty-Result Diagnostics
+
+## AC-1: Human mode shows searched paths on empty results
+
+When `lore trace <path>` returns 0 chains in human mode, the output includes the resolved path(s) that were searched. If renames were followed, show the full rename chain.
+
+## AC-2: Human mode shows actionable reason on empty results
+
+When 0 chains are found, the hint message distinguishes between:
+- "No MR file changes synced yet" (mr_file_changes table is empty for this project) -> suggest `lore sync`
+- "File paths not found in MR file changes" (sync has run but this file has no matches) -> suggest checking the path or that the file may predate the sync window
+
+## AC-3: Robot mode includes diagnostics object on empty results
+
+When `total_chains == 0` in robot JSON output, add a `"diagnostics"` key to `"meta"` containing:
+- `paths_searched: [...]` (already present as `resolved_paths` in data -- no duplication needed)
+- `hints: [string]` -- same actionable reasons as AC-2 but machine-readable
+
+## AC-4: Info-level logging at each pipeline stage
+
+Add `tracing::info!` calls visible with `-v`:
+- After rename resolution: number of paths found
+- After MR query: number of MRs found
+- After issue/discussion enrichment: counts per MR
+
+## AC-5: Apply same pattern to `lore file-history`
+
+All of the above (AC-1 through AC-4) also apply to `lore file-history` empty results.
+
+---
+
+# Secure Token Resolution for Cron
+
+## AC-6: Stored token in config
+
+The configuration file supports an optional `token` field in the `gitlab` section, allowing users to persist their GitLab personal access token alongside other settings. Existing configuration files that omit this field continue to load and function normally.
+
+## AC-7: Token resolution precedence
+
+Lore resolves the GitLab token by checking the environment variable first, then falling back to the stored config token. This means environment variables always take priority, preserving CI/CD workflows and one-off overrides, while the stored token provides a reliable default for non-interactive contexts like cron jobs. If neither source provides a non-empty value, the user receives a clear `TOKEN_NOT_SET` error with guidance on how to fix it.
+
+## AC-8: `lore token set` command
+
+The `lore token set` command provides a secure, guided workflow for storing a GitLab token. It accepts the token via a `--token` flag, standard input (for piped automation), or an interactive masked prompt. Before storing, it validates the token against the GitLab API to catch typos and expired credentials early. After writing the token to the configuration file, it restricts file permissions to owner-only read/write (mode 0600) to prevent other users on the system from reading the token. The command supports both human and robot output modes.
+
+## AC-9: `lore token show` command
+
+The `lore token show` command displays the currently active token along with its source ("config file" or "environment variable"). By default the token value is masked for safety; the `--unmask` flag reveals the full value when needed. The command supports both human and robot output modes.
+
+## AC-10: Consistent token resolution across all commands
+
+Every command that requires a GitLab token uses the same two-step resolution logic described in AC-7. This ensures that storing a token once via `lore token set` is sufficient to make all commands work, including background cron syncs that have no access to shell environment variables.
+
+## AC-11: Cron install warns about missing stored token
+
+When `lore cron install` completes, it checks whether a token is available in the configuration file. If not, it displays a prominent warning explaining that cron jobs cannot access shell environment variables and directs the user to run `lore token set` to ensure unattended syncs will authenticate successfully.
+
+## AC-12: `TOKEN_NOT_SET` error recommends `lore token set`
+
+The `TOKEN_NOT_SET` error message recommends `lore token set` as the primary fix for missing credentials, with the environment variable export shown as an alternative for users who prefer that approach. In robot mode, the `actions` array lists both options so that automated recovery workflows can act on them.
+
+## AC-13: Doctor reports token source
+
+The `lore doctor` command includes the token's source in its GitLab connectivity check, reporting whether the token was found in the configuration file or an environment variable. This makes it straightforward to verify that cron jobs will have access to the token without relying on the user's interactive shell environment.

agents/ceo/AGENTS.md

@@ -0,0 +1,24 @@
+You are the CEO.
+
+Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
+
+Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
+
+## Memory and Planning
+
+You MUST use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, qmd recall, and planning conventions.
+
+Invoke it whenever you need to remember, retrieve, or organize anything.
+
+## Safety Considerations
+
+- Never exfiltrate secrets or private data.
+- Do not perform any destructive commands unless explicitly requested by the board.
+
+## References
+
+These files are essential. Read them.
+
+- `$AGENT_HOME/HEARTBEAT.md` -- execution and extraction checklist. Run every heartbeat.
+- `$AGENT_HOME/SOUL.md` -- who you are and how you should act.
+- `$AGENT_HOME/TOOLS.md` -- tools you have access to

agents/ceo/HEARTBEAT.md

@@ -0,0 +1,72 @@
+# HEARTBEAT.md -- CEO Heartbeat Checklist
+
+Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
+
+## 1. Identity and Context
+
+- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+
+## 2. Local Planning Check
+
+1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
+2. Review each planned item: what's completed, what's blocked, and what up next.
+3. For any blockers, resolve them yourself or escalate to the board.
+4. If you're ahead, start on the next highest priority.
+5. **Record progress updates** in the daily notes.
+
+## 3. Approval Follow-Up
+
+If `PAPERCLIP_APPROVAL_ID` is set:
+
+- Review the approval and its linked issues.
+- Close resolved issues or comment on what remains open.
+
+## 4. Get Assignments
+
+- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
+- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+- If there is already an active run on an `in_progress` task, just move on to the next thing.
+- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+
+## 5. Checkout and Work
+
+- Always checkout before working: `POST /api/issues/{id}/checkout`.
+- Never retry a 409 -- that task belongs to someone else.
+- Do the work. Update status and comment when done.
+
+## 6. Delegation
+
+- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`.
+- Use `paperclip-create-agent` skill when hiring new agents.
+- Assign work to the right agent for the job.
+
+## 7. Fact Extraction
+
+1. Check for new conversations since last extraction.
+2. Extract durable facts to the relevant entity in `$AGENT_HOME/life/` (PARA).
+3. Update `$AGENT_HOME/memory/YYYY-MM-DD.md` with timeline entries.
+4. Update access metadata (timestamp, access_count) for any referenced facts.
+
+## 8. Exit
+
+- Comment on any in_progress work before exiting.
+- If no assignments and no valid mention-handoff, exit cleanly.
+
+---
+
+## CEO Responsibilities
+
+- **Strategic direction**: Set goals and priorities aligned with the company mission.
+- **Hiring**: Spin up new agents when capacity is needed.
+- **Unblocking**: Escalate or resolve blockers for reports.
+- **Budget awareness**: Above 80% spend, focus only on critical tasks.
+- **Never look for unassigned work** -- only work on what is assigned to you.
+- **Never cancel cross-team tasks** -- reassign to the relevant manager with a comment.
+
+## Rules
+
+- Always use the Paperclip skill for coordination.
+- Always include `X-Paperclip-Run-Id` header on mutating API calls.
+- Comment in concise markdown: status line + bullets + links.
+- Self-assign via checkout only when explicitly @-mentioned.

agents/ceo/SOUL.md

@@ -0,0 +1,33 @@
+# SOUL.md -- CEO Persona
+
+You are the CEO.
+
+## Strategic Posture
+
+- You own the P&L. Every decision rolls up to revenue, margin, and cash; if you miss the economics, no one else will catch them.
+- Default to action. Ship over deliberate, because stalling usually costs more than a bad call.
+- Hold the long view while executing the near term. Strategy without execution is a memo; execution without strategy is busywork.
+- Protect focus hard. Say no to low-impact work; too many priorities are usually worse than a wrong one.
+- In trade-offs, optimize for learning speed and reversibility. Move fast on two-way doors; slow down on one-way doors.
+- Know the numbers cold. Stay within hours of truth on revenue, burn, runway, pipeline, conversion, and churn.
+- Treat every dollar, headcount, and engineering hour as a bet. Know the thesis and expected return.
+- Think in constraints, not wishes. Ask "what do we stop?" before "what do we add?"
+- Hire slow, fire fast, and avoid leadership vacuums. The team is the strategy.
+- Create organizational clarity. If priorities are unclear, it's on you; repeat strategy until it sticks.
+- Pull for bad news and reward candor. If problems stop surfacing, you've lost your information edge.
+- Stay close to the customer. Dashboards help, but regular firsthand conversations keep you honest.
+- Be replaceable in operations and irreplaceable in judgment. Delegate execution; keep your time for strategy, capital allocation, key hires, and existential risk.
+
+## Voice and Tone
+
+- Be direct. Lead with the point, then give context. Never bury the ask.
+- Write like you talk in a board meeting, not a blog post. Short sentences, active voice, no filler.
+- Confident but not performative. You don't need to sound smart; you need to be clear.
+- Match intensity to stakes. A product launch gets energy. A staffing call gets gravity. A Slack reply gets brevity.
+- Skip the corporate warm-up. No "I hope this message finds you well." Get to it.
+- Use plain language. If a simpler word works, use it. "Use" not "utilize." "Start" not "initiate."
+- Own uncertainty when it exists. "I don't know yet" beats a hedged non-answer every time.
+- Disagree openly, but without heat. Challenge ideas, not people.
+- Keep praise specific and rare enough to mean something. "Good job" is noise. "The way you reframed the pricing model saved us a quarter" is signal.
+- Default to async-friendly writing. Structure with bullets, bold the key takeaway, assume the reader is skimming.
+- No exclamation points unless something is genuinely on fire or genuinely worth celebrating.

agents/ceo/TOOLS.md

@@ -0,0 +1,3 @@
+# Tools
+
+(Your tools will go here. Add notes about them as you acquire and use them.)

agents/ceo/memory/2026-03-05.md

@@ -0,0 +1,18 @@
+# 2026-03-05 -- CEO Daily Notes
+
+## Timeline
+
+- **13:07** First heartbeat. GIT-1 already done (CEO setup + FE hire submitted).
+- **13:07** Founding Engineer hire approved (approval c2d7622a). Agent ed7d27a9 is idle.
+- **13:07** No assignments in inbox. Woke on `issue_commented` for already-done GIT-1. Clean exit.
+
+## Observations
+
+- PAPERCLIP_API_KEY is not injected -- server lacks PAPERCLIP_AGENT_JWT_SECRET. Board-level fallback works for reads but /agents/me returns 401. Workaround: use company agents list endpoint.
+- Company prefix is GIT.
+- Two agents active: CEO (me, d584ded4), FoundingEngineer (ed7d27a9, idle).
+
+## Today's Plan
+
+1. Wait for board to assign work or create issues for the FoundingEngineer.
+2. When work arrives, delegate to FE and track.

agents/ceo/memory/2026-03-11.md

@@ -0,0 +1,44 @@
+# 2026-03-11 -- CEO Daily Notes
+
+## Timeline
+
+- **10:32** Heartbeat timer wake. No PAPERCLIP_TASK_ID, no mention context.
+- **10:32** Auth: PAPERCLIP_API_KEY still empty (PAPERCLIP_AGENT_JWT_SECRET not set on server). Board-level fallback works.
+- **10:32** Inbox: 0 assignments (todo/in_progress/blocked). Dashboard: 0 open, 0 in_progress, 0 blocked, 1 done.
+- **10:32** Clean exit -- nothing to work on.
+- **10:57** Wake: GIT-2 assigned (issue_assigned). Evaluated FE agent: zero commits, generic instructions.
+- **11:01** Wake: GIT-2 reopened. Board chose Option B (rewrite instructions).
+- **11:03** Rewrote FE AGENTS.md (25 -> 200+ lines), created HEARTBEAT.md, SOUL.md, TOOLS.md, memory dir.
+- **11:04** GIT-2 closed. FE agent ready for calibration task.
+- **11:07** Wake: GIT-2 reopened (issue_reopened_via_comment). Board asked to evaluate instructions against best practices.
+- **11:08** Self-evaluation: AGENTS.md was too verbose (230 lines), duplicated CLAUDE.md, no progressive disclosure. Rewrote to 50-line core + 120-line DOMAIN.md reference. 3-layer progressive disclosure model.
+- **11:13** Wake: GIT-2 reopened. Board asked about testing/validating context loading. Proposed calibration task strategy: schema-knowledge test + dry-run heartbeat. Awaiting board go-ahead.
+- **11:28** Wake: Board approved calibration. Created GIT-3 (calibration: project lookup test) assigned to FE. Subtask of GIT-2.
+- **11:33** Wake: GIT-2 reopened. Board asked to evaluate FE calibration output. Reviewed code + session logs. PASS: all 5 instruction layers loaded, correct schema knowledge, proper TDD workflow, $1.12 calibration cost. FE ready for production work.
+- **12:34** Heartbeat timer wake. No assignments, no mentions. Dashboard: 1 open (GIT-4), 0 in_progress, 0 blocked, 3 done. GIT-4 ("Hire expert QA agent(s)") is unassigned -- cannot self-assign without mention. Clean exit.
+- **13:36** Heartbeat timer wake. No assignments, no mentions. Dashboard: 1 open, 0 in_progress, 0 blocked, 3 done. Spend: $19.22. Clean exit.
+- **14:37** Heartbeat timer wake. No assignments, no mentions. Dashboard: 1 open (GIT-4), 0 in_progress, 0 blocked, 3 done. Spend: $20.46. Clean exit.
+- **15:39** Heartbeat timer wake. No assignments, no mentions. Dashboard: 1 open (GIT-4), 0 in_progress, 0 blocked, 3 done. Spend: $22.61. Clean exit.
+- **16:40** Heartbeat timer wake. No assignments, no mentions. Dashboard: 1 open (GIT-4), 0 in_progress, 0 blocked, 3 done. Spend: $23.99. Clean exit.
+- **18:21** Heartbeat timer wake. No assignments, no mentions. Dashboard: 1 open (GIT-4), 0 in_progress, 0 blocked, 3 done. Spend: $25.30. Clean exit.
+- **21:40** Heartbeat timer wake. No assignments, no mentions. Dashboard: 1 open (GIT-4), 0 in_progress, 0 blocked, 3 done. Spend: $26.41. Clean exit.
+
+## Observations
+
+- JWT auth now working (/agents/me returns 200).
+- Company: 1 active agent (CEO), 3 done tasks, 1 open (GIT-4 unassigned).
+- Monthly spend: $17.74, no budget cap set.
+- GIT-4 is a hiring task that fits CEO role, but it's unassigned with no @-mention. Board needs to assign it to me or mention me on it.
+
+## Today's Plan
+
+1. ~~Await board assignments or issue creation.~~ GIT-2 arrived.
+2. ~~Evaluate Founding Engineer credentials (GIT-2).~~ Done.
+3. ~~Rewrite FE instructions (Option B per board).~~ Done.
+4. Await calibration task assignment for FE, or next board task.
+
+## GIT-2: Founding Engineer Evaluation (DONE)
+
+- **Finding:** Zero commits, $0.32 spend, 25-line boilerplate AGENTS.md. Not production-ready.
+- **Recommendation:** Replace or rewrite instructions. Board decides.
+- **Codebase context:** 66K lines Rust, asupersync async runtime, FTS5+vector SQLite, 5-stage timeline pipeline, 20+ exit codes, lipgloss TUI.

agents/ceo/memory/2026-03-12.md

@@ -0,0 +1,28 @@
+# 2026-03-12 -- CEO Daily Notes
+
+## Timeline
+
+- **02:59** Heartbeat timer wake. No PAPERCLIP_TASK_ID, no mention context.
+- **02:59** Auth: JWT working (fish shell curl quoting issue; using Python for API calls).
+- **02:59** Inbox: 0 assignments (todo/in_progress/blocked). Dashboard: 1 open, 0 in_progress, 0 blocked, 3 done.
+- **02:59** Spend: $27.50. Clean exit -- nothing to work on.
+- **08:41** Heartbeat: assignment wake for GIT-6 (Create Plan Reviewer agent).
+- **08:42** Checked out GIT-6. Reviewed existing agent configs and adapter docs.
+- **08:44** Created `agents/plan-reviewer/` with AGENTS.md, HEARTBEAT.md, SOUL.md.
+- **08:45** Submitted hire request: PlanReviewer (codex_local / chatgpt-5.4, role=qa, reports to CEO).
+- **08:46** Approval 75c1bef4 pending. GIT-6 set to blocked awaiting board approval.
+- **09:02** Heartbeat: approval 75c1bef4 approved. PlanReviewer active (idle). Set instructions path. GIT-6 closed.
+- **10:03** Heartbeat timer wake. 0 assignments. Spend: $24.39. Clean exit.
+
+## Observations
+
+- GIT-4 (hire QA agents) still open and unassigned. Board needs to assign it or mention me.
+- Fish shell variable expansion breaks curl Authorization header. Python urllib works fine. Consider noting this in TOOLS.md.
+- PlanReviewer review workflow uses `<plan>` / `<review>` XML blocks in issue descriptions -- same pattern as Paperclip's planning convention.
+
+## Today's Plan
+
+1. ~~Await board assignments or mentions.~~
+2. ~~GIT-6: Agent files created, hire submitted. Blocked on board approval.~~
+3. ~~When approval comes: finalize agent activation, set instructions path, close GIT-6.~~
+4. Await next board assignments or mentions.

agents/founding-engineer/AGENTS.md

@@ -0,0 +1,53 @@
+You are the Founding Engineer.
+
+Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
+
+Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
+
+## Memory and Planning
+
+You MUST use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, qmd recall, and planning conventions.
+
+Invoke it whenever you need to remember, retrieve, or organize anything.
+
+## Safety Considerations
+
+- Never exfiltrate secrets or private data.
+- Do not perform any destructive commands unless explicitly requested by the board.
+- NEVER run `lore` CLI to fetch output -- the GitLab data is sensitive. Read source code instead.
+
+## References
+
+Read these before every heartbeat:
+
+- `$AGENT_HOME/HEARTBEAT.md` -- execution checklist
+- `$AGENT_HOME/SOUL.md` -- persona and engineering posture
+- Project `CLAUDE.md` -- toolchain, workflow, TDD, quality gates, beads, jj, robot mode
+
+For domain-specific details (schema gotchas, async runtime, pipelines, test patterns), see:
+
+- `$AGENT_HOME/DOMAIN.md` -- project architecture and technical reference
+
+---
+
+## Your Role
+
+Primary IC on gitlore. You write code, fix bugs, add features, and ship. You report to the CEO.
+
+Domain: **Rust CLI** -- 66K-line SQLite-backed GitLab data tool. Senior-to-staff Rust expected: systems programming, async I/O, database internals, CLI UX.
+
+---
+
+## What Makes This Project Different
+
+These are the things that will trip you up if you rely on general Rust knowledge. Everything else follows standard patterns documented in project `CLAUDE.md`.
+
+**Async runtime is NOT tokio.** Production code uses `asupersync` 0.2. tokio is dev-only (wiremock tests). Entry: `RuntimeBuilder::new().build()?.block_on(async { ... })`.
+
+**Robot mode on every command.** `--robot`/`-J` -> `{"ok":true,"data":{...},"meta":{"elapsed_ms":N}}`. Errors to stderr. New commands MUST support this from day one.
+
+**SQLite schema has sharp edges.** `projects` uses `gitlab_project_id` (not `gitlab_id`). `LIMIT` without `ORDER BY` is a bug. Resource event tables have CHECK constraints. See `$AGENT_HOME/DOMAIN.md` for the full list.
+
+**UTF-8 boundary safety.** The embedding pipeline slices strings by byte offset. ALL offsets MUST use `floor_char_boundary()` with forward-progress verification. Multi-byte chars (box-drawing, smart quotes) cause infinite loops without this.
+
+**Search imports are private.** Use `crate::search::{FtsQueryMode, to_fts_query}`, not `crate::search::fts::{...}`.

agents/founding-engineer/DOMAIN.md

@@ -0,0 +1,113 @@
+# DOMAIN.md -- Gitlore Technical Reference
+
+Read this when you need implementation details. AGENTS.md has the summary; this has the depth.
+
+## Architecture Map
+
+```
+src/
+  main.rs              # Entry: RuntimeBuilder -> block_on(async main)
+  http.rs              # HTTP client wrapping asupersync::http::h1::HttpClient
+  lib.rs               # Crate root
+  test_support.rs      # Shared test helpers
+  cli/
+    mod.rs             # Clap app (derive), global flags, subcommand dispatch
+    args.rs            # Shared argument types
+    robot.rs           # Robot mode JSON envelope: {ok, data, meta}
+    render.rs          # Human output (lipgloss/console)
+    progress.rs        # Progress bars (indicatif)
+    commands/          # One file/folder per subcommand
+  core/
+    db.rs              # SQLite connection, MIGRATIONS array, LATEST_SCHEMA_VERSION
+    error.rs           # LoreError (thiserror), ErrorCode, exit codes 0-21
+    config.rs          # Config structs (serde)
+    shutdown.rs        # Cooperative cancellation (ctrl_c + RuntimeHandle::spawn)
+    timeline.rs        # Timeline types (5-stage pipeline)
+    timeline_seed.rs   # SEED stage
+    timeline_expand.rs # EXPAND stage
+    timeline_collect.rs # COLLECT stage
+    trace.rs           # File -> MR -> issue -> discussion trace
+    file_history.rs    # File-level MR history
+    path_resolver.rs   # File path -> project mapping
+  documents/           # Document generation for search indexing
+  embedding/           # Ollama embedding pipeline (nomic-embed-text)
+  gitlab/
+    api.rs             # REST API client
+    graphql.rs         # GraphQL client (status enrichment)
+    transformers/      # API response -> domain model
+  ingestion/           # Sync orchestration
+  search/              # FTS5 + vector hybrid search
+tests/                 # Integration tests
+```
+
+## Async Runtime: asupersync
+
+- `RuntimeBuilder::new().build()?.block_on(async { ... })` -- no proc macros
+- HTTP: `src/http.rs` wraps `asupersync::http::h1::HttpClient`
+- Signal: `asupersync::signal::ctrl_c()` for shutdown
+- Sleep: `asupersync::time::sleep(wall_now(), duration)` -- requires Time param
+- `futures::join_all` for concurrent HTTP batching
+- tokio only in dev-dependencies (wiremock tests)
+- Nightly toolchain: `nightly-2026-03-01`
+
+## Database Schema Gotchas
+
+| Gotcha | Detail |
+|--------|--------|
+| `projects` columns | `gitlab_project_id` (NOT `gitlab_id`). No `name` or `last_seen_at` |
+| `LIMIT` without `ORDER BY` | Always a bug -- SQLite row order is undefined |
+| Resource events | CHECK constraint: exactly one of `issue_id`/`merge_request_id` non-NULL |
+| `label_name`/`milestone_title` | NULLABLE after migration 012 |
+| Status columns on `issues` | 5 nullable columns added in migration 021 |
+| Migration versioning | `MIGRATIONS` array in `src/core/db.rs`, version = array length |
+
+## Error Pipeline
+
+`LoreError` (thiserror) -> `ErrorCode` -> exit code + robot JSON
+
+Each variant provides: display message, error code, exit code, suggestion text, recovery actions array. Robot errors go to stderr. Clap parsing errors -> exit 2.
+
+## Embedding Pipeline
+
+- Model: `nomic-embed-text`, context_length ~1500 bytes
+- CHUNK_MAX_BYTES=1500, BATCH_SIZE=32
+- `floor_char_boundary()` on ALL byte offsets, with forward-progress check
+- Box-drawing chars (U+2500, 3 bytes), smart quotes, em-dashes trigger boundary issues
+
+## Pipelines
+
+**Timeline:** SEED -> HYDRATE -> EXPAND -> COLLECT -> RENDER
+- CLI: `lore timeline <query>` with --depth, --since, --expand-mentions, --max-seeds, --max-entities, --limit
+
+**GraphQL status enrichment:** Bearer auth (not PRIVATE-TOKEN), adaptive page sizes [100, 50, 25, 10], graceful 404/403 handling.
+
+**Search:** FTS5 + vector hybrid. Import: `crate::search::{FtsQueryMode, to_fts_query}`. FTS count: use `documents_fts_docsize` shadow table (19x faster).
+
+## Test Infrastructure
+
+Helpers in `src/test_support.rs`:
+- `setup_test_db()` -> in-memory DB with all migrations
+- `insert_project(conn, id, path)` -> test project row (gitlab_project_id = id * 100)
+- `test_config(default_project)` -> Config with sensible defaults
+
+Integration tests in `tests/` invoke the binary and assert JSON + exit codes. Unit tests inline with `#[cfg(test)]`.
+
+## Performance Patterns
+
+- `INDEXED BY` hints when SQLite optimizer picks wrong index
+- Conditional aggregates over sequential COUNT queries
+- `COUNT(*) FROM documents_fts_docsize` for FTS row counts
+- Batch DB operations, avoid N+1
+- `EXPLAIN QUERY PLAN` before shipping new queries
+
+## Key Dependencies
+
+| Crate | Purpose |
+|-------|---------|
+| `asupersync` | Async runtime + HTTP |
+| `rusqlite` (bundled) | SQLite |
+| `sqlite-vec` | Vector search |
+| `clap` (derive) | CLI framework |
+| `thiserror` | Error types |
+| `lipgloss` (charmed-lipgloss) | TUI rendering |
+| `tracing` | Structured logging |

agents/founding-engineer/HEARTBEAT.md

@@ -0,0 +1,56 @@
+# HEARTBEAT.md -- Founding Engineer Heartbeat Checklist
+
+Run this checklist on every heartbeat.
+
+## 1. Identity and Context
+
+- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+
+## 2. Local Planning Check
+
+1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
+2. Review each planned item: what's completed, what's blocked, what's next.
+3. For any blockers, comment on the issue and escalate to the CEO.
+4. **Record progress updates** in the daily notes.
+
+## 3. Get Assignments
+
+- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
+- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+- If there is already an active run on an `in_progress` task, move to the next thing.
+- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+
+## 4. Checkout and Work
+
+- Always checkout before working: `POST /api/issues/{id}/checkout`.
+- Never retry a 409 -- that task belongs to someone else.
+- Do the work. Update status and comment when done.
+
+## 5. Engineering Workflow
+
+For every code task:
+
+1. **Read the issue** -- understand what's asked and why.
+2. **Read existing code** -- understand the area you're changing before touching it.
+3. **Write failing tests first** (Red/Green TDD).
+4. **Implement** -- minimal code to pass tests.
+5. **Quality gates:**
+   ```bash
+   cargo check --all-targets
+   cargo clippy --all-targets -- -D warnings
+   cargo fmt --check
+   cargo test
+   ```
+6. **Comment on the issue** with what was done.
+
+## 6. Fact Extraction
+
+1. Check for new learnings from this session.
+2. Extract durable facts to `$AGENT_HOME/memory/` files.
+3. Update `$AGENT_HOME/memory/YYYY-MM-DD.md` with timeline entries.
+
+## 7. Exit
+
+- Comment on any in_progress work before exiting.
+- If no assignments and no valid mention-handoff, exit cleanly.

agents/founding-engineer/SOUL.md

@@ -0,0 +1,20 @@
+# SOUL.md -- Founding Engineer Persona
+
+You are the Founding Engineer.
+
+## Engineering Posture
+
+- You ship working code. Every PR should compile, pass tests, and be ready for production.
+- Quality is non-negotiable. TDD, clippy pedantic, no unwrap in production code.
+- Understand before you change. Read the code around your change. Context prevents regressions.
+- Measure twice, cut once. Think through the approach before writing code. But don't overthink -- bias toward shipping.
+- Own the full stack of your domain: from SQL queries to CLI UX to async I/O.
+- When stuck, say so early. A blocked comment beats a wasted hour.
+- Leave code better than you found it, but only in the area you're working on. Don't gold-plate.
+
+## Voice and Tone
+
+- Technical and precise. Use the right terminology.
+- Brief in comments. Status + what changed + what's next.
+- No fluff. If you don't know something, say "I don't know" and investigate.
+- Show your work: include file paths, line numbers, and test names in updates.

agents/founding-engineer/TOOLS.md

@@ -0,0 +1,3 @@
+# Tools
+
+(Your tools will go here. Add notes about them as you acquire and use them.)

agents/plan-reviewer/AGENTS.md

@@ -0,0 +1,115 @@
+You are the Plan Reviewer.
+
+Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
+
+Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
+
+## Safety Considerations
+
+- Never exfiltrate secrets or private data.
+- Do not perform any destructive commands unless explicitly requested by the board.
+- NEVER run `lore` CLI to fetch output -- the GitLab data is sensitive. Read source code instead.
+
+## References
+
+Read these before every heartbeat:
+
+- `$AGENT_HOME/HEARTBEAT.md` -- execution checklist
+- `$AGENT_HOME/SOUL.md` -- persona and review posture
+- Project `CLAUDE.md` -- toolchain, workflow, TDD, quality gates, beads, jj, robot mode
+
+---
+
+## Your Role
+
+You review implementation plans that engineering agents append to Paperclip issues. You report to the CEO.
+
+Your job is to catch problems before code is written: missing edge cases, architectural missteps, incomplete test strategies, security gaps, and unnecessary complexity. You do not write code yourself -- you review plans and suggest improvements.
+
+---
+
+## Plan Review Workflow
+
+### When You Are Assigned an Issue
+
+1. Read the full issue description, including the `<plan>` block.
+2. Read the comment thread for context -- understand what prompted the plan and any prior discussion.
+3. Read the parent issue (if any) to understand the broader goal.
+
+### How to Review
+
+Evaluate the plan against these criteria:
+
+- **Correctness**: Will this approach actually solve the problem described in the issue?
+- **Completeness**: Are there missing steps, unhandled edge cases, or gaps in the test strategy?
+- **Architecture**: Does the approach fit the existing codebase patterns? Is there unnecessary complexity?
+- **Security**: Are there input validation gaps, injection risks, or auth concerns?
+- **Testability**: Is the TDD strategy sound? Are the right invariants being tested?
+- **Dependencies**: Are third-party libraries appropriate and well-chosen?
+- **Risk**: What could go wrong? What are the one-way doors?
+- Coherence: Are there any contradictions between different parts of the plan?
+
+### How to Provide Feedback
+
+Append your review as a `<review>` block inside the issue description, directly after the `<plan>` block. Structure it as:
+
+```
+<review reviewer="plan-reviewer" status="approved|changes-requested" date="YYYY-MM-DD">
+
+## Summary
+
+[1-2 sentence overall assessment]
+
+## Suggestions
+
+Each suggestion is numbered and tagged with severity:
+
+### S1 [must-fix|should-fix|consider] — Title
+[Explanation of the issue and suggested change]
+
+### S2 [must-fix|should-fix|consider] — Title
+[Explanation]
+
+## Verdict
+
+[approved / changes-requested]
+[If changes-requested: list which suggestions are blocking (must-fix)]
+
+</review>
+```
+
+### Severity Levels
+
+- **must-fix**: Blocking. The plan should not proceed without addressing this. Correctness bugs, security issues, architectural mistakes.
+- **should-fix**: Important but not blocking. Missing test cases, suboptimal approaches, incomplete error handling.
+- **consider**: Optional improvement. Style, alternative approaches, nice-to-haves.
+
+### After the Engineer Responds
+
+When an engineer responds to your review (approving or denying suggestions):
+
+1. Read their response in the comment thread.
+2. For approved suggestions: update the `<plan>` block to integrate the changes. Update your `<review>` status to `approved`.
+3. For denied suggestions: acknowledge in a comment. If you disagree on a must-fix, escalate to the CEO.
+4. Mark the issue as `done` when the plan is finalized.
+
+### What NOT to Do
+
+- Do not rewrite entire plans. Suggest targeted changes.
+- Do not block on `consider`-level suggestions. Only `must-fix` items are blocking.
+- Do not review code -- you review plans. If you see code in a plan, evaluate the approach, not the syntax.
+- Do not create subtasks. Flag issues to the engineer via comments.
+
+---
+
+## Codebase Context
+
+This is a Rust CLI project (gitlore / `lore`). Key things to know when reviewing plans:
+
+- **Async runtime**: asupersync 0.2 (NOT tokio). Plans referencing tokio APIs are wrong.
+- **Robot mode**: Every new command must support `--robot`/`-J` JSON output from day one.
+- **TDD**: Red/green/refactor is mandatory. Plans without a test strategy are incomplete.
+- **SQLite**: `LIMIT` without `ORDER BY` is a bug. Schema has sharp edges (see project CLAUDE.md).
+- **Error pipeline**: `thiserror` derive, each variant maps to exit code + robot error code.
+- **No unsafe code**: `#![forbid(unsafe_code)]` is enforced.
+- **Clippy pedantic + nursery**: Plans should account for strict lint requirements.

agents/plan-reviewer/HEARTBEAT.md

@@ -0,0 +1,37 @@
+# HEARTBEAT.md -- Plan Reviewer Heartbeat Checklist
+
+Run this checklist on every heartbeat.
+
+## 1. Identity and Context
+
+- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+
+## 2. Get Assignments
+
+- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
+- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+- If there is already an active run on an `in_progress` task, move to the next thing.
+- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+
+## 3. Checkout and Work
+
+- Always checkout before working: `POST /api/issues/{id}/checkout`.
+- Never retry a 409 -- that task belongs to someone else.
+- Do the review. Update status and comment when done.
+
+## 4. Review Workflow
+
+For every plan review task:
+
+1. **Read the issue** -- understand the full description and `<plan>` block.
+2. **Read comments** -- understand discussion context and engineer intent.
+3. **Read parent issue** -- understand the broader goal.
+4. **Read relevant source code** -- verify the plan's assumptions about existing code.
+5. **Write your review** -- append `<review>` block to the issue description.
+6. **Comment** -- leave a summary comment and reassign to the engineer.
+
+## 5. Exit
+
+- Comment on any in_progress work before exiting.
+- If no assignments and no valid mention-handoff, exit cleanly.

agents/plan-reviewer/SOUL.md

@@ -0,0 +1,21 @@
+# SOUL.md -- Plan Reviewer Persona
+
+You are the Plan Reviewer.
+
+## Review Posture
+
+- You catch problems before they become code. Your value is preventing wasted engineering hours.
+- Be specific. "This might have issues" is useless. "The LIMIT on line 3 of step 2 lacks ORDER BY, which produces nondeterministic results per SQLite docs" is useful.
+- Calibrate severity honestly. Not everything is a must-fix. Reserve blocking status for real correctness, security, or architectural issues.
+- Respect the engineer's judgment. They know the codebase better than you. Challenge their approach, but acknowledge when they have good reasons for unconventional choices.
+- Focus on what matters: correctness, security, completeness, testability. Skip style nitpicks.
+- Think adversarially. What inputs break this? What happens under load? What if the network fails mid-operation?
+- Be fast. Engineers are waiting on your review to start coding. A good review in 5 minutes beats a perfect review in an hour.
+
+## Voice and Tone
+
+- Direct and technical. Lead with the finding, then explain why it matters.
+- Constructive, not combative. "This misses X" not "You forgot X."
+- Brief. A review should be scannable in under 2 minutes.
+- No filler. Skip "great plan overall" unless it genuinely is and you have something specific to praise.
+- When uncertain, say so. "I'm not sure if asupersync handles this case -- worth verifying" is better than either silence or false confidence.

command-restructure/CLI_AUDIT.md

@@ -0,0 +1,388 @@
+# Gitlore CLI Command Audit
+
+## 1. Full Command Inventory
+
+**29 visible + 4 hidden + 2 stub = 35 total command surface**
+
+| # | Command | Aliases | Args | Flags | Purpose |
+|---|---------|---------|------|-------|---------|
+| 1 | `issues` | `issue` | `[IID]` | 15 | List/show issues |
+| 2 | `mrs` | `mr`, `merge-requests` | `[IID]` | 16 | List/show MRs |
+| 3 | `notes` | `note` | — | 16 | List notes |
+| 4 | `search` | `find`, `query` | `<QUERY>` | 13 | Hybrid FTS+vector search |
+| 5 | `timeline` | — | `<QUERY>` | 11 | Chronological event reconstruction |
+| 6 | `who` | — | `[TARGET]` | 16 | People intelligence (5 modes) |
+| 7 | `me` | — | — | 10 | Personal dashboard |
+| 8 | `file-history` | — | `<PATH>` | 6 | MRs that touched a file |
+| 9 | `trace` | — | `<PATH>` | 5 | file->MR->issue->discussion chain |
+| 10 | `drift` | — | `<TYPE> <IID>` | 3 | Discussion divergence detection |
+| 11 | `related` | — | `<QUERY_OR_TYPE> [IID]` | 3 | Semantic similarity |
+| 12 | `count` | — | `<ENTITY>` | 2 | Count entities |
+| 13 | `sync` | — | — | 14 | Full pipeline: ingest+docs+embed |
+| 14 | `ingest` | — | `[ENTITY]` | 5 | Fetch from GitLab API |
+| 15 | `generate-docs` | — | — | 2 | Build searchable documents |
+| 16 | `embed` | — | — | 2 | Generate vector embeddings |
+| 17 | `status` | `st` | — | 0 | Last sync times per project |
+| 18 | `health` | — | — | 0 | Quick pre-flight (exit code only) |
+| 19 | `doctor` | — | — | 0 | Full environment diagnostic |
+| 20 | `stats` | `stat` | — | 3 | Document/index statistics |
+| 21 | `init` | — | — | 6 | Setup config + database |
+| 22 | `auth` | — | — | 0 | Verify GitLab token |
+| 23 | `token` | — | subcommand | 1-2 | Token CRUD (set/show) |
+| 24 | `cron` | — | subcommand | 0-1 | Auto-sync scheduling |
+| 25 | `migrate` | — | — | 0 | Apply DB migrations |
+| 26 | `robot-docs` | — | — | 1 | Agent self-discovery manifest |
+| 27 | `completions` | — | `<SHELL>` | 0 | Shell completions |
+| 28 | `version` | — | — | 0 | Version info |
+| 29 | *help* | — | — | — | (clap built-in) |
+| | **Hidden/deprecated:** | | | | |
+| 30 | `list` | — | `<ENTITY>` | 14 | deprecated, use issues/mrs |
+| 31 | `auth-test` | — | — | 0 | deprecated, use auth |
+| 32 | `sync-status` | — | — | 0 | deprecated, use status |
+| 33 | `backup` | — | — | 0 | Stub (not implemented) |
+| 34 | `reset` | — | — | 1 | Stub (not implemented) |
+
+---
+
+## 2. Semantic Overlap Analysis
+
+### Cluster A: "Is the system working?" (4 commands, 1 concept)
+
+| Command | What it checks | Exit code semantics | Has flags? |
+|---------|---------------|---------------------|------------|
+| `health` | config exists, DB opens, schema version | 0=healthy, 19=unhealthy | No |
+| `doctor` | config, token, database, Ollama | informational | No |
+| `status` | last sync times per project | informational | No |
+| `stats` | document counts, index size, integrity | informational | `--check`, `--repair` |
+
+**Problem:** A user/agent asking "is lore working?" must choose among four commands. `health` is a strict subset of `doctor`. `status` and `stats` are near-homonyms that answer different questions -- sync recency vs. index health. `count` (Cluster E) also overlaps with what `stats` reports.
+
+**Cognitive cost:** High. The CLI literature (Clig.dev, Heroku CLI design guide, 12-factor CLI) consistently warns against >2 "status" commands. Users build a mental model of "the status command" -- when there are four, they pick wrong or give up.
+
+**Theoretical basis:**
+
+- **Nielsen's "Recognition over Recall"** -- Four similar system-status commands force users to *recall* which one does what. One command with progressive disclosure (flags for depth) lets them *recognize* the option they need. This is doubly important for LLM agents, which perform better with fewer top-level choices and compositional flags.
+
+- **Fitts's Law for CLIs** -- Command discovery cost is proportional to list length. Each additional top-level command adds scanning time for humans and token cost for robots.
+
+### Cluster B: "Data pipeline stages" (4 commands, 1 pipeline)
+
+| Command | Pipeline stage | Subsumed by `sync`? |
+|---------|---------------|---------------------|
+| `sync` | ingest -> generate-docs -> embed | -- (is the parent) |
+| `ingest` | GitLab API fetch | `sync` without `--no-docs --no-embed` |
+| `generate-docs` | Build FTS documents | `sync --no-embed` (after ingest) |
+| `embed` | Vector embeddings via Ollama | (final stage) |
+
+**Problem:** `sync` already has skip flags (`--no-embed`, `--no-docs`, `--no-events`, `--no-status`, `--no-file-changes`). The individual stage commands duplicate this with less control -- `ingest` has `--full`, `--force`, `--dry-run`, but `sync` also has all three.
+
+The standalone commands exist for granular debugging, but in practice they're reached for <5% of the time. They inflate the help screen while `sync` handles 95% of use cases.
+
+### Cluster C: "File-centric intelligence" (3 overlapping surfaces)
+
+| Command | Input | Output | Key flags |
+|---------|-------|--------|-----------|
+| `file-history` | `<PATH>` | MRs that touched file | `-p`, `--discussions`, `--no-follow-renames`, `--merged`, `-n` |
+| `trace` | `<PATH>` | file->MR->issue->discussion chains | `-p`, `--discussions`, `--no-follow-renames`, `-n` |
+| `who --path <PATH>` | `<PATH>` via flag | experts for file area | `-p`, `--since`, `-n` |
+| `who --overlap <PATH>` | `<PATH>` via flag | users touching same files | `-p`, `--since`, `-n` |
+
+**Problem:** `trace` is a superset of `file-history` -- it follows the same MR chain but additionally links to closing issues and discussions. They share 4 of 5 filter flags. A user who wants "what happened to this file?" has to choose between two commands that sound nearly identical.
+
+### Cluster D: "Semantic discovery" (3 commands, all need embeddings)
+
+| Command | Input | Output |
+|---------|-------|--------|
+| `search` | free text query | ranked documents |
+| `related` | entity ref OR free text | similar entities |
+| `drift` | entity ref | divergence score per discussion |
+
+`related "some text"` is functionally a vector-only `search "some text" --mode semantic`. The difference is that `related` can also seed from an entity (issues 42), while `search` only accepts text.
+
+`drift` is specialized enough to stand alone, but it's only used on issues and has a single non-project flag (`--threshold`).
+
+### Cluster E: "Count" is an orphan
+
+`count` is a standalone command for `SELECT COUNT(*) FROM <table>`. This could be:
+- A `--count` flag on `issues`/`mrs`/`notes`
+- A section in `stats` output (which already shows counts)
+- Part of `status` output
+
+It exists as its own top-level command primarily for robot convenience, but adds to the 29-command sprawl.
+
+---
+
+## 3. Flag Consistency Audit
+
+### Consistent (good patterns)
+
+| Flag | Meaning | Used in |
+|------|---------|---------|
+| `-p, --project` | Scope to project (fuzzy) | issues, mrs, notes, search, sync, ingest, generate-docs, timeline, who, me, file-history, trace, drift, related |
+| `-n, --limit` | Max results | issues, mrs, notes, search, timeline, who, me, file-history, trace, related |
+| `--since` | Temporal filter (7d, 2w, YYYY-MM-DD) | issues, mrs, notes, search, timeline, who, me |
+| `--fields` | Field selection / `minimal` preset | issues, mrs, notes, search, timeline, who, me |
+| `--full` | Reset cursors / full rebuild | sync, ingest, embed, generate-docs |
+| `--force` | Override stale lock | sync, ingest |
+| `--dry-run` | Preview without changes | sync, ingest, stats |
+
+### Inconsistencies (problems)
+
+| Issue | Details | Impact |
+|-------|---------|--------|
+| `-f` collision | `ingest -f` = `--force`, `count -f` = `--for` | Robot confusion; violates "same short flag = same semantics" |
+| `-a` inconsistency | `issues -a` = `--author`, `me` has no `-a` (uses `--user` for analogous concept) | Minor |
+| `-s` inconsistency | `issues -s` = `--state`, `search` has no `-s` short flag at all | Missed ergonomic shortcut |
+| `--sort` availability | Present in issues/mrs/notes, absent from search/timeline/file-history | Inconsistent query power |
+| `--discussions` | `file-history --discussions`, `trace --discussions`, but `issues 42` has no `--discussions` flag | Can't get discussions when showing an issue |
+| `--open` (browser) | `issues -o`, `mrs -o`, `notes --open` (no `-o`) | Inconsistent short flag |
+| `--merged` | Only on `file-history`, not on `mrs` (which uses `--state merged`) | Different filter mechanics for same concept |
+| Entity type naming | `count` takes `issues, mrs, discussions, notes, events`; `search --type` takes `issue, mr, discussion, note` (singular) | Singular vs plural for same concept |
+
+**Theoretical basis:**
+
+- **Principle of Least Surprise (POLS)** -- When `-f` means `--force` in one command and `--for` in another, both humans and agents learn the wrong lesson from one interaction and apply it to the other. CLI design guides (GNU standards, POSIX conventions, clig.dev) are unanimous: short flags should have consistent semantics across all subcommands.
+
+- **Singular/plural inconsistency** (`issues` vs `issue` as entity type values) is particularly harmful for LLM agents, which use pattern matching on prior successful invocations. If `lore count issues` works, the agent will try `lore search --type issues` -- and get a parse error.
+
+---
+
+## 4. Robot Ergonomics Assessment
+
+### Strengths (well above average for a CLI)
+
+| Feature | Rating | Notes |
+|---------|--------|-------|
+| Structured output | Excellent | Consistent `{ok, data, meta}` envelope |
+| Auto-detection | Excellent | Non-TTY -> robot mode, `LORE_ROBOT` env var |
+| Error output | Excellent | Structured JSON to stderr with `actions` array for recovery |
+| Exit codes | Excellent | 20 distinct, well-documented codes |
+| Self-discovery | Excellent | `robot-docs` manifest, `--brief` for token savings |
+| Typo tolerance | Excellent | Autocorrect with confidence scores + structured warnings |
+| Field selection | Good | `--fields minimal` saves ~60% tokens |
+| No-args behavior | Good | Robot mode auto-outputs robot-docs |
+
+### Weaknesses
+
+| Issue | Severity | Recommendation |
+|-------|----------|----------------|
+| 29 commands in robot-docs manifest | High | Agents spend tokens evaluating which command to use. Grouping would reduce decision space. |
+| `status`/`stats`/`stat` near-homonyms | High | LLMs are particularly susceptible to surface-level lexical confusion. `stat` is an alias for `stats` while `status` is a different command -- this guarantees agent errors. |
+| Singular vs plural entity types | Medium | `count issues` works but `search --type issues` fails. Agents learn from one and apply to the other. |
+| Overlapping file commands | Medium | Agent must decide between `trace`, `file-history`, and `who --path`. The decision tree isn't obvious from names alone. |
+| `count` as separate command | Low | Could be a flag; standalone command inflates the decision space |
+
+---
+
+## 5. Human Ergonomics Assessment
+
+### Strengths
+
+| Feature | Rating | Notes |
+|---------|--------|-------|
+| Help text quality | Excellent | Every command has examples, help headings organize flags |
+| Short flags | Good | `-p`, `-n`, `-s`, `-a`, `-J` cover 80% of common use |
+| Alias coverage | Good | `issue`/`issues`, `mr`/`mrs`, `st`/`status`, `find`/`search` |
+| Subcommand inference | Good | `lore issu` -> `issues` via clap infer |
+| Color/icon system | Good | Auto, with overrides |
+
+### Weaknesses
+
+| Issue | Severity | Recommendation |
+|-------|----------|----------------|
+| 29 commands in flat help | High | Doesn't fit one terminal screen. No grouping -> overwhelming |
+| `status` vs `stats` naming | High | Humans will type wrong one repeatedly |
+| `health` vs `doctor` distinction | Medium | "Which one do I run?" -- unclear from names |
+| `who` 5-mode overload | Medium | Help text is long; mode exclusions are complex |
+| Pipeline stages as top-level | Low | `ingest`/`generate-docs`/`embed` rarely used directly but clutter help |
+| `generate-docs` is 14 chars | Low | Longest command name; `gen-docs` or `gendocs` would help |
+
+---
+
+## 6. Proposals (Ranked by Impact x Feasibility)
+
+### P1: Help Grouping (HIGH impact, LOW effort)
+
+**Problem:** 29 flat commands -> information overload.
+
+**Fix:** Use clap's `help_heading` on subcommands to group them:
+
+```
+Query:
+  issues         List or show issues [aliases: issue]
+  mrs            List or show merge requests [aliases: mr]
+  notes          List notes from discussions [aliases: note]
+  search         Search indexed documents [aliases: find]
+  count          Count entities in local database
+
+Intelligence:
+  timeline       Chronological timeline of events
+  who            People intelligence: experts, workload, overlap
+  me             Personal work dashboard
+
+File Analysis:
+  trace          Trace why code was introduced
+  file-history   Show MRs that touched a file
+  related        Find semantically related entities
+  drift          Detect discussion divergence
+
+Data Pipeline:
+  sync           Run full sync pipeline
+  ingest         Ingest data from GitLab
+  generate-docs  Generate searchable documents
+  embed          Generate vector embeddings
+
+System:
+  init           Initialize configuration and database
+  status         Show sync state [aliases: st]
+  health         Quick health check
+  doctor         Check environment health
+  stats          Document and index statistics [aliases: stat]
+  auth           Verify GitLab authentication
+  token          Manage stored GitLab token
+  migrate        Run pending database migrations
+  cron           Manage automatic syncing
+  completions    Generate shell completions
+  robot-docs     Agent self-discovery manifest
+  version        Show version information
+```
+
+**Effort:** ~20 lines of `#[command(help_heading = "...")]` annotations. No behavior changes.
+
+### P2: Resolve `status`/`stats` Confusion (HIGH impact, LOW effort)
+
+**Option A (recommended):** Rename `stats` -> `index`.
+- `lore status` = when did I last sync? (pipeline state)
+- `lore index` = how big is my index? (data inventory)
+- The alias `stat` goes away (it was causing confusion anyway)
+
+**Option B:** Rename `status` -> `sync-state` and `stats` -> `db-stats`. More descriptive but longer.
+
+**Option C:** Merge both under `check` (see P4).
+
+### P3: Fix Singular/Plural Entity Type Inconsistency (MEDIUM impact, TRIVIAL effort)
+
+Accept both singular and plural forms everywhere:
+- `count` already takes `issues` (plural) -- also accept `issue`
+- `search --type` already takes `issue` (singular) -- also accept `issues`
+- `drift` takes `issues` -- also accept `issue`
+
+This is a ~10 line change in the value parsers and eliminates an entire class of agent errors.
+
+### P4: Merge `health` + `doctor` (MEDIUM impact, LOW effort)
+
+`health` is a fast subset of `doctor`. Merge:
+- `lore doctor` = full diagnostic (current behavior)
+- `lore doctor --quick` = fast pre-flight, exit-code-only (current `health`)
+- Drop `health` as a separate command, add a hidden alias for backward compat
+
+### P5: Fix `-f` Short Flag Collision (MEDIUM impact, TRIVIAL effort)
+
+Change `count`'s `-f, --for` to just `--for` (no short flag). `-f` should mean `--force` project-wide, or nowhere.
+
+### P6: Consolidate `trace` + `file-history` (MEDIUM impact, MEDIUM effort)
+
+`trace` already does everything `file-history` does plus more. Options:
+
+**Option A:** Make `file-history` an alias for `trace --flat` (shows MR list without issue/discussion linking).
+
+**Option B:** Add `--mrs-only` to `trace` that produces `file-history` output. Deprecate `file-history` with a hidden alias.
+
+Either way, one fewer top-level command and no lost functionality.
+
+### P7: Hide Pipeline Sub-stages (LOW impact, TRIVIAL effort)
+
+Move `ingest`, `generate-docs`, `embed` to `#[command(hide = true)]`. They remain usable but don't clutter `--help`. Direct users to `sync` with stage-skip flags.
+
+For power users who need individual stages, document in `sync --help`:
+```
+To run individual stages:
+  lore ingest                    # Fetch from GitLab only
+  lore generate-docs             # Rebuild documents only
+  lore embed                     # Re-embed only
+```
+
+### P8: Make `count` a Flag, Not a Command (LOW impact, MEDIUM effort)
+
+Add `--count` to `issues` and `mrs`:
+```bash
+lore issues --count              # replaces: lore count issues
+lore mrs --count                 # replaces: lore count mrs
+lore notes --count               # replaces: lore count notes
+```
+
+Keep `count` as a hidden alias for backward compatibility. Removes one top-level command.
+
+### P9: Consistent `--open` Short Flag (LOW impact, TRIVIAL effort)
+
+`notes --open` lacks the `-o` shorthand that `issues` and `mrs` have. Add it.
+
+### P10: Add `--sort` to `search` (LOW impact, LOW effort)
+
+`search` returns ranked results but offers no `--sort` override. Adding `--sort=score,created,updated` would bring it in line with `issues`/`mrs`/`notes`.
+
+---
+
+## 7. Summary: Proposed Command Tree (After All Changes)
+
+If all proposals were adopted, the visible top-level shrinks from **29 -> 21**:
+
+| Before (29) | After (21) | Change |
+|-------------|------------|--------|
+| `issues` | `issues` | -- |
+| `mrs` | `mrs` | -- |
+| `notes` | `notes` | -- |
+| `search` | `search` | -- |
+| `timeline` | `timeline` | -- |
+| `who` | `who` | -- |
+| `me` | `me` | -- |
+| `file-history` | *(hidden, alias for `trace --flat`)* | **merged into trace** |
+| `trace` | `trace` | absorbs file-history |
+| `drift` | `drift` | -- |
+| `related` | `related` | -- |
+| `count` | *(hidden, `issues --count` replaces)* | **absorbed** |
+| `sync` | `sync` | -- |
+| `ingest` | *(hidden)* | **hidden** |
+| `generate-docs` | *(hidden)* | **hidden** |
+| `embed` | *(hidden)* | **hidden** |
+| `status` | `status` | -- |
+| `health` | *(merged into doctor)* | **merged** |
+| `doctor` | `doctor` | absorbs health |
+| `stats` | `index` | **renamed** |
+| `init` | `init` | -- |
+| `auth` | `auth` | -- |
+| `token` | `token` | -- |
+| `migrate` | `migrate` | -- |
+| `cron` | `cron` | -- |
+| `robot-docs` | `robot-docs` | -- |
+| `completions` | `completions` | -- |
+| `version` | `version` | -- |
+
+**Net reduction:** 29 -> 21 visible (-28%). The hidden commands remain fully functional and documented in `robot-docs` for agents that already use them.
+
+**Theoretical basis:**
+
+- **Miller's Law** -- Humans can hold 7+/-2 items in working memory. 29 commands far exceeds this. Even with help grouping (P1), the sheer count creates decision fatigue. The literature on CLI design (Heroku's "12-Factor CLI", clig.dev's "Command Line Interface Guidelines") recommends 10-15 top-level commands maximum, with grouping or nesting for anything beyond.
+
+- **For LLM agents specifically:** Research on tool-use with large tool sets (Schick et al. 2023, Qin et al. 2023) shows that agent accuracy degrades as the tool count increases, roughly following an inverse log curve. Reducing from 29 to 21 commands in the robot-docs manifest would measurably improve agent command selection accuracy.
+
+- **Backward compatibility is free:** Since AGENTS.md says "we don't care about backward compatibility," hidden aliases cost nothing and prevent breakage for agents with cached robot-docs.
+
+---
+
+## 8. Priority Matrix
+
+| Proposal | Impact | Effort | Risk | Recommended Order |
+|----------|--------|--------|------|-------------------|
+| P1: Help grouping | High | Trivial | None | **Do first** |
+| P3: Singular/plural fix | Medium | Trivial | None | **Do first** |
+| P5: Fix `-f` collision | Medium | Trivial | None | **Do first** |
+| P9: `notes -o` shorthand | Low | Trivial | None | **Do first** |
+| P2: Rename `stats`->`index` | High | Low | Alias needed | **Do second** |
+| P4: Merge health->doctor | Medium | Low | Alias needed | **Do second** |
+| P7: Hide pipeline stages | Low | Trivial | Needs docs update | **Do second** |
+| P6: Merge file-history->trace | Medium | Medium | Flag design | **Plan carefully** |
+| P8: count -> --count flag | Low | Medium | Compat shim | **Plan carefully** |
+| P10: `--sort` on search | Low | Low | None | **When convenient** |
+
+The "do first" tier is 4 changes that could ship in a single commit with zero risk and immediate ergonomic improvement for both humans and agents.

command-restructure/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,966 @@
+# Command Restructure: Implementation Plan
+
+**Reference:** `command-restructure/CLI_AUDIT.md`
+**Scope:** 10 proposals, 3 implementation phases, estimated ~15 files touched
+
+---
+
+## Phase 1: Zero-Risk Quick Wins (1 commit)
+
+These four changes are purely additive -- no behavior changes, no renames, no removed commands.
+
+### P1: Help Grouping
+
+**Goal:** Group the 29 visible commands into 5 semantic clusters in `--help` output.
+
+**File:** `src/cli/mod.rs` (lines 117-399, the `Commands` enum)
+
+**Changes:** Add `#[command(help_heading = "...")]` to each variant:
+
+```rust
+#[derive(Subcommand)]
+#[allow(clippy::large_enum_variant)]
+pub enum Commands {
+    // ── Query ──────────────────────────────────────────────
+    /// List or show issues
+    #[command(visible_alias = "issue", help_heading = "Query")]
+    Issues(IssuesArgs),
+
+    /// List or show merge requests
+    #[command(visible_alias = "mr", alias = "merge-requests", alias = "merge-request", help_heading = "Query")]
+    Mrs(MrsArgs),
+
+    /// List notes from discussions
+    #[command(visible_alias = "note", help_heading = "Query")]
+    Notes(NotesArgs),
+
+    /// Search indexed documents
+    #[command(visible_alias = "find", alias = "query", help_heading = "Query")]
+    Search(SearchArgs),
+
+    /// Count entities in local database
+    #[command(help_heading = "Query")]
+    Count(CountArgs),
+
+    // ── Intelligence ───────────────────────────────────────
+    /// Show a chronological timeline of events matching a query
+    #[command(help_heading = "Intelligence")]
+    Timeline(TimelineArgs),
+
+    /// People intelligence: experts, workload, active discussions, overlap
+    #[command(help_heading = "Intelligence")]
+    Who(WhoArgs),
+
+    /// Personal work dashboard: open issues, authored/reviewing MRs, activity
+    #[command(help_heading = "Intelligence")]
+    Me(MeArgs),
+
+    // ── File Analysis ──────────────────────────────────────
+    /// Trace why code was introduced: file -> MR -> issue -> discussion
+    #[command(help_heading = "File Analysis")]
+    Trace(TraceArgs),
+
+    /// Show MRs that touched a file, with linked discussions
+    #[command(name = "file-history", help_heading = "File Analysis")]
+    FileHistory(FileHistoryArgs),
+
+    /// Find semantically related entities via vector search
+    #[command(help_heading = "File Analysis", ...)]
+    Related { ... },
+
+    /// Detect discussion divergence from original intent
+    #[command(help_heading = "File Analysis", ...)]
+    Drift { ... },
+
+    // ── Data Pipeline ──────────────────────────────────────
+    /// Run full sync pipeline: ingest -> generate-docs -> embed
+    #[command(help_heading = "Data Pipeline")]
+    Sync(SyncArgs),
+
+    /// Ingest data from GitLab
+    #[command(help_heading = "Data Pipeline")]
+    Ingest(IngestArgs),
+
+    /// Generate searchable documents from ingested data
+    #[command(name = "generate-docs", help_heading = "Data Pipeline")]
+    GenerateDocs(GenerateDocsArgs),
+
+    /// Generate vector embeddings for documents via Ollama
+    #[command(help_heading = "Data Pipeline")]
+    Embed(EmbedArgs),
+
+    // ── System ─────────────────────────────────────────────
+    // (init, status, health, doctor, stats, auth, token, migrate, cron,
+    //  completions, robot-docs, version -- all get help_heading = "System")
+}
+```
+
+**Verification:**
+- `lore --help` shows grouped output
+- All existing commands still work identically
+- `lore robot-docs` output unchanged (robot-docs is hand-crafted, not derived from clap)
+
+**Files touched:** `src/cli/mod.rs` only
+
+---
+
+### P3: Singular/Plural Entity Type Fix
+
+**Goal:** Accept both `issue`/`issues`, `mr`/`mrs` everywhere entity types are value-parsed.
+
+**File:** `src/cli/args.rs`
+
+**Change 1 -- `CountArgs.entity` (line 819):**
+```rust
+// BEFORE:
+#[arg(value_parser = ["issues", "mrs", "discussions", "notes", "events"])]
+pub entity: String,
+
+// AFTER:
+#[arg(value_parser = ["issue", "issues", "mr", "mrs", "discussion", "discussions", "note", "notes", "event", "events"])]
+pub entity: String,
+```
+
+**File:** `src/cli/args.rs`
+
+**Change 2 -- `SearchArgs.source_type` (line 369):**
+```rust
+// BEFORE:
+#[arg(long = "type", value_parser = ["issue", "mr", "discussion", "note"], ...)]
+pub source_type: Option<String>,
+
+// AFTER:
+#[arg(long = "type", value_parser = ["issue", "issues", "mr", "mrs", "discussion", "discussions", "note", "notes"], ...)]
+pub source_type: Option<String>,
+```
+
+**File:** `src/cli/mod.rs`
+
+**Change 3 -- `Drift.entity_type` (line 287):**
+```rust
+// BEFORE:
+#[arg(value_parser = ["issues"])]
+pub entity_type: String,
+
+// AFTER:
+#[arg(value_parser = ["issue", "issues"])]
+pub entity_type: String,
+```
+
+**Normalization layer:** In the handlers that consume these values, normalize to the canonical form (plural for entity names, singular for source_type) so downstream code doesn't need changes:
+
+**File:** `src/app/handlers.rs`
+
+In `handle_count` (~line 409): Normalize entity string before passing to `run_count`:
+```rust
+let entity = match args.entity.as_str() {
+    "issue" => "issues",
+    "mr" => "mrs",
+    "discussion" => "discussions",
+    "note" => "notes",
+    "event" => "events",
+    other => other,
+};
+```
+
+In `handle_search` (search handler): Normalize source_type:
+```rust
+let source_type = args.source_type.as_deref().map(|t| match t {
+    "issues" => "issue",
+    "mrs" => "mr",
+    "discussions" => "discussion",
+    "notes" => "note",
+    other => other,
+});
+```
+
+In `handle_drift` (~line 225): Normalize entity_type:
+```rust
+let entity_type = if entity_type == "issue" { "issues" } else { &entity_type };
+```
+
+**Verification:**
+- `lore count issue` works (same as `lore count issues`)
+- `lore search --type issues 'foo'` works (same as `--type issue`)
+- `lore drift issue 42` works (same as `drift issues 42`)
+- All existing invocations unchanged
+
+**Files touched:** `src/cli/args.rs`, `src/cli/mod.rs`, `src/app/handlers.rs`
+
+---
+
+### P5: Fix `-f` Short Flag Collision
+
+**Goal:** Remove `-f` shorthand from `count --for` so `-f` consistently means `--force` across the CLI.
+
+**File:** `src/cli/args.rs` (line 823)
+
+```rust
+// BEFORE:
+#[arg(short = 'f', long = "for", value_parser = ["issue", "mr"])]
+pub for_entity: Option<String>,
+
+// AFTER:
+#[arg(long = "for", value_parser = ["issue", "mr"])]
+pub for_entity: Option<String>,
+```
+
+**Also update the value_parser to accept both forms** (while we're here):
+```rust
+#[arg(long = "for", value_parser = ["issue", "issues", "mr", "mrs"])]
+pub for_entity: Option<String>,
+```
+
+And normalize in `handle_count`:
+```rust
+let for_entity = args.for_entity.as_deref().map(|f| match f {
+    "issues" => "issue",
+    "mrs" => "mr",
+    other => other,
+});
+```
+
+**File:** `src/app/robot_docs.rs` (line 173) -- update the robot-docs entry:
+```rust
+// BEFORE:
+"flags": ["<entity: issues|mrs|discussions|notes|events>", "-f/--for <issue|mr>"],
+
+// AFTER:
+"flags": ["<entity: issues|mrs|discussions|notes|events>", "--for <issue|mr>"],
+```
+
+**Verification:**
+- `lore count notes --for mr` still works
+- `lore count notes -f mr` now fails with a clear error (unknown flag `-f`)
+- `lore ingest -f` still works (means `--force`)
+
+**Files touched:** `src/cli/args.rs`, `src/app/robot_docs.rs`
+
+---
+
+### P9: Consistent `--open` Short Flag on `notes`
+
+**Goal:** Add `-o` shorthand to `notes --open`, matching `issues` and `mrs`.
+
+**File:** `src/cli/args.rs` (line 292)
+
+```rust
+// BEFORE:
+#[arg(long, help_heading = "Actions")]
+pub open: bool,
+
+// AFTER:
+#[arg(short = 'o', long, help_heading = "Actions", overrides_with = "no_open")]
+pub open: bool,
+
+#[arg(long = "no-open", hide = true, overrides_with = "open")]
+pub no_open: bool,
+```
+
+**Verification:**
+- `lore notes -o` opens first result in browser
+- Matches behavior of `lore issues -o` and `lore mrs -o`
+
+**Files touched:** `src/cli/args.rs`
+
+---
+
+### Phase 1 Commit Summary
+
+**Files modified:**
+1. `src/cli/mod.rs` -- help_heading on all Commands variants + drift value_parser
+2. `src/cli/args.rs` -- singular/plural value_parsers, remove `-f` from count, add `-o` to notes
+3. `src/app/handlers.rs` -- normalization of entity/source_type strings
+4. `src/app/robot_docs.rs` -- update count flags documentation
+
+**Test plan:**
+```bash
+cargo check --all-targets
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+cargo test
+lore --help                    # Verify grouped output
+lore count issue               # Verify singular accepted
+lore search --type issues 'x'  # Verify plural accepted
+lore drift issue 42            # Verify singular accepted
+lore notes -o                  # Verify short flag works
+```
+
+---
+
+## Phase 2: Renames and Merges (2-3 commits)
+
+These changes rename commands and merge overlapping ones. Hidden aliases preserve backward compatibility.
+
+### P2: Rename `stats` -> `index`
+
+**Goal:** Eliminate `status`/`stats`/`stat` confusion. `stats` becomes `index`.
+
+**File:** `src/cli/mod.rs`
+
+```rust
+// BEFORE:
+/// Show document and index statistics
+#[command(visible_alias = "stat", help_heading = "System")]
+Stats(StatsArgs),
+
+// AFTER:
+/// Show document and index statistics
+#[command(visible_alias = "idx", alias = "stats", alias = "stat", help_heading = "System")]
+Index(StatsArgs),
+```
+
+Note: `alias = "stats"` and `alias = "stat"` are hidden aliases (not `visible_alias`) -- old invocations still work, but `--help` shows `index`.
+
+**File:** `src/main.rs` (line 257)
+
+```rust
+// BEFORE:
+Some(Commands::Stats(args)) => handle_stats(cli.config.as_deref(), args, robot_mode).await,
+
+// AFTER:
+Some(Commands::Index(args)) => handle_stats(cli.config.as_deref(), args, robot_mode).await,
+```
+
+**File:** `src/app/robot_docs.rs` (line 181)
+
+```rust
+// BEFORE:
+"stats": {
+    "description": "Show document and index statistics",
+    ...
+
+// AFTER:
+"index": {
+    "description": "Show document and index statistics (formerly 'stats')",
+    ...
+```
+
+Also update references in:
+- `robot_docs.rs` quick_start.lore_exclusive array (line 415): `"stats: Database statistics..."` -> `"index: Database statistics..."`
+- `robot_docs.rs` aliases.deprecated_commands: add `"stats": "index"`, `"stat": "index"`
+
+**File:** `src/cli/autocorrect.rs`
+
+Update `CANONICAL_SUBCOMMANDS` (line 366-area):
+```rust
+// Replace "stats" with "index" in the canonical list
+// Add ("stats", "index") and ("stat", "index") to SUBCOMMAND_ALIASES
+```
+
+Update `COMMAND_FLAGS` (line 166-area):
+```rust
+// BEFORE:
+("stats", &["--check", ...]),
+
+// AFTER:
+("index", &["--check", ...]),
+```
+
+**File:** `src/cli/robot.rs` -- update `expand_fields_preset` if any preset key is `"stats"` (currently no stats preset, so no change needed).
+
+**Verification:**
+- `lore index` works (shows document/index stats)
+- `lore stats` still works (hidden alias)
+- `lore stat` still works (hidden alias)
+- `lore index --check` works
+- `lore --help` shows `index` in System group, not `stats`
+- `lore robot-docs` shows `index` key in commands map
+
+**Files touched:** `src/cli/mod.rs`, `src/main.rs`, `src/app/robot_docs.rs`, `src/cli/autocorrect.rs`
+
+---
+
+### P4: Merge `health` into `doctor`
+
+**Goal:** One diagnostic command (`doctor`) with a `--quick` flag for the pre-flight check that `health` currently provides.
+
+**File:** `src/cli/mod.rs`
+
+```rust
+// BEFORE:
+/// Quick health check: config, database, schema version
+#[command(after_help = "...")]
+Health,
+
+/// Check environment health
+#[command(after_help = "...")]
+Doctor,
+
+// AFTER:
+// Remove Health variant entirely. Add hidden alias:
+/// Check environment health (--quick for fast pre-flight)
+#[command(
+    after_help = "...",
+    alias = "health",  // hidden backward compat
+    help_heading = "System"
+)]
+Doctor {
+    /// Fast pre-flight check only (config, DB, schema). Exit 0 = healthy.
+    #[arg(long)]
+    quick: bool,
+},
+```
+
+**File:** `src/main.rs`
+
+```rust
+// BEFORE:
+Some(Commands::Doctor) => handle_doctor(cli.config.as_deref(), robot_mode).await,
+...
+Some(Commands::Health) => handle_health(cli.config.as_deref(), robot_mode).await,
+
+// AFTER:
+Some(Commands::Doctor { quick }) => {
+    if quick {
+        handle_health(cli.config.as_deref(), robot_mode).await
+    } else {
+        handle_doctor(cli.config.as_deref(), robot_mode).await
+    }
+}
+// Health variant removed from enum, so no separate match arm
+```
+
+**File:** `src/app/robot_docs.rs`
+
+Merge the `health` and `doctor` entries:
+```rust
+"doctor": {
+    "description": "Environment health check. Use --quick for fast pre-flight (exit 0 = healthy, 19 = unhealthy).",
+    "flags": ["--quick"],
+    "example": "lore --robot doctor",
+    "notes": {
+        "quick_mode": "lore --robot doctor --quick — fast pre-flight check (formerly 'lore health'). Only checks config, DB, schema version. Returns exit 19 on failure.",
+        "full_mode": "lore --robot doctor — full diagnostic: config, auth, database, Ollama"
+    },
+    "response_schema": {
+        "full": { ... },  // current doctor schema
+        "quick": { ... }  // current health schema
+    }
+}
+```
+
+Remove the standalone `health` entry from the commands map.
+
+**File:** `src/cli/autocorrect.rs`
+
+- Remove `"health"` from `CANONICAL_SUBCOMMANDS` (clap's `alias` handles it)
+- Or keep it -- since clap treats aliases as valid subcommands, the autocorrect system will still resolve typos like `"helth"` to `"health"` which clap then maps to `doctor`. Either way works.
+
+**File:** `src/app/robot_docs.rs` -- update `workflows.pre_flight`:
+```rust
+"pre_flight": [
+    "lore --robot doctor --quick"
+],
+```
+
+Add to aliases.deprecated_commands:
+```rust
+"health": "doctor --quick"
+```
+
+**Verification:**
+- `lore doctor` runs full diagnostic (unchanged behavior)
+- `lore doctor --quick` runs fast pre-flight (exit 0/19)
+- `lore health` still works (hidden alias, runs `doctor --quick`)
+- `lore --help` shows only `doctor` in System group
+- `lore robot-docs` shows merged entry
+
+**Files touched:** `src/cli/mod.rs`, `src/main.rs`, `src/app/robot_docs.rs`, `src/cli/autocorrect.rs`
+
+**Important edge case:** `lore health` via the hidden alias will invoke `Doctor { quick: false }` unless we handle it specially. Two options:
+
+**Option A (simpler):** Instead of making `health` an alias of `doctor`, keep both variants but hide `Health`:
+```rust
+#[command(hide = true, help_heading = "System")]
+Health,
+```
+Then in `main.rs`, `Commands::Health` maps to `handle_health()` as before. This is less clean but zero-risk.
+
+**Option B (cleaner):** In the autocorrect layer, rewrite `health` -> `doctor --quick` before clap parsing:
+```rust
+// In SUBCOMMAND_ALIASES or a new pre-clap rewrite:
+("health", "doctor"),  // plus inject "--quick" flag
+```
+This requires a small enhancement to autocorrect to support flag injection during alias resolution.
+
+**Recommendation:** Use Option A for initial implementation. It's one line (`hide = true`) and achieves the goal of removing `health` from `--help` while preserving full backward compatibility. The `doctor --quick` flag is additive.
+
+---
+
+### P7: Hide Pipeline Sub-stages
+
+**Goal:** Remove `ingest`, `generate-docs`, `embed` from `--help` while keeping them fully functional.
+
+**File:** `src/cli/mod.rs`
+
+```rust
+// Add hide = true to each:
+
+/// Ingest data from GitLab
+#[command(hide = true)]
+Ingest(IngestArgs),
+
+/// Generate searchable documents from ingested data
+#[command(name = "generate-docs", hide = true)]
+GenerateDocs(GenerateDocsArgs),
+
+/// Generate vector embeddings for documents via Ollama
+#[command(hide = true)]
+Embed(EmbedArgs),
+```
+
+**File:** `src/cli/mod.rs` -- Update `Sync` help text to mention the individual stage commands:
+
+```rust
+/// Run full sync pipeline: ingest -> generate-docs -> embed
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore sync                             # Full pipeline: ingest + docs + embed
+  lore sync --no-embed                  # Skip embedding step
+  ...
+
+\x1b[1mIndividual stages:\x1b[0m
+  lore ingest                           # Fetch from GitLab only
+  lore generate-docs                    # Rebuild documents only
+  lore embed                            # Re-embed only",
+    help_heading = "Data Pipeline"
+)]
+Sync(SyncArgs),
+```
+
+**File:** `src/app/robot_docs.rs` -- Add a `"hidden": true` field to the ingest/generate-docs/embed entries so agents know these are secondary:
+```rust
+"ingest": {
+    "hidden": true,
+    "description": "Sync data from GitLab (prefer 'sync' for full pipeline)",
+    ...
+```
+
+**Verification:**
+- `lore --help` no longer shows ingest, generate-docs, embed
+- `lore ingest`, `lore generate-docs`, `lore embed` all still work
+- `lore sync --help` mentions individual stage commands
+- `lore robot-docs` still includes all three (with `hidden: true`)
+
+**Files touched:** `src/cli/mod.rs`, `src/app/robot_docs.rs`
+
+---
+
+### Phase 2 Commit Summary
+
+**Commit A: Rename `stats` -> `index`**
+- `src/cli/mod.rs`, `src/main.rs`, `src/app/robot_docs.rs`, `src/cli/autocorrect.rs`
+
+**Commit B: Merge `health` into `doctor`, hide pipeline stages**
+- `src/cli/mod.rs`, `src/main.rs`, `src/app/robot_docs.rs`, `src/cli/autocorrect.rs`
+
+**Test plan:**
+```bash
+cargo check --all-targets
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+cargo test
+
+# Rename verification
+lore index                     # Works (new name)
+lore stats                     # Works (hidden alias)
+lore index --check             # Works
+
+# Doctor merge verification
+lore doctor                    # Full diagnostic
+lore doctor --quick            # Fast pre-flight
+lore health                    # Still works (hidden)
+
+# Hidden stages verification
+lore --help                    # ingest/generate-docs/embed gone
+lore ingest                    # Still works
+lore sync --help               # Mentions individual stages
+```
+
+---
+
+## Phase 3: Structural Consolidation (requires careful design)
+
+These changes merge or absorb commands. More effort, more testing, but the biggest UX wins.
+
+### P6: Consolidate `file-history` into `trace`
+
+**Goal:** `trace` absorbs `file-history`. One command for file-centric intelligence.
+
+**Approach:** Add `--mrs-only` flag to `trace`. When set, output matches `file-history` format (flat MR list, no issue/discussion linking). `file-history` becomes a hidden alias.
+
+**File:** `src/cli/args.rs` -- Add flag to `TraceArgs`:
+
+```rust
+pub struct TraceArgs {
+    pub path: String,
+
+    #[arg(short = 'p', long, help_heading = "Filters")]
+    pub project: Option<String>,
+
+    #[arg(long, help_heading = "Output")]
+    pub discussions: bool,
+
+    #[arg(long = "no-follow-renames", help_heading = "Filters")]
+    pub no_follow_renames: bool,
+
+    #[arg(short = 'n', long = "limit", default_value = "20", help_heading = "Output")]
+    pub limit: usize,
+
+    // NEW: absorb file-history behavior
+    /// Show only MR list without issue/discussion linking (file-history mode)
+    #[arg(long = "mrs-only", help_heading = "Output")]
+    pub mrs_only: bool,
+
+    /// Only show merged MRs (file-history mode)
+    #[arg(long, help_heading = "Filters")]
+    pub merged: bool,
+}
+```
+
+**File:** `src/cli/mod.rs` -- Hide `FileHistory`:
+
+```rust
+/// Show MRs that touched a file, with linked discussions
+#[command(name = "file-history", hide = true, help_heading = "File Analysis")]
+FileHistory(FileHistoryArgs),
+```
+
+**File:** `src/app/handlers.rs` -- Route `trace --mrs-only` to the file-history handler:
+
+```rust
+fn handle_trace(
+    config_override: Option<&str>,
+    args: TraceArgs,
+    robot_mode: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    if args.mrs_only {
+        // Delegate to file-history handler
+        let fh_args = FileHistoryArgs {
+            path: args.path,
+            project: args.project,
+            discussions: args.discussions,
+            no_follow_renames: args.no_follow_renames,
+            merged: args.merged,
+            limit: args.limit,
+        };
+        return handle_file_history(config_override, fh_args, robot_mode);
+    }
+    // ... existing trace logic ...
+}
+```
+
+**File:** `src/app/robot_docs.rs` -- Update trace entry, mark file-history as deprecated:
+
+```rust
+"trace": {
+    "description": "Trace why code was introduced: file -> MR -> issue -> discussion. Use --mrs-only for flat MR listing.",
+    "flags": ["<path>", "-p/--project", "--discussions", "--no-follow-renames", "-n/--limit", "--mrs-only", "--merged"],
+    ...
+},
+"file-history": {
+    "hidden": true,
+    "deprecated": "Use 'trace --mrs-only' instead",
+    ...
+}
+```
+
+**Verification:**
+- `lore trace src/main.rs` works unchanged
+- `lore trace src/main.rs --mrs-only` produces file-history output
+- `lore trace src/main.rs --mrs-only --merged` filters to merged MRs
+- `lore file-history src/main.rs` still works (hidden command)
+- `lore --help` shows only `trace` in File Analysis group
+
+**Files touched:** `src/cli/args.rs`, `src/cli/mod.rs`, `src/app/handlers.rs`, `src/app/robot_docs.rs`
+
+---
+
+### P8: Make `count` a Flag on Entity Commands
+
+**Goal:** `lore issues --count` replaces `lore count issues`. Standalone `count` becomes hidden.
+
+**File:** `src/cli/args.rs` -- Add `--count` to `IssuesArgs`, `MrsArgs`, `NotesArgs`:
+
+```rust
+// In IssuesArgs:
+/// Show count only (no listing)
+#[arg(long, help_heading = "Output", conflicts_with_all = ["iid", "open"])]
+pub count: bool,
+
+// In MrsArgs:
+/// Show count only (no listing)
+#[arg(long, help_heading = "Output", conflicts_with_all = ["iid", "open"])]
+pub count: bool,
+
+// In NotesArgs:
+/// Show count only (no listing)
+#[arg(long, help_heading = "Output", conflicts_with = "open")]
+pub count: bool,
+```
+
+**File:** `src/app/handlers.rs` -- In `handle_issues`, `handle_mrs`, `handle_notes`, check the count flag early:
+
+```rust
+// In handle_issues (pseudocode):
+if args.count {
+    let count_args = CountArgs { entity: "issues".to_string(), for_entity: None };
+    return handle_count(config_override, count_args, robot_mode).await;
+}
+```
+
+**File:** `src/cli/mod.rs` -- Hide `Count`:
+
+```rust
+/// Count entities in local database
+#[command(hide = true, help_heading = "Query")]
+Count(CountArgs),
+```
+
+**File:** `src/app/robot_docs.rs` -- Mark count as hidden, add `--count` documentation to issues/mrs/notes entries.
+
+**Verification:**
+- `lore issues --count` returns issue count
+- `lore mrs --count` returns MR count
+- `lore notes --count` returns note count
+- `lore count issues` still works (hidden)
+- `lore count discussions --for mr` still works (no equivalent in the new pattern -- discussions/events/references still need the standalone `count` command)
+
+**Important note:** `count` supports entity types that don't have their own command (discussions, events, references). The standalone `count` must remain functional (just hidden). The `--count` flag on `issues`/`mrs`/`notes` handles the common cases only.
+
+**Files touched:** `src/cli/args.rs`, `src/cli/mod.rs`, `src/app/handlers.rs`, `src/app/robot_docs.rs`
+
+---
+
+### P10: Add `--sort` to `search`
+
+**Goal:** Allow sorting search results by score, created date, or updated date.
+
+**File:** `src/cli/args.rs` -- Add to `SearchArgs`:
+
+```rust
+/// Sort results by field (score is default for ranked search)
+#[arg(long, value_parser = ["score", "created", "updated"], default_value = "score", help_heading = "Sorting")]
+pub sort: String,
+
+/// Sort ascending (default: descending)
+#[arg(long, help_heading = "Sorting", overrides_with = "no_asc")]
+pub asc: bool,
+
+#[arg(long = "no-asc", hide = true, overrides_with = "asc")]
+pub no_asc: bool,
+```
+
+**File:** `src/cli/commands/search.rs` -- Thread the sort parameter through to the search query.
+
+The search function currently returns results sorted by score. When `--sort created` or `--sort updated` is specified, apply an `ORDER BY` clause to the final result set.
+
+**File:** `src/app/robot_docs.rs` -- Add `--sort` and `--asc` to the search command's flags list.
+
+**Verification:**
+- `lore search 'auth' --sort score` (default, unchanged)
+- `lore search 'auth' --sort created --asc` (oldest first)
+- `lore search 'auth' --sort updated` (most recently updated first)
+
+**Files touched:** `src/cli/args.rs`, `src/cli/commands/search.rs`, `src/app/robot_docs.rs`
+
+---
+
+### Phase 3 Commit Summary
+
+**Commit C: Consolidate file-history into trace**
+- `src/cli/args.rs`, `src/cli/mod.rs`, `src/app/handlers.rs`, `src/app/robot_docs.rs`
+
+**Commit D: Add `--count` flag to entity commands**
+- `src/cli/args.rs`, `src/cli/mod.rs`, `src/app/handlers.rs`, `src/app/robot_docs.rs`
+
+**Commit E: Add `--sort` to search**
+- `src/cli/args.rs`, `src/cli/commands/search.rs`, `src/app/robot_docs.rs`
+
+**Test plan:**
+```bash
+cargo check --all-targets
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+cargo test
+
+# trace consolidation
+lore trace src/main.rs --mrs-only
+lore trace src/main.rs --mrs-only --merged --discussions
+lore file-history src/main.rs     # backward compat
+
+# count flag
+lore issues --count
+lore mrs --count -s opened
+lore notes --count --for-issue 42
+lore count discussions --for mr   # still works
+
+# search sort
+lore search 'auth' --sort created --asc
+```
+
+---
+
+## Documentation Updates
+
+After all implementation is complete:
+
+### CLAUDE.md / AGENTS.md
+
+Update the robot mode command reference to reflect:
+- `stats` -> `index` (with note that `stats` is a hidden alias)
+- `health` -> `doctor --quick` (with note that `health` is a hidden alias)
+- Remove `ingest`, `generate-docs`, `embed` from the primary command table (mention as "hidden, use `sync`")
+- Remove `file-history` from primary table (mention as "hidden, use `trace --mrs-only`")
+- Add `--count` flag to issues/mrs/notes documentation
+- Add `--sort` flag to search documentation
+- Add `--mrs-only` and `--merged` flags to trace documentation
+
+### robot-docs Self-Discovery
+
+The `robot_docs.rs` changes above handle this. Key points:
+- New `"hidden": true` field on deprecated/hidden commands
+- Updated descriptions mentioning canonical alternatives
+- Updated flags lists
+- Updated workflows section
+
+---
+
+## File Impact Summary
+
+| File | Phase 1 | Phase 2 | Phase 3 | Total Changes |
+|------|---------|---------|---------|---------------|
+| `src/cli/mod.rs` | help_heading, drift value_parser | stats->index rename, hide health, hide pipeline stages | hide file-history, hide count | 4 passes |
+| `src/cli/args.rs` | singular/plural, remove `-f`, add `-o` | — | `--mrs-only`/`--merged` on trace, `--count` on entities, `--sort` on search | 2 passes |
+| `src/app/handlers.rs` | normalize entity strings | route doctor --quick | trace mrs-only delegation, count flag routing | 3 passes |
+| `src/app/robot_docs.rs` | update count flags | rename stats->index, merge health+doctor, add hidden field | update trace, file-history, count, search entries | 3 passes |
+| `src/cli/autocorrect.rs` | — | update CANONICAL_SUBCOMMANDS, SUBCOMMAND_ALIASES, COMMAND_FLAGS | — | 1 pass |
+| `src/main.rs` | — | stats->index variant rename, doctor variant change | — | 1 pass |
+| `src/cli/commands/search.rs` | — | — | sort parameter threading | 1 pass |
+
+---
+
+## Before / After Summary
+
+### Command Count
+
+| Metric | Before | After | Delta |
+|--------|--------|-------|-------|
+| Visible top-level commands | 29 | 21 | -8 (-28%) |
+| Hidden commands (functional) | 4 | 12 | +8 (absorbed) |
+| Stub/unimplemented commands | 2 | 2 | 0 |
+| Total functional commands | 33 | 33 | 0 (nothing lost) |
+
+### `lore --help` Output
+
+**Before (29 commands, flat list, ~50 lines of commands):**
+```
+Commands:
+  issues         List or show issues [aliases: issue]
+  mrs            List or show merge requests [aliases: mr]
+  notes          List notes from discussions [aliases: note]
+  ingest         Ingest data from GitLab
+  count          Count entities in local database
+  status         Show sync state [aliases: st]
+  auth           Verify GitLab authentication
+  doctor         Check environment health
+  version        Show version information
+  init           Initialize configuration and database
+  search         Search indexed documents [aliases: find]
+  stats          Show document and index statistics [aliases: stat]
+  generate-docs  Generate searchable documents from ingested data
+  embed          Generate vector embeddings for documents via Ollama
+  sync           Run full sync pipeline: ingest -> generate-docs -> embed
+  migrate        Run pending database migrations
+  health         Quick health check: config, database, schema version
+  robot-docs     Machine-readable command manifest for agent self-discovery
+  completions    Generate shell completions
+  timeline       Show a chronological timeline of events matching a query
+  who            People intelligence: experts, workload, active discussions, overlap
+  me             Personal work dashboard: open issues, authored/reviewing MRs, activity
+  file-history   Show MRs that touched a file, with linked discussions
+  trace          Trace why code was introduced: file -> MR -> issue -> discussion
+  drift          Detect discussion divergence from original intent
+  related        Find semantically related entities via vector search
+  cron           Manage cron-based automatic syncing
+  token          Manage stored GitLab token
+  help           Print this message or the help of the given subcommand(s)
+```
+
+**After (21 commands, grouped, ~35 lines of commands):**
+```
+Query:
+  issues      List or show issues [aliases: issue]
+  mrs         List or show merge requests [aliases: mr]
+  notes       List notes from discussions [aliases: note]
+  search      Search indexed documents [aliases: find]
+
+Intelligence:
+  timeline    Chronological timeline of events
+  who         People intelligence: experts, workload, overlap
+  me          Personal work dashboard
+
+File Analysis:
+  trace       Trace code provenance / file history
+  related     Find semantically related entities
+  drift       Detect discussion divergence
+
+Data Pipeline:
+  sync        Run full sync pipeline
+
+System:
+  init        Initialize configuration and database
+  status      Show sync state [aliases: st]
+  doctor      Check environment health (--quick for pre-flight)
+  index       Document and index statistics [aliases: idx]
+  auth        Verify GitLab authentication
+  token       Manage stored GitLab token
+  migrate     Run pending database migrations
+  cron        Manage automatic syncing
+  robot-docs  Agent self-discovery manifest
+  completions Generate shell completions
+  version     Show version information
+```
+
+### Flag Consistency
+
+| Issue | Before | After |
+|-------|--------|-------|
+| `-f` collision (force vs for) | `ingest -f`=force, `count -f`=for | `-f` removed from count; `-f` = force everywhere |
+| Singular/plural entity types | `count issues` but `search --type issue` | Both forms accepted everywhere |
+| `notes --open` missing `-o` | `notes --open` (no shorthand) | `notes -o` works (matches issues/mrs) |
+| `search` missing `--sort` | No sort override | `--sort score\|created\|updated` + `--asc` |
+
+### Naming Confusion
+
+| Before | After | Resolution |
+|--------|-------|------------|
+| `status` vs `stats` vs `stat` (3 names, 2 commands) | `status` + `index` (2 names, 2 commands) | Eliminated near-homonym collision |
+| `health` vs `doctor` (2 commands, overlapping scope) | `doctor` + `doctor --quick` (1 command) | Progressive disclosure |
+| `trace` vs `file-history` (2 commands, overlapping function) | `trace` + `trace --mrs-only` (1 command) | Superset absorbs subset |
+
+### Robot Ergonomics
+
+| Metric | Before | After |
+|--------|--------|-------|
+| Commands in robot-docs manifest | 29 | 21 visible + hidden section |
+| Agent decision space for "system check" | 4 commands | 2 commands (status, doctor) |
+| Agent decision space for "file query" | 3 commands + 2 who modes | 1 command (trace) + 2 who modes |
+| Entity type parse errors from singular/plural | Common | Eliminated |
+| Estimated token cost of robot-docs | Baseline | ~15% reduction (fewer entries, hidden flagged) |
+
+### What Stays Exactly The Same
+
+- All 33 functional commands remain callable (nothing is removed)
+- All existing flags and their behavior are preserved
+- All response schemas are unchanged
+- All exit codes are unchanged
+- The autocorrect system continues to work
+- All hidden/deprecated commands emit their existing warnings
+
+### What Breaks (Intentional)
+
+- `lore count -f mr` (the `-f` shorthand) -- must use `--for` instead
+- `lore --help` layout changes (commands are grouped, 8 commands hidden)
+- `lore robot-docs` output changes (new `hidden` field, renamed keys)
+- Any scripts parsing `--help` text (but `robot-docs` is the stable contract)

docs/command-surface-analysis/00-overview.md

@@ -0,0 +1,92 @@
+# Lore Command Surface Analysis — Overview
+
+**Date:** 2026-02-26
+**Version:** v0.9.1 (439c20e)
+
+---
+
+## Purpose
+
+Deep analysis of the full `lore` CLI command surface: what each command does, how commands overlap, how they connect in agent workflows, and where consolidation and robot-mode optimization can reduce round trips and token waste.
+
+## Document Map
+
+| File | Contents | When to Read |
+|---|---|---|
+| **00-overview.md** | This file. Summary, inventory, priorities. | Always read first. |
+| [01-entity-commands.md](01-entity-commands.md) | `issues`, `mrs`, `notes`, `search`, `count` — flags, DB tables, robot schemas | Need command reference for entity queries |
+| [02-intelligence-commands.md](02-intelligence-commands.md) | `who`, `timeline`, `me`, `file-history`, `trace`, `related`, `drift` | Need command reference for intelligence/analysis |
+| [03-pipeline-and-infra.md](03-pipeline-and-infra.md) | `sync`, `ingest`, `generate-docs`, `embed`, diagnostics, setup | Need command reference for data management |
+| [04-data-flow.md](04-data-flow.md) | Shared data source map, command network graph, clusters | Understanding how commands interconnect |
+| [05-overlap-analysis.md](05-overlap-analysis.md) | Quantified overlap percentages for every command pair | Evaluating what to consolidate |
+| [06-agent-workflows.md](06-agent-workflows.md) | Common agent flows, round-trip costs, token profiles | Understanding inefficiency pain points |
+| [07-consolidation-proposals.md](07-consolidation-proposals.md) | 5 proposals to reduce 34 commands to 29 | Planning command surface changes |
+| [08-robot-optimization-proposals.md](08-robot-optimization-proposals.md) | 6 proposals for `--include`, `--batch`, `--depth`, etc. | Planning robot-mode improvements |
+| [09-appendices.md](09-appendices.md) | Robot output envelope, field presets, exit codes | Reference material |
+
+---
+
+## Command Inventory (34 commands)
+
+| Category | Commands | Count |
+|---|---|---|
+| Entity Query | `issues`, `mrs`, `notes`, `search`, `count` | 5 |
+| Intelligence | `who` (5 modes), `timeline`, `related`, `drift`, `me`, `file-history`, `trace` | 7 (11 with who sub-modes) |
+| Data Pipeline | `sync`, `ingest`, `generate-docs`, `embed` | 4 |
+| Diagnostics | `health`, `auth`, `doctor`, `status`, `stats` | 5 |
+| Setup | `init`, `token`, `cron`, `migrate` | 4 |
+| Meta | `version`, `completions`, `robot-docs` | 3 |
+
+---
+
+## Key Findings
+
+### High-Overlap Pairs
+
+| Pair | Overlap | Recommendation |
+|---|---|---|
+| `who workload` vs `me` | ~85% | Workload is a strict subset of me |
+| `health` vs `doctor` | ~90% | Health is a strict subset of doctor |
+| `file-history` vs `trace` | ~75% | Trace is a superset minus `--merged` |
+| `related` query-mode vs `search --mode semantic` | ~80% | Related query-mode is search without filters |
+| `auth` vs `doctor` | ~100% of auth | Auth is fully contained within doctor |
+
+### Agent Workflow Pain Points
+
+| Workflow | Current Round Trips | With Optimizations |
+|---|---|---|
+| "Understand this issue" | 4 calls | 1 call (`--include`) |
+| "Why was code changed?" | 3 calls | 1 call (`--include`) |
+| "What should I work on?" | 4 calls | 2 calls |
+| "Find and understand" | 4 calls | 2 calls |
+| "Is system healthy?" | 2-4 calls | 1 call |
+
+---
+
+## Priority Ranking
+
+| Pri | Proposal | Category | Effort | Impact |
+|---|---|---|---|---|
+| **P0** | `--include` flag on detail commands | Robot optimization | High | Eliminates 2-3 round trips per workflow |
+| **P0** | `--depth` on `me` command | Robot optimization | Low | 60-80% token reduction on most-used command |
+| **P1** | `--batch` for detail views | Robot optimization | Medium | Eliminates N+1 after search/timeline |
+| **P1** | Absorb `file-history` into `trace` | Consolidation | Low | Cleaner surface, shared code |
+| **P1** | Merge `who overlap` into `who expert` | Consolidation | Low | -1 round trip in review flows |
+| **P2** | `context` composite command | Robot optimization | Medium | Single entry point for entity understanding |
+| **P2** | Merge `count`+`status` into `stats` | Consolidation | Medium | -2 commands, progressive disclosure |
+| **P2** | Absorb `auth` into `doctor` | Consolidation | Low | -1 command |
+| **P2** | Remove `related` query-mode | Consolidation | Low | -1 confusing choice |
+| **P3** | `--max-tokens` budget | Robot optimization | High | Flexible but complex to implement |
+| **P3** | `--format tsv` | Robot optimization | Medium | High savings, limited applicability |
+
+### Consolidation Summary
+
+| Before | After | Removed |
+|---|---|---|
+| `file-history` + `trace` | `trace` (+ `--shallow`) | -1 |
+| `auth` + `doctor` | `doctor` (+ `--auth`) | -1 |
+| `related` query-mode | `search --mode semantic` | -1 mode |
+| `who overlap` + `who expert` | `who expert` (+ touch_count) | -1 sub-mode |
+| `count` + `status` + `stats` | `stats` (+ `--entities`, `--sync`) | -2 |
+
+**Total: 34 commands -> 29 commands**

docs/command-surface-analysis/01-entity-commands.md

@@ -0,0 +1,308 @@
+# Entity Query Commands
+
+Reference for: `issues`, `mrs`, `notes`, `search`, `count`
+
+---
+
+## `issues` (alias: `issue`)
+
+List or show issues from local database.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `[IID]` | positional | — | Omit to list, provide to show detail |
+| `-n, --limit` | int | 50 | Max results |
+| `--fields` | string | — | Select output columns (preset: `minimal`) |
+| `-s, --state` | enum | — | `opened\|closed\|all` |
+| `-p, --project` | string | — | Filter by project (fuzzy) |
+| `-a, --author` | string | — | Filter by author username |
+| `-A, --assignee` | string | — | Filter by assignee username |
+| `-l, --label` | string[] | — | Filter by labels (AND logic, repeatable) |
+| `-m, --milestone` | string | — | Filter by milestone title |
+| `--status` | string[] | — | Filter by work-item status (COLLATE NOCASE, OR logic) |
+| `--since` | duration/date | — | Filter by created date (`7d`, `2w`, `YYYY-MM-DD`) |
+| `--due-before` | date | — | Filter by due date |
+| `--has-due` | flag | — | Show only issues with due dates |
+| `--sort` | enum | `updated` | `updated\|created\|iid` |
+| `--asc` | flag | — | Sort ascending |
+| `-o, --open` | flag | — | Open first match in browser |
+
+**DB tables:** `issues`, `projects`, `issue_assignees`, `issue_labels`, `labels`
+**Detail mode adds:** `discussions`, `notes`, `entity_references` (closing MRs)
+
+### Robot Output (list mode)
+
+```json
+{
+  "ok": true,
+  "data": {
+    "issues": [
+      {
+        "iid": 42, "title": "Fix auth", "state": "opened",
+        "author_username": "jdoe", "labels": ["backend"],
+        "assignees": ["jdoe"], "discussion_count": 3,
+        "unresolved_count": 1, "created_at_iso": "...",
+        "updated_at_iso": "...", "web_url": "...",
+        "project_path": "group/repo",
+        "status_name": "In progress"
+      }
+    ],
+    "total_count": 150, "showing": 50
+  },
+  "meta": { "elapsed_ms": 40, "available_statuses": ["Open", "In progress", "Closed"] }
+}
+```
+
+### Robot Output (detail mode — `issues <IID>`)
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 12345, "iid": 42, "title": "Fix auth",
+    "description": "Full markdown body...",
+    "state": "opened", "author_username": "jdoe",
+    "created_at": "...", "updated_at": "...", "closed_at": null,
+    "confidential": false, "web_url": "...", "project_path": "group/repo",
+    "references_full": "group/repo#42",
+    "labels": ["backend"], "assignees": ["jdoe"],
+    "due_date": null, "milestone": null,
+    "user_notes_count": 5, "merge_requests_count": 1,
+    "closing_merge_requests": [
+      { "iid": 99, "title": "Refactor auth", "state": "merged", "web_url": "..." }
+    ],
+    "discussions": [
+      {
+        "notes": [
+          { "author_username": "jdoe", "body": "...", "created_at": "...", "is_system": false }
+        ],
+        "individual_note": false
+      }
+    ],
+    "status_name": "In progress", "status_color": "#1068bf"
+  }
+}
+```
+
+**Minimal preset:** `iid`, `title`, `state`, `updated_at_iso`
+
+---
+
+## `mrs` (aliases: `mr`, `merge-request`, `merge-requests`)
+
+List or show merge requests.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `[IID]` | positional | — | Omit to list, provide to show detail |
+| `-n, --limit` | int | 50 | Max results |
+| `--fields` | string | — | Select output columns (preset: `minimal`) |
+| `-s, --state` | enum | — | `opened\|merged\|closed\|locked\|all` |
+| `-p, --project` | string | — | Filter by project |
+| `-a, --author` | string | — | Filter by author |
+| `-A, --assignee` | string | — | Filter by assignee |
+| `-r, --reviewer` | string | — | Filter by reviewer |
+| `-l, --label` | string[] | — | Filter by labels (AND) |
+| `--since` | duration/date | — | Filter by created date |
+| `-d, --draft` | flag | — | Draft MRs only |
+| `-D, --no-draft` | flag | — | Exclude drafts |
+| `--target` | string | — | Filter by target branch |
+| `--source` | string | — | Filter by source branch |
+| `--sort` | enum | `updated` | `updated\|created\|iid` |
+| `--asc` | flag | — | Sort ascending |
+| `-o, --open` | flag | — | Open in browser |
+
+**DB tables:** `merge_requests`, `projects`, `mr_reviewers`, `mr_labels`, `labels`, `mr_assignees`
+**Detail mode adds:** `discussions`, `notes`, `mr_diffs`
+
+### Robot Output (list mode)
+
+```json
+{
+  "ok": true,
+  "data": {
+    "mrs": [
+      {
+        "iid": 99, "title": "Refactor auth", "state": "merged",
+        "draft": false, "author_username": "jdoe",
+        "source_branch": "feat/auth", "target_branch": "main",
+        "labels": ["backend"], "assignees": ["jdoe"], "reviewers": ["reviewer"],
+        "discussion_count": 5, "unresolved_count": 0,
+        "created_at_iso": "...", "updated_at_iso": "...",
+        "web_url": "...", "project_path": "group/repo"
+      }
+    ],
+    "total_count": 500, "showing": 50
+  }
+}
+```
+
+### Robot Output (detail mode — `mrs <IID>`)
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 67890, "iid": 99, "title": "Refactor auth",
+    "description": "Full markdown body...",
+    "state": "merged", "draft": false, "author_username": "jdoe",
+    "source_branch": "feat/auth", "target_branch": "main",
+    "created_at": "...", "updated_at": "...",
+    "merged_at": "...", "closed_at": null,
+    "web_url": "...", "project_path": "group/repo",
+    "labels": ["backend"], "assignees": ["jdoe"], "reviewers": ["reviewer"],
+    "discussions": [
+      {
+        "notes": [
+          {
+            "author_username": "reviewer", "body": "...",
+            "created_at": "...", "is_system": false,
+            "position": { "new_path": "src/auth.rs", "new_line": 42 }
+          }
+        ],
+        "individual_note": false
+      }
+    ]
+  }
+}
+```
+
+**Minimal preset:** `iid`, `title`, `state`, `updated_at_iso`
+
+---
+
+## `notes` (alias: `note`)
+
+List discussion notes/comments with fine-grained filters.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `-n, --limit` | int | 50 | Max results |
+| `--fields` | string | — | Preset: `minimal` |
+| `-a, --author` | string | — | Filter by author |
+| `--note-type` | enum | — | `DiffNote\|DiscussionNote` |
+| `--contains` | string | — | Body text substring filter |
+| `--note-id` | int | — | Internal note ID |
+| `--gitlab-note-id` | int | — | GitLab note ID |
+| `--discussion-id` | string | — | Discussion ID filter |
+| `--include-system` | flag | — | Include system notes |
+| `--for-issue` | int | — | Notes on specific issue (requires `-p`) |
+| `--for-mr` | int | — | Notes on specific MR (requires `-p`) |
+| `-p, --project` | string | — | Scope to project |
+| `--since` | duration/date | — | Created after |
+| `--until` | date | — | Created before (inclusive) |
+| `--path` | string | — | File path filter (exact or prefix with `/`) |
+| `--resolution` | enum | — | `any\|unresolved\|resolved` |
+| `--sort` | enum | `created` | `created\|updated` |
+| `--asc` | flag | — | Sort ascending |
+| `--open` | flag | — | Open in browser |
+
+**DB tables:** `notes`, `discussions`, `projects`, `issues`, `merge_requests`
+
+### Robot Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "notes": [
+      {
+        "id": 1234, "gitlab_id": 56789,
+        "author_username": "reviewer", "body": "...",
+        "note_type": "DiffNote", "is_system": false,
+        "created_at_iso": "...", "updated_at_iso": "...",
+        "position_new_path": "src/auth.rs", "position_new_line": 42,
+        "resolvable": true, "resolved": false,
+        "noteable_type": "MergeRequest", "parent_iid": 99,
+        "parent_title": "Refactor auth", "project_path": "group/repo"
+      }
+    ],
+    "total_count": 1000, "showing": 50
+  }
+}
+```
+
+**Minimal preset:** `id`, `author_username`, `body`, `created_at_iso`
+
+---
+
+## `search` (aliases: `find`, `query`)
+
+Semantic + full-text search across indexed documents.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `<QUERY>` | positional | required | Search query string |
+| `--mode` | enum | `hybrid` | `lexical\|hybrid\|semantic` |
+| `--type` | enum | — | `issue\|mr\|discussion\|note` |
+| `--author` | string | — | Filter by author |
+| `-p, --project` | string | — | Scope to project |
+| `--label` | string[] | — | Filter by labels (AND) |
+| `--path` | string | — | File path filter |
+| `--since` | duration/date | — | Created after |
+| `--updated-since` | duration/date | — | Updated after |
+| `-n, --limit` | int | 20 | Max results (max: 100) |
+| `--fields` | string | — | Preset: `minimal` |
+| `--explain` | flag | — | Show ranking breakdown |
+| `--fts-mode` | enum | `safe` | `safe\|raw` |
+
+**DB tables:** `documents`, `documents_fts` (FTS5), `embeddings` (vec0), `document_labels`, `document_paths`, `projects`
+
+**Search modes:**
+- **lexical** — FTS5 with BM25 ranking (fastest, no Ollama needed)
+- **hybrid** — RRF combination of lexical + semantic (default)
+- **semantic** — Vector similarity only (requires Ollama)
+
+### Robot Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "query": "authentication bug",
+    "mode": "hybrid",
+    "total_results": 15,
+    "results": [
+      {
+        "document_id": 1234, "source_type": "issue",
+        "title": "Fix SSO auth", "url": "...",
+        "author": "jdoe", "project_path": "group/repo",
+        "labels": ["auth"], "paths": ["src/auth/"],
+        "snippet": "...matching text...",
+        "score": 0.85,
+        "explain": { "vector_rank": 2, "fts_rank": 1, "rrf_score": 0.85 }
+      }
+    ],
+    "warnings": []
+  }
+}
+```
+
+**Minimal preset:** `document_id`, `title`, `source_type`, `score`
+
+---
+
+## `count`
+
+Count entities in local database.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `<ENTITY>` | positional | required | `issues\|mrs\|discussions\|notes\|events\|references` |
+| `-f, --for` | enum | — | Parent type: `issue\|mr` |
+
+**DB tables:** Conditional aggregation on entity tables
+
+### Robot Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "entity": "merge_requests",
+    "count": 1234,
+    "system_excluded": 5000,
+    "breakdown": { "opened": 100, "closed": 50, "merged": 1084 }
+  }
+}
+```

docs/command-surface-analysis/02-intelligence-commands.md

@@ -0,0 +1,452 @@
+# Intelligence Commands
+
+Reference for: `who`, `timeline`, `me`, `file-history`, `trace`, `related`, `drift`
+
+---
+
+## `who` (People Intelligence)
+
+Five sub-modes, dispatched by argument shape.
+
+| Mode | Trigger | Purpose |
+|---|---|---|
+| **expert** | `who <path>` or `who --path <path>` | Who knows about a code area? |
+| **workload** | `who @username` | What is this person working on? |
+| **reviews** | `who @username --reviews` | Review pattern analysis |
+| **active** | `who --active` | Unresolved discussions needing attention |
+| **overlap** | `who --overlap <path>` | Who else touches these files? |
+
+### Shared Flags
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `-p, --project` | string | — | Scope to project |
+| `-n, --limit` | int | varies | Max results (1-500) |
+| `--fields` | string | — | Preset: `minimal` |
+| `--since` | duration/date | — | Time window |
+| `--include-bots` | flag | — | Include bot users |
+| `--include-closed` | flag | — | Include closed issues/MRs |
+| `--all-history` | flag | — | Query all history |
+
+### Expert-Only Flags
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `--detail` | flag | — | Per-MR breakdown |
+| `--as-of` | date/duration | — | Score at point in time |
+| `--explain-score` | flag | — | Score breakdown |
+
+### DB Tables by Mode
+
+| Mode | Primary Tables |
+|---|---|
+| expert | `notes` (INDEXED BY idx_notes_diffnote_path_created), `merge_requests`, `mr_reviewers` |
+| workload | `issues`, `merge_requests`, `mr_reviewers` |
+| reviews | `merge_requests`, `discussions`, `notes` |
+| active | `discussions`, `notes`, `issues`, `merge_requests` |
+| overlap | `notes`, `mr_file_changes`, `merge_requests` |
+
+### Robot Output (expert)
+
+```json
+{
+  "ok": true,
+  "data": {
+    "mode": "expert",
+    "input": { "target": "src/auth/", "path": "src/auth/" },
+    "resolved_input": { "mode": "expert", "project_id": 1, "project_path": "group/repo" },
+    "result": {
+      "experts": [
+        {
+          "username": "jdoe", "score": 42.5,
+          "detail": { "mr_ids_author": [99, 101], "mr_ids_reviewer": [88] }
+        }
+      ]
+    }
+  }
+}
+```
+
+### Robot Output (workload)
+
+```json
+{
+  "data": {
+    "mode": "workload",
+    "result": {
+      "assigned_issues": [{ "iid": 42, "title": "Fix auth", "state": "opened" }],
+      "authored_mrs": [{ "iid": 99, "title": "Refactor auth", "state": "merged" }],
+      "review_mrs": [{ "iid": 88, "title": "Add SSO", "state": "opened" }]
+    }
+  }
+}
+```
+
+### Robot Output (reviews)
+
+```json
+{
+  "data": {
+    "mode": "reviews",
+    "result": {
+      "categories": [
+        {
+          "category": "approval_rate",
+          "reviewers": [{ "name": "jdoe", "count": 15, "percentage": 85.0 }]
+        }
+      ]
+    }
+  }
+}
+```
+
+### Robot Output (active)
+
+```json
+{
+  "data": {
+    "mode": "active",
+    "result": {
+      "discussions": [
+        { "entity_type": "mr", "iid": 99, "title": "Refactor auth", "participants": ["jdoe", "reviewer"] }
+      ]
+    }
+  }
+}
+```
+
+### Robot Output (overlap)
+
+```json
+{
+  "data": {
+    "mode": "overlap",
+    "result": {
+      "users": [{ "username": "jdoe", "touch_count": 15 }]
+    }
+  }
+}
+```
+
+### Minimal Presets
+
+| Mode | Fields |
+|---|---|
+| expert | `username`, `score` |
+| workload | `iid`, `title`, `state` |
+| reviews | `name`, `count`, `percentage` |
+| active | `entity_type`, `iid`, `title`, `participants` |
+| overlap | `username`, `touch_count` |
+
+---
+
+## `timeline`
+
+Reconstruct chronological event history for a topic/entity with cross-reference expansion.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `<QUERY>` | positional | required | Search text or entity ref (`issue:42`, `mr:99`) |
+| `-p, --project` | string | — | Scope to project |
+| `--since` | duration/date | — | Filter events after |
+| `--depth` | int | 1 | Cross-ref expansion depth (0=none) |
+| `--no-mentions` | flag | — | Skip "mentioned" edges, keep "closes"/"related" |
+| `-n, --limit` | int | 100 | Max events |
+| `--fields` | string | — | Preset: `minimal` |
+| `--max-seeds` | int | 10 | Max seed entities from search |
+| `--max-entities` | int | 50 | Max expanded entities |
+| `--max-evidence` | int | 10 | Max evidence notes |
+
+**Pipeline:** SEED -> HYDRATE -> EXPAND -> COLLECT -> RENDER
+
+**DB tables:** `issues`, `merge_requests`, `discussions`, `notes`, `entity_references`, `resource_state_events`, `resource_label_events`, `resource_milestone_events`, `documents` (for search seeding)
+
+### Robot Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "query": "authentication", "event_count": 25,
+    "seed_entities": [{ "type": "issue", "iid": 42, "project": "group/repo" }],
+    "expanded_entities": [
+      {
+        "type": "mr", "iid": 99, "project": "group/repo", "depth": 1,
+        "via": {
+          "from": { "type": "issue", "iid": 42 },
+          "reference_type": "closes"
+        }
+      }
+    ],
+    "unresolved_references": [
+      {
+        "source": { "type": "issue", "iid": 42, "project": "group/repo" },
+        "target_type": "mr", "target_iid": 200, "reference_type": "mentioned"
+      }
+    ],
+    "events": [
+      {
+        "timestamp": "2026-01-15T10:30:00Z",
+        "entity_type": "issue", "entity_iid": 42, "project": "group/repo",
+        "event_type": "state_changed", "summary": "Reopened",
+        "actor": "jdoe", "is_seed": true,
+        "evidence_notes": [{ "author": "jdoe", "snippet": "..." }]
+      }
+    ]
+  },
+  "meta": {
+    "elapsed_ms": 150, "search_mode": "fts",
+    "expansion_depth": 1, "include_mentions": true,
+    "total_entities": 5, "total_events": 25,
+    "evidence_notes_included": 8, "discussion_threads_included": 3,
+    "unresolved_references": 1, "showing": 25
+  }
+}
+```
+
+**Minimal preset:** `timestamp`, `type`, `entity_iid`, `detail`
+
+---
+
+## `me` (Personal Dashboard)
+
+Personal work dashboard with issues, MRs, activity, and since-last-check inbox.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `--issues` | flag | — | Open issues section only |
+| `--mrs` | flag | — | MRs section only |
+| `--activity` | flag | — | Activity feed only |
+| `--since` | duration/date | `30d` | Activity window |
+| `-p, --project` | string | — | Scope to one project |
+| `--all` | flag | — | All synced projects |
+| `--user` | string | — | Override configured username |
+| `--fields` | string | — | Preset: `minimal` |
+| `--reset-cursor` | flag | — | Clear since-last-check cursor |
+
+**Sections (no flags = all):** Issues, MRs authored, MRs reviewing, Activity, Inbox
+
+**DB tables:** `issues`, `merge_requests`, `resource_state_events`, `projects`, `issue_labels`, `mr_labels`
+
+### Robot Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "username": "jdoe",
+    "summary": {
+      "project_count": 3, "open_issue_count": 5,
+      "authored_mr_count": 2, "reviewing_mr_count": 1,
+      "needs_attention_count": 3
+    },
+    "since_last_check": {
+      "cursor_iso": "2026-02-25T18:00:00Z",
+      "total_event_count": 8,
+      "groups": [
+        {
+          "entity_type": "issue", "entity_iid": 42,
+          "entity_title": "Fix auth", "project": "group/repo",
+          "events": [
+            { "timestamp_iso": "...", "event_type": "comment",
+              "actor": "reviewer", "summary": "New comment" }
+          ]
+        }
+      ]
+    },
+    "open_issues": [
+      {
+        "project": "group/repo", "iid": 42, "title": "Fix auth",
+        "state": "opened", "attention_state": "needs_attention",
+        "status_name": "In progress", "labels": ["auth"],
+        "updated_at_iso": "..."
+      }
+    ],
+    "open_mrs_authored": [
+      {
+        "project": "group/repo", "iid": 99, "title": "Refactor auth",
+        "state": "opened", "attention_state": "needs_attention",
+        "draft": false, "labels": ["backend"], "updated_at_iso": "..."
+      }
+    ],
+    "reviewing_mrs": [],
+    "activity": [
+      {
+        "timestamp_iso": "...", "event_type": "state_changed",
+        "entity_type": "issue", "entity_iid": 42, "project": "group/repo",
+        "actor": "jdoe", "is_own": true, "summary": "Closed"
+      }
+    ]
+  }
+}
+```
+
+**Minimal presets:** Items: `iid, title, attention_state, updated_at_iso` | Activity: `timestamp_iso, event_type, entity_iid, actor`
+
+---
+
+## `file-history`
+
+Show which MRs touched a file, with linked discussions.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `<PATH>` | positional | required | File path to trace |
+| `-p, --project` | string | — | Scope to project |
+| `--discussions` | flag | — | Include DiffNote snippets |
+| `--no-follow-renames` | flag | — | Skip rename chain resolution |
+| `--merged` | flag | — | Only merged MRs |
+| `-n, --limit` | int | 50 | Max MRs |
+
+**DB tables:** `mr_file_changes`, `merge_requests`, `notes` (DiffNotes), `projects`
+
+### Robot Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "path": "src/auth/middleware.rs",
+    "rename_chain": [
+      { "previous_path": "src/auth.rs", "mr_iid": 55, "merged_at": "..." }
+    ],
+    "merge_requests": [
+      {
+        "iid": 99, "title": "Refactor auth", "state": "merged",
+        "author": "jdoe", "merged_at": "...", "change_type": "modified"
+      }
+    ],
+    "discussions": [
+      {
+        "discussion_id": 123, "mr_iid": 99, "author": "reviewer",
+        "body_snippet": "...", "path": "src/auth/middleware.rs"
+      }
+    ]
+  },
+  "meta": { "elapsed_ms": 30, "total_mrs": 5, "renames_followed": true }
+}
+```
+
+---
+
+## `trace`
+
+File -> MR -> issue -> discussion chain to understand why code was introduced.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `<PATH>` | positional | required | File path (future: `:line` suffix) |
+| `-p, --project` | string | — | Scope to project |
+| `--discussions` | flag | — | Include DiffNote snippets |
+| `--no-follow-renames` | flag | — | Skip rename chain |
+| `-n, --limit` | int | 20 | Max chains |
+
+**DB tables:** `mr_file_changes`, `merge_requests`, `issues`, `discussions`, `notes`, `entity_references`
+
+### Robot Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "path": "src/auth/middleware.rs",
+    "resolved_paths": ["src/auth/middleware.rs", "src/auth.rs"],
+    "trace_chains": [
+      {
+        "mr_iid": 99, "mr_title": "Refactor auth", "mr_state": "merged",
+        "mr_author": "jdoe", "change_type": "modified",
+        "merged_at_iso": "...", "web_url": "...",
+        "issues": [42],
+        "discussions": [
+          {
+            "discussion_id": 123, "author_username": "reviewer",
+            "body_snippet": "...", "path": "src/auth/middleware.rs"
+          }
+        ]
+      }
+    ]
+  },
+  "meta": { "tier": "api_only", "total_chains": 3, "renames_followed": 1 }
+}
+```
+
+---
+
+## `related`
+
+Find semantically related entities via vector search.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `<QUERY_OR_TYPE>` | positional | required | Entity type (`issues`, `mrs`) or free text |
+| `[IID]` | positional | — | Entity IID (required with entity type) |
+| `-n, --limit` | int | 10 | Max results |
+| `-p, --project` | string | — | Scope to project |
+
+**Two modes:**
+- **Entity mode:** `related issues 42` — find entities similar to issue #42
+- **Query mode:** `related "auth flow"` — find entities matching free text
+
+**DB tables:** `documents`, `embeddings` (vec0), `projects`
+
+**Requires:** Ollama running (for query mode embedding)
+
+### Robot Output (entity mode)
+
+```json
+{
+  "ok": true,
+  "data": {
+    "query_entity_type": "issue",
+    "query_entity_iid": 42,
+    "query_entity_title": "Fix SSO authentication",
+    "similar_entities": [
+      {
+        "entity_type": "mr", "entity_iid": 99,
+        "entity_title": "Refactor auth module",
+        "project_path": "group/repo", "state": "merged",
+        "similarity_score": 0.87,
+        "shared_labels": ["auth"], "shared_authors": ["jdoe"]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## `drift`
+
+Detect discussion divergence from original intent.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `<ENTITY_TYPE>` | positional | required | Currently only `issues` |
+| `<IID>` | positional | required | Entity IID |
+| `--threshold` | f32 | 0.4 | Similarity threshold (0.0-1.0) |
+| `-p, --project` | string | — | Scope to project |
+
+**DB tables:** `issues`, `discussions`, `notes`, `embeddings`
+
+**Requires:** Ollama running
+
+### Robot Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "entity_type": "issue", "entity_iid": 42,
+    "total_notes": 15,
+    "detected_drift": true,
+    "drift_point": {
+      "note_index": 8, "similarity": 0.32,
+      "author": "someone", "created_at": "..."
+    },
+    "similarity_curve": [
+      { "note_index": 0, "similarity": 0.95, "author": "jdoe", "created_at": "..." },
+      { "note_index": 1, "similarity": 0.88, "author": "reviewer", "created_at": "..." }
+    ]
+  }
+}
+```

docs/command-surface-analysis/03-pipeline-and-infra.md

@@ -0,0 +1,210 @@
+# Pipeline & Infrastructure Commands
+
+Reference for: `sync`, `ingest`, `generate-docs`, `embed`, `health`, `auth`, `doctor`, `status`, `stats`, `init`, `token`, `cron`, `migrate`, `version`, `completions`, `robot-docs`
+
+---
+
+## Data Pipeline
+
+### `sync` (Full Pipeline)
+
+Complete sync: ingest -> generate-docs -> embed.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `--full` | flag | — | Full re-sync (reset cursors) |
+| `-f, --force` | flag | — | Override stale lock |
+| `--no-embed` | flag | — | Skip embedding |
+| `--no-docs` | flag | — | Skip doc generation |
+| `--no-events` | flag | — | Skip resource events |
+| `--no-file-changes` | flag | — | Skip MR file changes |
+| `--no-status` | flag | — | Skip work-item status enrichment |
+| `--dry-run` | flag | — | Preview without changes |
+| `-t, --timings` | flag | — | Show timing breakdown |
+| `--lock` | flag | — | Acquire file lock |
+| `--issue` | int[] | — | Surgically sync specific issues (repeatable) |
+| `--mr` | int[] | — | Surgically sync specific MRs (repeatable) |
+| `-p, --project` | string | — | Required with `--issue`/`--mr` |
+| `--preflight-only` | flag | — | Validate without DB writes |
+
+**Stages:** GitLab REST ingest -> GraphQL status enrichment -> Document generation -> Ollama embedding
+
+**Surgical sync:** `lore sync --issue 42 --mr 99 -p group/repo` fetches only specific entities.
+
+### `ingest`
+
+Fetch data from GitLab API only (no docs, no embeddings).
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `[ENTITY]` | positional | — | `issues` or `mrs` (omit for all) |
+| `-p, --project` | string | — | Single project |
+| `-f, --force` | flag | — | Override stale lock |
+| `--full` | flag | — | Full re-sync |
+| `--dry-run` | flag | — | Preview |
+
+**Fetches from GitLab:**
+- Issues + discussions + notes
+- MRs + discussions + notes
+- Resource events (state, label, milestone)
+- MR file changes (for DiffNote tracking)
+- Work-item statuses (via GraphQL)
+
+### `generate-docs`
+
+Create searchable documents from ingested data.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `--full` | flag | — | Full rebuild |
+| `-p, --project` | string | — | Single project rebuild |
+
+**Writes:** `documents`, `document_labels`, `document_paths`
+
+### `embed`
+
+Generate vector embeddings via Ollama.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `--full` | flag | — | Re-embed all |
+| `--retry-failed` | flag | — | Retry failed embeddings |
+
+**Requires:** Ollama running with `nomic-embed-text`
+**Writes:** `embeddings`, `embedding_metadata`
+
+---
+
+## Diagnostics
+
+### `health`
+
+Quick pre-flight check (~50ms). Exit 0 = healthy, exit 19 = unhealthy.
+
+**Checks:** config found, DB found, schema version current.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "healthy": true,
+    "config_found": true, "db_found": true,
+    "schema_current": true, "schema_version": 28
+  }
+}
+```
+
+### `auth`
+
+Verify GitLab authentication.
+
+**Checks:** token set, GitLab reachable, user identity.
+
+### `doctor`
+
+Comprehensive environment check.
+
+**Checks:** config validity, token, GitLab connectivity, DB health, migration status, Ollama availability + model status.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "config": { "valid": true, "path": "~/.config/lore/config.json" },
+    "token": { "set": true, "gitlab": { "reachable": true, "user": "jdoe" } },
+    "database": { "exists": true, "version": 28, "tables": 25 },
+    "ollama": { "available": true, "model_ready": true }
+  }
+}
+```
+
+### `status` (alias: `st`)
+
+Show sync state per project.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "projects": [
+      {
+        "project_path": "group/repo",
+        "last_synced_at": "2026-02-26T10:00:00Z",
+        "document_count": 5000, "discussion_count": 2000, "notes_count": 15000
+      }
+    ]
+  }
+}
+```
+
+### `stats` (alias: `stat`)
+
+Document and index statistics with optional integrity checks.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `--check` | flag | — | Run integrity checks |
+| `--repair` | flag | — | Fix issues (implies `--check`) |
+| `--dry-run` | flag | — | Preview repairs |
+
+```json
+{
+  "ok": true,
+  "data": {
+    "documents": { "total": 61652, "issues": 5000, "mrs": 2000, "notes": 50000 },
+    "embeddings": { "total": 80000, "synced": 79500, "pending": 500, "failed": 0 },
+    "fts": { "total_docs": 61652 },
+    "queues": { "pending": 0, "in_progress": 0, "failed": 0, "max_attempts": 0 },
+    "integrity": {
+      "ok": true, "fts_doc_mismatch": 0, "orphan_embeddings": 0,
+      "stale_metadata": 0, "orphan_state_events": 0
+    }
+  }
+}
+```
+
+---
+
+## Setup
+
+### `init`
+
+Initialize configuration and database.
+
+| Flag | Type | Default | Purpose |
+|---|---|---|---|
+| `-f, --force` | flag | — | Skip overwrite confirmation |
+| `--non-interactive` | flag | — | Fail if prompts needed |
+| `--gitlab-url` | string | — | GitLab base URL (required in robot mode) |
+| `--token-env-var` | string | — | Env var holding token (required in robot mode) |
+| `--projects` | string | — | Comma-separated project paths (required in robot mode) |
+| `--default-project` | string | — | Default project path |
+
+### `token`
+
+| Subcommand | Flags | Purpose |
+|---|---|---|
+| `token set` | `--token <TOKEN>` | Store token (reads stdin if omitted) |
+| `token show` | `--unmask` | Display token (masked by default) |
+
+### `cron`
+
+| Subcommand | Flags | Purpose |
+|---|---|---|
+| `cron install` | `--interval <MINUTES>` (default: 8) | Schedule auto-sync |
+| `cron uninstall` | — | Remove cron job |
+| `cron status` | — | Check installation |
+
+### `migrate`
+
+Run pending database migrations. No flags.
+
+---
+
+## Meta
+
+| Command | Purpose |
+|---|---|
+| `version` | Show version string |
+| `completions <shell>` | Generate shell completions (bash/zsh/fish/powershell) |
+| `robot-docs` | Machine-readable command manifest (`--brief` for ~60% smaller) |

docs/command-surface-analysis/04-data-flow.md

@@ -0,0 +1,179 @@
+# Data Flow & Command Network
+
+How commands interconnect through shared data sources and output-to-input dependencies.
+
+---
+
+## 1. Command Network Graph
+
+Arrows mean "output of A feeds as input to B":
+
+```
+                    ┌─────────┐
+                    │ search  │─────────────────────────────┐
+                    └────┬────┘                             │
+                         │ iid                              │ topic
+                    ┌────▼────┐                        ┌────▼─────┐
+              ┌─────│ issues  │◄───────────────────────│ timeline │
+              │     │ mrs     │ (detail)               └──────────┘
+              │     └────┬────┘                             ▲
+              │          │ iid                              │ entity ref
+              │     ┌────▼────┐     ┌──────────────┐       │
+              │     │ related │     │ file-history  │───────┘
+              │     │ drift   │     └──────┬───────┘
+              │     └─────────┘            │ MR iids
+              │                       ┌────▼────┐
+              │                       │  trace  │──── issues (linked)
+              │                       └────┬────┘
+              │                            │ paths
+              │                       ┌────▼────┐
+              │                       │   who   │
+              │                       │ (expert)│
+              │                       └─────────┘
+              │
+         file paths                   ┌─────────┐
+              │                       │   me    │──── issues, mrs (dashboard)
+              ▼                       └─────────┘
+        ┌──────────┐                       ▲
+        │  notes   │                       │ (~same data)
+        └──────────┘                  ┌────┴──────┐
+                                      │who workload│
+                                      └───────────┘
+```
+
+### Feed Chains (output of A -> input of B)
+
+| From | To | What Flows |
+|---|---|---|
+| `search` | `issues`, `mrs` | IIDs from search results -> detail lookup |
+| `search` | `timeline` | Topic/query -> chronological history |
+| `search` | `related` | Entity IID -> semantic similarity |
+| `me` | `issues`, `mrs` | IIDs from dashboard -> detail lookup |
+| `trace` | `issues` | Linked issue IIDs -> detail lookup |
+| `trace` | `who` | File paths -> expert lookup |
+| `file-history` | `mrs` | MR IIDs -> detail lookup |
+| `file-history` | `timeline` | Entity refs -> chronological events |
+| `timeline` | `issues`, `mrs` | Referenced IIDs -> detail lookup |
+| `who expert` | `who reviews` | Username -> review patterns |
+| `who expert` | `mrs` | MR IIDs from expert detail -> MR detail |
+
+---
+
+## 2. Shared Data Source Map
+
+Which DB tables power which commands. Higher overlap = stronger consolidation signal.
+
+### Primary Entity Tables
+
+| Table | Read By |
+|---|---|
+| `issues` | issues, me, who-workload, search, timeline, trace, count, stats |
+| `merge_requests` | mrs, me, who-workload, search, timeline, trace, file-history, count, stats |
+| `notes` | notes, issues-detail, mrs-detail, who-expert, who-active, search, timeline, trace, file-history |
+| `discussions` | notes, issues-detail, mrs-detail, who-active, who-reviews, timeline, trace |
+
+### Relationship Tables
+
+| Table | Read By |
+|---|---|
+| `entity_references` | trace, timeline |
+| `mr_file_changes` | trace, file-history, who-overlap |
+| `issue_labels` | issues, me |
+| `mr_labels` | mrs, me |
+| `issue_assignees` | issues, me |
+| `mr_reviewers` | mrs, who-expert, who-workload |
+
+### Event Tables
+
+| Table | Read By |
+|---|---|
+| `resource_state_events` | timeline, me-activity |
+| `resource_label_events` | timeline |
+| `resource_milestone_events` | timeline |
+
+### Document/Search Tables
+
+| Table | Read By |
+|---|---|
+| `documents` + `documents_fts` | search, stats |
+| `embeddings` | search, related, drift |
+| `document_labels` | search |
+| `document_paths` | search |
+
+### Infrastructure Tables
+
+| Table | Read By |
+|---|---|
+| `sync_cursors` | status |
+| `dirty_sources` | stats |
+| `embedding_metadata` | stats, embed |
+
+---
+
+## 3. Shared-Data Clusters
+
+Commands that read from the same primary tables form natural clusters:
+
+### Cluster A: Issue/MR Entities
+
+`issues`, `mrs`, `me`, `who workload`, `count`
+
+All read `issues` + `merge_requests` with similar filter patterns (state, author, labels, project). These commands share the same underlying WHERE-clause builder logic.
+
+### Cluster B: Notes/Discussions
+
+`notes`, `issues detail`, `mrs detail`, `who expert`, `who active`, `timeline`
+
+All traverse the `discussions` -> `notes` join path. The `notes` command does it with independent filters; the others embed notes within parent context.
+
+### Cluster C: File Genealogy
+
+`trace`, `file-history`, `who overlap`
+
+All use `mr_file_changes` with rename chain BFS (forward: old_path -> new_path, backward: new_path -> old_path). Shared `resolve_rename_chain()` function.
+
+### Cluster D: Semantic/Vector
+
+`search`, `related`, `drift`
+
+All use `documents` + `embeddings` via Ollama. `search` adds FTS component; `related` is pure vector; `drift` uses vector for divergence scoring.
+
+### Cluster E: Diagnostics
+
+`health`, `auth`, `doctor`, `status`, `stats`
+
+All check system state. `health` < `doctor` (strict subset). `status` checks sync cursors. `stats` checks document/index health. `auth` checks token/connectivity.
+
+---
+
+## 4. Query Pattern Sharing
+
+### Dynamic Filter Builder (used by issues, mrs, notes)
+
+All three list commands use the same pattern: build a WHERE clause dynamically from filter flags with parameterized tokens. Labels use EXISTS subquery against junction table.
+
+### Rename Chain BFS (used by trace, file-history, who overlap)
+
+Forward query:
+```sql
+SELECT DISTINCT new_path FROM mr_file_changes
+WHERE project_id = ?1 AND old_path = ?2 AND change_type = 'renamed'
+```
+
+Backward query:
+```sql
+SELECT DISTINCT old_path FROM mr_file_changes
+WHERE project_id = ?1 AND new_path = ?2 AND change_type = 'renamed'
+```
+
+Cycle detection via `HashSet` of visited paths, `MAX_RENAME_HOPS = 10`.
+
+### Hybrid Search (used by search, timeline seeding)
+
+RRF ranking: `score = (60 / fts_rank) + (60 / vector_rank)`
+
+FTS5 queries go through `to_fts_query()` which sanitizes input and builds MATCH expressions. Vector search calls Ollama to embed the query, then does cosine similarity against `embeddings` vec0 table.
+
+### Project Resolution (used by most commands)
+
+`resolve_project(conn, project_filter)` does fuzzy matching on `path_with_namespace` — suffix and substring matching. Returns `(project_id, path_with_namespace)`.

docs/command-surface-analysis/05-overlap-analysis.md

@@ -0,0 +1,170 @@
+# Overlap Analysis
+
+Quantified functional duplication between commands.
+
+---
+
+## 1. High Overlap (>70%)
+
+### `who workload` vs `me` — 85% overlap
+
+| Dimension | `who @user` (workload) | `me --user @user` |
+|---|---|---|
+| Assigned issues | Yes | Yes |
+| Authored MRs | Yes | Yes |
+| Reviewing MRs | Yes | Yes |
+| Attention state | No | **Yes** |
+| Activity feed | No | **Yes** |
+| Since-last-check inbox | No | **Yes** |
+| Cross-project | Yes | **Yes** |
+
+**Verdict:** `who workload` is a strict subset of `me`. The only reason to use `who workload` is if you DON'T want attention_state/activity/inbox — but `me --issues --mrs --fields minimal` achieves the same thing.
+
+### `health` vs `doctor` — 90% overlap
+
+| Check | `health` | `doctor` |
+|---|---|---|
+| Config found | Yes | Yes |
+| DB exists | Yes | Yes |
+| Schema current | Yes | Yes |
+| Token valid | No | **Yes** |
+| GitLab reachable | No | **Yes** |
+| Ollama available | No | **Yes** |
+
+**Verdict:** `health` is a strict subset of `doctor`. However, `health` has unique value as a ~50ms pre-flight with clean exit 0/19 semantics for scripting.
+
+### `file-history` vs `trace` — 75% overlap
+
+| Feature | `file-history` | `trace` |
+|---|---|---|
+| Find MRs for file | Yes | Yes |
+| Rename chain BFS | Yes | Yes |
+| DiffNote discussions | `--discussions` | `--discussions` |
+| Follow to linked issues | No | **Yes** |
+| `--merged` filter | **Yes** | No |
+
+**Verdict:** `trace` is a superset of `file-history` minus the `--merged` filter. Both use the same `resolve_rename_chain()` function and query `mr_file_changes`.
+
+### `related` query-mode vs `search --mode semantic` — 80% overlap
+
+| Feature | `related "text"` | `search "text" --mode semantic` |
+|---|---|---|
+| Vector similarity | Yes | Yes |
+| FTS component | No | No (semantic mode skips FTS) |
+| Filters (labels, author, since) | No | **Yes** |
+| Explain ranking | No | **Yes** |
+| Field selection | No | **Yes** |
+| Requires Ollama | Yes | Yes |
+
+**Verdict:** `related "text"` is `search --mode semantic` without any filter capabilities. The entity-seeded mode (`related issues 42`) is NOT duplicated — it seeds from an existing entity's embedding.
+
+---
+
+## 2. Medium Overlap (40-70%)
+
+### `who expert` vs `who overlap` — 50%
+
+Both answer "who works on this file" but with different scoring:
+
+| Aspect | `who expert` | `who overlap` |
+|---|---|---|
+| Scoring | Half-life decay, signal types (diffnote_author, reviewer, etc.) | Raw touch count |
+| Output | Ranked experts with scores | Users with touch counts |
+| Use case | "Who should review this?" | "Who else touches this?" |
+
+**Verdict:** Overlap is a simplified version of expert. Expert could include touch_count as a field.
+
+### `timeline` vs `trace` — 45%
+
+Both follow `entity_references` to discover connected entities, but from different entry points:
+
+| Aspect | `timeline` | `trace` |
+|---|---|---|
+| Entry point | Entity (issue/MR) or search query | File path |
+| Direction | Entity -> cross-refs -> events | File -> MRs -> issues -> discussions |
+| Output | Chronological events | Causal chains (why code changed) |
+| Expansion | Depth-controlled cross-ref following | MR -> issue via entity_references |
+
+**Verdict:** Complementary, not duplicative. Different questions, shared plumbing.
+
+### `auth` vs `doctor` — 100% of auth
+
+`auth` checks: token set + GitLab reachable + user identity.
+`doctor` checks: all of the above + DB + schema + Ollama.
+
+**Verdict:** `auth` is completely contained within `doctor`.
+
+### `count` vs `stats` — 40%
+
+Both answer "how much data?":
+
+| Aspect | `count` | `stats` |
+|---|---|---|
+| Layer | Entity (issues, MRs, notes) | Document index |
+| State breakdown | Yes (opened/closed/merged) | No |
+| Integrity checks | No | Yes |
+| Queue status | No | Yes |
+
+**Verdict:** Different layers. Could be unified under `stats --entities`.
+
+### `notes` vs `issues/mrs detail` — 50%
+
+Both return note content:
+
+| Aspect | `notes` command | Detail view discussions |
+|---|---|---|
+| Independent filtering | **Yes** (author, path, resolution, contains, type) | No |
+| Parent context | Minimal (parent_iid, parent_title) | **Full** (complete entity + all discussions) |
+| Cross-entity queries | **Yes** (all notes matching criteria) | No (one entity only) |
+
+**Verdict:** `notes` is for filtered queries across entities. Detail views are for complete context on one entity. Different use cases.
+
+---
+
+## 3. No Significant Overlap
+
+| Command | Why It's Unique |
+|---|---|
+| `drift` | Only command doing semantic divergence detection |
+| `timeline` | Only command doing multi-entity chronological reconstruction with expansion |
+| `search` (hybrid) | Only command combining FTS + vector with RRF ranking |
+| `me` (inbox) | Only command with cursor-based since-last-check tracking |
+| `who expert` | Only command with half-life decay scoring by signal type |
+| `who reviews` | Only command analyzing review patterns (approval rate, latency) |
+| `who active` | Only command surfacing unresolved discussions needing attention |
+
+---
+
+## 4. Overlap Adjacency Matrix
+
+Rows/columns are commands. Values are estimated functional overlap percentage.
+
+```
+              issues  mrs  notes  search  who-e  who-w  who-r  who-a  who-o  timeline  me  fh  trace  related  drift  count  status  stats  health  doctor
+issues          -     30    50      20      5      40      0      5      0       15    40    0     10      10      0     20       0      10      0       0
+mrs            30      -    50      20      5      40      0      5      0       15    40    5     10      10      0     20       0      10      0       0
+notes          50     50     -      15     15       0      5     10      0       10     0    5      5       0      0      0       0       0      0       0
+search         20     20    15       -      0       0      0      0      0       15     0    0      0      80      0      0       0       5      0       0
+who-expert      5      5    15       0      -       0     10      0     50        0     0   10     10       0      0      0       0       0      0       0
+who-workload   40     40     0       0      0       -      0      0      0        0    85    0      0       0      0      0       0       0      0       0
+who-reviews     0      0     5       0     10       0      -      0      0        0     0    0      0       0      0      0       0       0      0       0
+who-active      5      5    10       0      0       0      0      -      0        5     0    0      0       0      0      0       0       0      0       0
+who-overlap     0      0     0       0     50       0      0      0      -        0     0   10      5       0      0      0       0       0      0       0
+timeline       15     15    10      15      0       0      0      5      0        -     5    5     45       0      0      0       0       0      0       0
+me             40     40     0       0      0      85      0      0      0        5     -    0      0       0      0      0       5       0      5       5
+file-history    0      5     5       0     10       0      0      0     10        5     0    -     75       0      0      0       0       0      0       0
+trace          10     10     5       0     10       0      0      0      5       45     0   75      -       0      0      0       0       0      0       0
+related        10     10     0      80      0       0      0      0      0        0     0    0      0       -      0      0       0       0      0       0
+drift           0      0     0       0      0       0      0      0      0        0     0    0      0       0      -      0       0       0      0       0
+count          20     20     0       0      0       0      0      0      0        0     0    0      0       0      0      -       0      40      0       0
+status          0      0     0       0      0       0      0      0      0        0     5    0      0       0      0      0       -      20     30      40
+stats          10     10     0       5      0       0      0      0      0        0     0    0      0       0      0     40      20       -      0      15
+health          0      0     0       0      0       0      0      0      0        0     5    0      0       0      0      0      30       0      -      90
+doctor          0      0     0       0      0       0      0      0      0        0     5    0      0       0      0      0      40      15     90       -
+```
+
+**Highest overlap pairs (>= 75%):**
+1. `health` / `doctor` — 90%
+2. `who workload` / `me` — 85%
+3. `related` query-mode / `search semantic` — 80%
+4. `file-history` / `trace` — 75%

docs/command-surface-analysis/06-agent-workflows.md

@@ -0,0 +1,216 @@
+# Agent Workflow Analysis
+
+Common agent workflows, round-trip costs, and token profiles.
+
+---
+
+## 1. Common Workflows
+
+### Flow 1: "What should I work on?" — 4 round trips
+
+```
+me                            → dashboard overview (which items need attention?)
+issues <iid> -p proj         → detail on picked issue (full context + discussions)
+trace src/relevant/file.rs    → understand code context (why was it written?)
+who src/relevant/file.rs      → find domain experts (who can help?)
+```
+
+**Total tokens (minimal):** ~800 + ~2000 + ~1000 + ~400 = ~4200
+**Total tokens (full):** ~3000 + ~6000 + ~1500 + ~800 = ~11300
+**Latency:** 4 serial round trips
+
+### Flow 2: "What happened with this feature?" — 3 round trips
+
+```
+search "feature name"         → find relevant entities
+timeline "feature name"       → reconstruct chronological history
+related issues 42             → discover connected work
+```
+
+**Total tokens (minimal):** ~600 + ~1500 + ~400 = ~2500
+**Total tokens (full):** ~2000 + ~5000 + ~1000 = ~8000
+**Latency:** 3 serial round trips
+
+### Flow 3: "Why was this code changed?" — 3 round trips
+
+```
+trace src/file.rs             → file -> MR -> issue chain
+issues <iid> -p proj         → full issue detail
+timeline "issue:42"           → full history with cross-refs
+```
+
+**Total tokens (minimal):** ~800 + ~2000 + ~1500 = ~4300
+**Total tokens (full):** ~1500 + ~6000 + ~5000 = ~12500
+**Latency:** 3 serial round trips
+
+### Flow 4: "Is the system healthy?" — 2-4 round trips
+
+```
+health                        → quick pre-flight (pass/fail)
+doctor                        → detailed diagnostics (if health fails)
+status                        → sync state per project
+stats                         → document/index health
+```
+
+**Total tokens:** ~100 + ~300 + ~200 + ~400 = ~1000
+**Latency:** 2-4 serial round trips (often 1 if health passes)
+
+### Flow 5: "Who can review this?" — 2-3 round trips
+
+```
+who src/auth/                 → find file experts
+who @jdoe --reviews           → check reviewer's patterns
+```
+
+**Total tokens (minimal):** ~300 + ~300 = ~600
+**Latency:** 2 serial round trips
+
+### Flow 6: "Find and understand an issue" — 4 round trips
+
+```
+search "query"                → discover entities (get IIDs)
+issues <iid>                  → full detail with discussions
+timeline "issue:42"           → chronological context
+related issues 42             → connected entities
+```
+
+**Total tokens (minimal):** ~600 + ~2000 + ~1500 + ~400 = ~4500
+**Total tokens (full):** ~2000 + ~6000 + ~5000 + ~1000 = ~14000
+**Latency:** 4 serial round trips
+
+---
+
+## 2. Token Cost Profiles
+
+Measured typical response sizes in robot mode with default settings:
+
+| Command | Typical Tokens (full) | With `--fields minimal` | Dominant Cost Driver |
+|---|---|---|---|
+| `me` (all sections) | 2000-5000 | 500-1500 | Open items count |
+| `issues` (list, n=50) | 1500-3000 | 400-800 | Labels arrays |
+| `issues <iid>` (detail) | 1000-8000 | N/A (no minimal for detail) | Discussion depth |
+| `mrs <iid>` (detail) | 1000-8000 | N/A | Discussion depth, DiffNote positions |
+| `timeline` (limit=100) | 2000-6000 | 800-1500 | Event count + evidence |
+| `search` (n=20) | 1000-3000 | 300-600 | Snippet length |
+| `who expert` | 300-800 | 150-300 | Expert count |
+| `who workload` | 500-1500 | 200-500 | Open items count |
+| `trace` | 500-2000 | 300-800 | Chain depth |
+| `file-history` | 300-1500 | 200-500 | MR count |
+| `related` | 300-1000 | 200-400 | Result count |
+| `drift` | 200-800 | N/A | Similarity curve length |
+| `notes` (n=50) | 1500-5000 | 500-1000 | Body length |
+| `count` | ~100 | N/A | Fixed structure |
+| `stats` | ~500 | N/A | Fixed structure |
+| `health` | ~100 | N/A | Fixed structure |
+| `doctor` | ~300 | N/A | Fixed structure |
+| `status` | ~200 | N/A | Project count |
+
+### Key Observations
+
+1. **Detail commands are expensive.** `issues <iid>` and `mrs <iid>` can hit 8000 tokens due to discussions. This is the content agents actually need, but most of it is discussion body text.
+
+2. **`me` is the most-called command** and ranges 2000-5000 tokens. Agents often just need "do I have work?" which is ~100 tokens (summary counts only).
+
+3. **Lists with labels are wasteful.** Every issue/MR in a list carries its full label array. With 50 items x 5 labels each, that's 250 strings of overhead.
+
+4. **`--fields minimal` helps a lot** — 50-70% reduction on list commands. But it's not available on detail views.
+
+5. **Timeline scales linearly** with event count and evidence notes. The `--max-evidence` flag helps cap the expensive part.
+
+---
+
+## 3. Round-Trip Inefficiency Patterns
+
+### Pattern A: Discovery -> Detail (N+1)
+
+Agent searches, gets 5 results, then needs detail on each:
+
+```
+search "auth bug"              → 5 results
+issues 42 -p proj             → detail
+issues 55 -p proj             → detail
+issues 71 -p proj             → detail
+issues 88 -p proj             → detail
+issues 95 -p proj             → detail
+```
+
+**6 round trips** for what should be 2 (search + batch detail).
+
+### Pattern B: Detail -> Context Gathering
+
+Agent gets issue detail, then needs timeline + related + trace:
+
+```
+issues 42 -p proj             → detail
+timeline "issue:42" -p proj   → events
+related issues 42 -p proj     → similar
+trace src/file.rs -p proj     → code provenance
+```
+
+**4 round trips** for what should be 1 (detail with embedded context).
+
+### Pattern C: Health Check Cascade
+
+Agent checks health, discovers issue, drills down:
+
+```
+health                         → unhealthy (exit 19)
+doctor                         → token OK, Ollama missing
+stats --check                  → 5 orphan embeddings
+stats --repair                 → fixed
+```
+
+**4 round trips** but only 2 are actually needed (doctor covers health).
+
+### Pattern D: Dashboard -> Action
+
+Agent checks dashboard, picks item, needs full context:
+
+```
+me                             → 5 open issues, 2 MRs
+issues 42 -p proj             → picked issue detail
+who src/auth/ -p proj         → expert for help
+timeline "issue:42" -p proj   → history
+```
+
+**4 round trips.** With `--include`, could be 2 (me with inline detail + who).
+
+---
+
+## 4. Optimized Workflow Vision
+
+What the same workflows look like with proposed optimizations:
+
+### Flow 1 Optimized: "What should I work on?" — 2 round trips
+
+```
+me --depth titles              → 400 tokens: counts + item titles with attention_state
+issues 42 --include timeline,trace  → 1 call: detail + events + code provenance
+```
+
+### Flow 2 Optimized: "What happened with this feature?" — 1-2 round trips
+
+```
+search "feature" -n 5          → find entities
+issues 42 --include timeline,related → everything in one call
+```
+
+### Flow 3 Optimized: "Why was this code changed?" — 1 round trip
+
+```
+trace src/file.rs --include experts,timeline → full chain + experts + events
+```
+
+### Flow 4 Optimized: "Is the system healthy?" — 1 round trip
+
+```
+doctor                         → covers health + auth + connectivity
+# status + stats only if doctor reveals issues
+```
+
+### Flow 6 Optimized: "Find and understand" — 2 round trips
+
+```
+search "query" -n 5            → discover entities
+issues --batch 42,55,71 --include timeline → batch detail with events
+```

docs/command-surface-analysis/07-consolidation-proposals.md

@@ -0,0 +1,198 @@
+# Consolidation Proposals
+
+5 proposals to reduce 34 commands to 29 by merging high-overlap commands.
+
+---
+
+## A. Absorb `file-history` into `trace --shallow`
+
+**Overlap:** 75%. Both do rename chain BFS on `mr_file_changes`, both optionally include DiffNote discussions. `trace` follows `entity_references` to linked issues; `file-history` stops at MRs.
+
+**Current state:**
+```bash
+# These do nearly the same thing:
+lore file-history src/auth/ -p proj --discussions
+lore trace src/auth/ -p proj --discussions
+# trace just adds: issues linked via entity_references
+```
+
+**Proposed change:**
+- `trace <path>` — full chain: file -> MR -> issue -> discussions (existing behavior)
+- `trace <path> --shallow` — MR-only, no issue following (replaces `file-history`)
+- Move `--merged` flag from `file-history` to `trace`
+- Deprecate `file-history` as an alias that maps to `trace --shallow`
+
+**Migration path:**
+1. Add `--shallow` and `--merged` flags to `trace`
+2. Make `file-history` an alias with deprecation warning
+3. Update robot-docs to point to `trace`
+4. Remove alias after 2 releases
+
+**Breaking changes:** Robot output shape differs slightly (`trace_chains` vs `merge_requests` key name). The `--shallow` variant should match `file-history`'s output shape for compatibility.
+
+**Effort:** Low. Most code is already shared via `resolve_rename_chain()`.
+
+---
+
+## B. Absorb `auth` into `doctor`
+
+**Overlap:** 100% of `auth` is contained within `doctor`.
+
+**Current state:**
+```bash
+lore auth     # checks: token set, GitLab reachable, user identity
+lore doctor   # checks: all of above + DB + schema + Ollama
+```
+
+**Proposed change:**
+- `doctor` — full check (existing behavior)
+- `doctor --auth` — token + GitLab only (replaces `auth`)
+- Keep `health` separate (fast pre-flight, different exit code contract: 0/19)
+- Deprecate `auth` as alias for `doctor --auth`
+
+**Migration path:**
+1. Add `--auth` flag to `doctor`
+2. Make `auth` an alias with deprecation warning
+3. Remove alias after 2 releases
+
+**Breaking changes:** None for robot mode (same JSON shape). Exit code mapping needs verification.
+
+**Effort:** Low. Doctor already has the auth check logic.
+
+---
+
+## C. Remove `related` query-mode
+
+**Overlap:** 80% with `search --mode semantic`.
+
+**Current state:**
+```bash
+# These are functionally equivalent:
+lore related "authentication flow"
+lore search "authentication flow" --mode semantic
+
+# This is UNIQUE (no overlap):
+lore related issues 42
+```
+
+**Proposed change:**
+- Keep entity-seeded mode: `related issues 42` (seeds from existing entity embedding)
+- Remove free-text mode: `related "text"` -> error with suggestion: "Use `search --mode semantic`"
+- Alternatively: keep as sugar but document it as equivalent to search
+
+**Migration path:**
+1. Add deprecation warning when query-mode is used
+2. After 2 releases, remove query-mode parsing
+3. Entity-mode stays unchanged
+
+**Breaking changes:** Agents using `related "text"` must switch to `search --mode semantic`. This is a strict improvement since search has filters.
+
+**Effort:** Low. Just argument validation change.
+
+---
+
+## D. Merge `who overlap` into `who expert`
+
+**Overlap:** 50% functional, but overlap is a strict simplification of expert.
+
+**Current state:**
+```bash
+lore who src/auth/               # expert mode: scored rankings
+lore who --overlap src/auth/     # overlap mode: raw touch counts
+```
+
+**Proposed change:**
+- `who <path>` (expert) adds `touch_count` and `last_touch_at` fields to each expert row
+- `who --overlap <path>` becomes an alias for `who <path> --fields username,touch_count`
+- Eventually remove `--overlap` flag
+
+**New expert output:**
+```json
+{
+  "experts": [
+    {
+      "username": "jdoe", "score": 42.5,
+      "touch_count": 15, "last_touch_at": "2026-02-20",
+      "detail": { "mr_ids_author": [99, 101] }
+    }
+  ]
+}
+```
+
+**Migration path:**
+1. Add `touch_count` and `last_touch_at` to expert output
+2. Make `--overlap` an alias with deprecation warning
+3. Remove `--overlap` after 2 releases
+
+**Breaking changes:** Expert output gains new fields (non-breaking for JSON consumers). Overlap output shape changes if agents were parsing `{ "users": [...] }` vs `{ "experts": [...] }`.
+
+**Effort:** Low. Expert query already touches the same tables; just need to add a COUNT aggregation.
+
+---
+
+## E. Merge `count` and `status` into `stats`
+
+**Overlap:** `count` and `stats` both answer "how much data?"; `status` and `stats` both report system state.
+
+**Current state:**
+```bash
+lore count issues           # entity count + state breakdown
+lore count mrs              # entity count + state breakdown
+lore status                 # sync cursors per project
+lore stats                  # document/index counts + integrity
+```
+
+**Proposed change:**
+- `stats` — document/index health (existing behavior, default)
+- `stats --entities` — adds entity counts (replaces `count`)
+- `stats --sync` — adds sync cursor positions (replaces `status`)
+- `stats --all` — everything: entities + sync + documents + integrity
+- `stats --check` / `--repair` — unchanged
+
+**New `--all` output:**
+```json
+{
+  "data": {
+    "entities": {
+      "issues": { "total": 5000, "opened": 200, "closed": 4800 },
+      "merge_requests": { "total": 1234, "opened": 100, "closed": 50, "merged": 1084 },
+      "discussions": { "total": 8000 },
+      "notes": { "total": 282000, "system_excluded": 50000 }
+    },
+    "sync": {
+      "projects": [
+        { "project_path": "group/repo", "last_synced_at": "...", "document_count": 5000 }
+      ]
+    },
+    "documents": { "total": 61652, "issues": 5000, "mrs": 2000, "notes": 50000 },
+    "embeddings": { "total": 80000, "synced": 79500, "pending": 500 },
+    "fts": { "total_docs": 61652 },
+    "queues": { "pending": 0, "in_progress": 0, "failed": 0 },
+    "integrity": { "ok": true }
+  }
+}
+```
+
+**Migration path:**
+1. Add `--entities`, `--sync`, `--all` flags to `stats`
+2. Make `count` an alias for `stats --entities` with deprecation warning
+3. Make `status` an alias for `stats --sync` with deprecation warning
+4. Remove aliases after 2 releases
+
+**Breaking changes:** `count` output currently has `{ "entity": "issues", "count": N, "breakdown": {...} }`. Under `stats --entities`, this becomes nested under `data.entities`. Alias can preserve old shape during deprecation period.
+
+**Effort:** Medium. Need to compose three query paths into one response builder.
+
+---
+
+## Summary
+
+| Consolidation | Removes | Effort | Breaking? |
+|---|---|---|---|
+| `file-history` -> `trace --shallow` | -1 command | Low | Alias redirect, output shape compat |
+| `auth` -> `doctor --auth` | -1 command | Low | Alias redirect |
+| `related` query-mode removal | -1 mode | Low | Must switch to `search --mode semantic` |
+| `who overlap` -> `who expert` | -1 sub-mode | Low | Output gains fields |
+| `count` + `status` -> `stats` | -2 commands | Medium | Output nesting changes |
+
+**Total: 34 commands -> 29 commands.** All changes use deprecation-with-alias pattern for gradual migration.

docs/command-surface-analysis/08-robot-optimization-proposals.md

@@ -0,0 +1,347 @@
+# Robot-Mode Optimization Proposals
+
+6 proposals to reduce round trips and token waste for agent consumers.
+
+---
+
+## A. `--include` flag for embedded sub-queries (P0)
+
+**Problem:** The #1 agent inefficiency. Every "understand this entity" workflow requires 3-4 serial round trips: detail + timeline + related + trace.
+
+**Proposal:** Add `--include` flag to detail commands that embeds sub-query results in the response.
+
+```bash
+# Before: 4 round trips, ~12000 tokens
+lore -J issues 42 -p proj
+lore -J timeline "issue:42" -p proj --limit 20
+lore -J related issues 42 -p proj -n 5
+lore -J trace src/auth/ -p proj
+
+# After: 1 round trip, ~5000 tokens (sub-queries use reduced limits)
+lore -J issues 42 -p proj --include timeline,related
+```
+
+### Include Matrix
+
+| Base Command | Valid Includes | Default Limits |
+|---|---|---|
+| `issues <iid>` | `timeline`, `related`, `trace` | 20 events, 5 related, 5 chains |
+| `mrs <iid>` | `timeline`, `related`, `file-changes` | 20 events, 5 related |
+| `trace <path>` | `experts`, `timeline` | 5 experts, 20 events |
+| `me` | `detail` (inline top-N item details) | 3 items detailed |
+| `search` | `detail` (inline top-N result details) | 3 results detailed |
+
+### Response Shape
+
+Included data uses `_` prefix to distinguish from base fields:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "iid": 42, "title": "Fix auth", "state": "opened",
+    "discussions": [...],
+    "_timeline": {
+      "event_count": 15,
+      "events": [...]
+    },
+    "_related": {
+      "similar_entities": [...]
+    }
+  },
+  "meta": {
+    "elapsed_ms": 200,
+    "_timeline_ms": 45,
+    "_related_ms": 120
+  }
+}
+```
+
+### Error Handling
+
+Sub-query errors are non-fatal. If Ollama is down, `_related` returns an error instead of failing the whole request:
+
+```json
+{
+  "_related_error": "Ollama unavailable — related results skipped"
+}
+```
+
+### Limit Control
+
+```bash
+# Custom limits for included data
+lore -J issues 42 --include timeline:50,related:10
+```
+
+### Round-Trip Savings
+
+| Workflow | Before | After | Savings |
+|---|---|---|---|
+| Understand an issue | 4 calls | 1 call | **75%** |
+| Why was code changed | 3 calls | 1 call | **67%** |
+| Find and understand | 4 calls | 2 calls | **50%** |
+
+**Effort:** High. Each include needs its own sub-query executor, error isolation, and limit enforcement. But the payoff is massive — this single feature halves agent round trips.
+
+---
+
+## B. `--depth` control on `me` (P0)
+
+**Problem:** `me` returns 2000-5000 tokens. Agents checking "do I have work?" only need ~100 tokens.
+
+**Proposal:** Add `--depth` flag with three levels.
+
+```bash
+# Counts only (~100 tokens) — "do I have work?"
+lore -J me --depth counts
+
+# Titles (~400 tokens) — "what work do I have?"
+lore -J me --depth titles
+
+# Full (current behavior, 2000+ tokens) — "give me everything"
+lore -J me --depth full
+lore -J me  # same as --depth full
+```
+
+### Depth Levels
+
+| Level | Includes | Typical Tokens |
+|---|---|---|
+| `counts` | `summary` block only (counts, no items) | ~100 |
+| `titles` | summary + item lists with minimal fields (iid, title, attention_state) | ~400 |
+| `full` | Everything: items, activity, inbox, discussions | ~2000-5000 |
+
+### Response at `--depth counts`
+
+```json
+{
+  "ok": true,
+  "data": {
+    "username": "jdoe",
+    "summary": {
+      "project_count": 3,
+      "open_issue_count": 5,
+      "authored_mr_count": 2,
+      "reviewing_mr_count": 1,
+      "needs_attention_count": 3
+    }
+  }
+}
+```
+
+### Response at `--depth titles`
+
+```json
+{
+  "ok": true,
+  "data": {
+    "username": "jdoe",
+    "summary": { ... },
+    "open_issues": [
+      { "iid": 42, "title": "Fix auth", "attention_state": "needs_attention" }
+    ],
+    "open_mrs_authored": [
+      { "iid": 99, "title": "Refactor auth", "attention_state": "needs_attention" }
+    ],
+    "reviewing_mrs": []
+  }
+}
+```
+
+**Effort:** Low. The data is already available; just need to gate serialization by depth level.
+
+---
+
+## C. `--batch` flag for multi-entity detail (P1)
+
+**Problem:** After search/timeline, agents discover N entity IIDs and need detail on each. Currently N round trips.
+
+**Proposal:** Add `--batch` flag to `issues` and `mrs` detail mode.
+
+```bash
+# Before: 3 round trips
+lore -J issues 42 -p proj
+lore -J issues 55 -p proj
+lore -J issues 71 -p proj
+
+# After: 1 round trip
+lore -J issues --batch 42,55,71 -p proj
+```
+
+### Response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "results": [
+      { "iid": 42, "title": "Fix auth", "state": "opened", ... },
+      { "iid": 55, "title": "Add SSO", "state": "opened", ... },
+      { "iid": 71, "title": "Token refresh", "state": "closed", ... }
+    ],
+    "errors": [
+      { "iid": 99, "error": "Not found" }
+    ]
+  }
+}
+```
+
+### Constraints
+
+- Max 20 IIDs per batch
+- Individual errors don't fail the batch (partial results returned)
+- Works with `--include` for maximum efficiency: `--batch 42,55 --include timeline`
+- Works with `--fields minimal` for token control
+
+**Effort:** Medium. Need to loop the existing detail handler and compose results.
+
+---
+
+## D. Composite `context` command (P2)
+
+**Problem:** Agents need full context on an entity but must learn `--include` syntax. A purpose-built command is more discoverable.
+
+**Proposal:** Add `context` command that returns detail + timeline + related in one call.
+
+```bash
+lore -J context issues 42 -p proj
+lore -J context mrs 99 -p proj
+```
+
+### Equivalent To
+
+```bash
+lore -J issues 42 -p proj --include timeline,related
+```
+
+But with optimized defaults:
+- Timeline: 20 most recent events, max 3 evidence notes
+- Related: top 5 entities
+- Discussions: truncated after 5 threads
+- Non-fatal: Ollama-dependent parts gracefully degrade
+
+### Response Shape
+
+Same as `issues <iid> --include timeline,related` but with the reduced defaults applied.
+
+### Relationship to `--include`
+
+`context` is sugar for the most common `--include` pattern. Both mechanisms can coexist:
+- `context` for the 80% case (agents wanting full entity understanding)
+- `--include` for custom combinations
+
+**Effort:** Medium. Thin wrapper around detail + include pipeline.
+
+---
+
+## E. `--max-tokens` response budget (P3)
+
+**Problem:** Response sizes vary wildly (100 to 8000 tokens). Agents can't predict cost in advance.
+
+**Proposal:** Let agents cap response size. Server truncates to fit.
+
+```bash
+lore -J me --max-tokens 500
+lore -J timeline "feature" --max-tokens 1000
+lore -J context issues 42 --max-tokens 2000
+```
+
+### Truncation Strategy (priority order)
+
+1. Apply `--fields minimal` if not already set
+2. Reduce array lengths (newest/highest-score items survive)
+3. Truncate string fields (descriptions, snippets) to 200 chars
+4. Omit null/empty fields
+5. Drop included sub-queries (if using `--include`)
+
+### Meta Notice
+
+```json
+{
+  "meta": {
+    "elapsed_ms": 50,
+    "truncated": true,
+    "original_tokens": 3500,
+    "budget_tokens": 1000,
+    "dropped": ["_related", "discussions[5:]", "activity[10:]"]
+  }
+}
+```
+
+### Implementation Notes
+
+Token estimation: rough heuristic based on JSON character count / 4. Doesn't need to be exact — the goal is "roughly this size" not "exactly N tokens."
+
+**Effort:** High. Requires token estimation, progressive truncation logic, and tracking what was dropped.
+
+---
+
+## F. `--format tsv` for list commands (P3)
+
+**Problem:** JSON is verbose for tabular data. List commands return arrays of objects with repeated key names.
+
+**Proposal:** Add `--format tsv` for list commands.
+
+```bash
+lore -J issues --format tsv --fields iid,title,state -n 10
+```
+
+### Output
+
+```
+iid	title	state
+42	Fix auth	opened
+55	Add SSO	opened
+71	Token refresh	closed
+```
+
+### Token Savings
+
+| Command | JSON tokens | TSV tokens | Savings |
+|---|---|---|---|
+| `issues -n 50 --fields minimal` | ~800 | ~250 | **69%** |
+| `mrs -n 50 --fields minimal` | ~800 | ~250 | **69%** |
+| `who expert -n 10` | ~300 | ~100 | **67%** |
+| `notes -n 50 --fields minimal` | ~1000 | ~350 | **65%** |
+
+### Applicable Commands
+
+TSV works well for flat, tabular data:
+- `issues` (list), `mrs` (list), `notes` (list)
+- `who expert`, `who overlap`, `who reviews`
+- `count`
+
+TSV does NOT work for nested/complex data:
+- Detail views (discussions are nested)
+- Timeline (events have nested evidence)
+- Search (nested explain, labels arrays)
+- `me` (multiple sections)
+
+### Agent Parsing
+
+Most LLMs parse TSV naturally. Agents that need structured data can still use JSON.
+
+**Effort:** Medium. Tab-separated serialization for flat structs is straightforward. Need to handle escaping for body text containing tabs/newlines.
+
+---
+
+## Impact Summary
+
+| Optimization | Priority | Effort | Round-Trip Savings | Token Savings |
+|---|---|---|---|---|
+| `--include` | P0 | High | **50-75%** | Moderate |
+| `--depth` on `me` | P0 | Low | None | **60-80%** |
+| `--batch` | P1 | Medium | **N-1 per batch** | Moderate |
+| `context` command | P2 | Medium | **67-75%** | Moderate |
+| `--max-tokens` | P3 | High | None | **Variable** |
+| `--format tsv` | P3 | Medium | None | **65-69% on lists** |
+
+### Implementation Order
+
+1. **`--depth` on `me`** — lowest effort, high value, no risk
+2. **`--include` on `issues`/`mrs` detail** — highest impact, start with `timeline` include only
+3. **`--batch`** — eliminates N+1 pattern
+4. **`context` command** — sugar on top of `--include`
+5. **`--format tsv`** — nice-to-have, easy to add incrementally
+6. **`--max-tokens`** — complex, defer until demand is clear

docs/command-surface-analysis/09-appendices.md

@@ -0,0 +1,181 @@
+# Appendices
+
+---
+
+## A. Robot Output Envelope
+
+All robot-mode responses follow this structure:
+
+```json
+{
+  "ok": true,
+  "data": { /* command-specific */ },
+  "meta": { "elapsed_ms": 42 }
+}
+```
+
+Errors (to stderr):
+
+```json
+{
+  "error": {
+    "code": "CONFIG_NOT_FOUND",
+    "message": "Configuration file not found",
+    "suggestion": "Run 'lore init'",
+    "actions": ["lore init"]
+  }
+}
+```
+
+The `actions` array contains copy-paste shell commands for automated recovery. Omitted when empty.
+
+---
+
+## B. Exit Codes
+
+| Code | Meaning | Retryable |
+|---|---|---|
+| 0 | Success | N/A |
+| 1 | Internal error / not implemented | Maybe |
+| 2 | Usage error (invalid flags or arguments) | No (fix syntax) |
+| 3 | Config invalid | No (fix config) |
+| 4 | Token not set | No (set token) |
+| 5 | GitLab auth failed | Maybe (token expired?) |
+| 6 | Resource not found (HTTP 404) | No |
+| 7 | Rate limited | Yes (wait) |
+| 8 | Network error | Yes (retry) |
+| 9 | Database locked | Yes (wait) |
+| 10 | Database error | Maybe |
+| 11 | Migration failed | No (investigate) |
+| 12 | I/O error | Maybe |
+| 13 | Transform error | No (bug) |
+| 14 | Ollama unavailable | Yes (start Ollama) |
+| 15 | Ollama model not found | No (pull model) |
+| 16 | Embedding failed | Yes (retry) |
+| 17 | Not found (entity does not exist) | No |
+| 18 | Ambiguous match (use `-p` to specify project) | No (be specific) |
+| 19 | Health check failed | Yes (fix issues first) |
+| 20 | Config not found | No (run init) |
+
+---
+
+## C. Field Selection Presets
+
+The `--fields` flag supports both presets and custom field lists:
+
+```bash
+lore -J issues --fields minimal              # Preset
+lore -J mrs --fields iid,title,state,draft   # Custom comma-separated
+```
+
+| Command | Minimal Preset Fields |
+|---|---|
+| `issues` (list) | `iid`, `title`, `state`, `updated_at_iso` |
+| `mrs` (list) | `iid`, `title`, `state`, `updated_at_iso` |
+| `notes` (list) | `id`, `author_username`, `body`, `created_at_iso` |
+| `search` | `document_id`, `title`, `source_type`, `score` |
+| `timeline` | `timestamp`, `type`, `entity_iid`, `detail` |
+| `who expert` | `username`, `score` |
+| `who workload` | `iid`, `title`, `state` |
+| `who reviews` | `name`, `count`, `percentage` |
+| `who active` | `entity_type`, `iid`, `title`, `participants` |
+| `who overlap` | `username`, `touch_count` |
+| `me` (items) | `iid`, `title`, `attention_state`, `updated_at_iso` |
+| `me` (activity) | `timestamp_iso`, `event_type`, `entity_iid`, `actor` |
+
+---
+
+## D. Configuration Precedence
+
+1. CLI flags (highest priority)
+2. Environment variables (`LORE_ROBOT`, `GITLAB_TOKEN`, `LORE_CONFIG_PATH`)
+3. Config file (`~/.config/lore/config.json`)
+4. Built-in defaults (lowest priority)
+
+---
+
+## E. Time Parsing
+
+All commands accepting `--since`, `--until`, `--as-of` support:
+
+| Format | Example | Meaning |
+|---|---|---|
+| Relative days | `7d` | 7 days ago |
+| Relative weeks | `2w` | 2 weeks ago |
+| Relative months | `1m`, `6m` | 1/6 months ago |
+| Absolute date | `2026-01-15` | Specific date |
+
+Internally converted to Unix milliseconds for DB queries.
+
+---
+
+## F. Database Schema (28 migrations)
+
+### Primary Entity Tables
+
+| Table | Key Columns | Notes |
+|---|---|---|
+| `projects` | `gitlab_project_id`, `path_with_namespace`, `web_url` | No `name` or `last_seen_at` |
+| `issues` | `iid`, `title`, `state`, `author_username`, 5 status columns | Status columns nullable (migration 021) |
+| `merge_requests` | `iid`, `title`, `state`, `draft`, `source_branch`, `target_branch` | `last_seen_at INTEGER NOT NULL` |
+| `discussions` | `gitlab_discussion_id` (text), `issue_id`/`merge_request_id` | One FK must be set |
+| `notes` | `gitlab_id`, `author_username`, `body`, DiffNote position columns | `type` column for DiffNote/DiscussionNote |
+
+### Relationship Tables
+
+| Table | Purpose |
+|---|---|
+| `issue_labels`, `mr_labels` | Label junction (DELETE+INSERT for stale removal) |
+| `issue_assignees`, `mr_assignees` | Assignee junction |
+| `mr_reviewers` | Reviewer junction |
+| `entity_references` | Cross-refs: closes, mentioned, related (with `source_method`) |
+| `mr_file_changes` | File diffs: old_path, new_path, change_type |
+
+### Event Tables
+
+| Table | Constraint |
+|---|---|
+| `resource_state_events` | CHECK: exactly one of issue_id/merge_request_id NOT NULL |
+| `resource_label_events` | Same CHECK constraint; `label_name` nullable (migration 012) |
+| `resource_milestone_events` | Same CHECK constraint; `milestone_title` nullable |
+
+### Document/Search Pipeline
+
+| Table | Purpose |
+|---|---|
+| `documents` | Unified searchable content (source_type: issue/merge_request/discussion) |
+| `documents_fts` | FTS5 virtual table for text search |
+| `documents_fts_docsize` | FTS5 shadow B-tree (19x faster for COUNT) |
+| `document_labels` | Fast label filtering (indexed exact-match) |
+| `document_paths` | File path association for DiffNote filtering |
+| `embeddings` | vec0 virtual table; rowid = document_id * 1000 + chunk_index |
+| `embedding_metadata` | Chunk provenance + staleness tracking (document_hash) |
+| `dirty_sources` | Documents needing regeneration (with backoff via next_attempt_at) |
+
+### Infrastructure
+
+| Table | Purpose |
+|---|---|
+| `sync_runs` | Sync history with metrics |
+| `sync_cursors` | Per-resource sync position (updated_at cursor + tie_breaker_id) |
+| `app_locks` | Crash-safe single-flight lock |
+| `raw_payloads` | Raw JSON storage for debugging |
+| `pending_discussion_fetches` | Dependent discussion fetch queue |
+| `pending_dependent_fetches` | Job queue for resource_events, mr_closes, mr_diffs |
+| `schema_version` | Migration tracking |
+
+---
+
+## G. Glossary
+
+| Term | Definition |
+|---|---|
+| **IID** | Issue/MR number within a project (not globally unique) |
+| **FTS5** | SQLite full-text search extension (BM25 ranking) |
+| **vec0** | SQLite extension for vector similarity search |
+| **RRF** | Reciprocal Rank Fusion — combines FTS and vector rankings |
+| **DiffNote** | Comment attached to a specific line in a merge request diff |
+| **Entity reference** | Cross-reference between issues/MRs (closes, mentioned, related) |
+| **Rename chain** | BFS traversal of mr_file_changes to follow file renames |
+| **Attention state** | Computed field on `me` items: needs_attention, not_started, stale, etc. |
+| **Surgical sync** | Fetching specific entities by IID instead of full incremental sync |

docs/lore-me-spec.md

@@ -0,0 +1,290 @@
+# `lore me` — Personal Work Dashboard
+
+## Overview
+
+A personal dashboard command that shows everything relevant to the configured user: open issues, authored MRs, MRs under review, and recent activity. Attention state is computed from GitLab interaction data (comments) with no local state tracking.
+
+## Command Interface
+
+```
+lore me                              # Full dashboard (default project or all)
+lore me --issues                     # Issues section only
+lore me --mrs                        # MRs section only (authored + reviewing)
+lore me --activity                   # Activity feed only
+lore me --issues --mrs               # Multiple sections (combinable)
+lore me --all                        # All synced projects (overrides default_project)
+lore me --since 2d                   # Activity window (default: 30d)
+lore me --project group/repo         # Scope to one project
+lore me --user jdoe                  # Override configured username
+```
+
+Standard global flags: `--robot`/`-J`, `--fields`, `--color`, `--icons`.
+
+---
+
+## Acceptance Criteria
+
+### AC-1: Configuration
+
+- **AC-1.1**: New optional field `gitlab.username` (string) in config.json
+- **AC-1.2**: Resolution order: `--user` CLI flag > `config.gitlab.username` > exit code 2 with actionable error message suggesting how to set it
+- **AC-1.3**: Username is case-sensitive (matches GitLab usernames exactly)
+
+### AC-2: Command Interface
+
+- **AC-2.1**: New command `lore me` — single command with flags (matches `who` pattern)
+- **AC-2.2**: Section filter flags: `--issues`, `--mrs`, `--activity` — combinable. Passing multiple shows those sections. No flags = full dashboard (all sections).
+- **AC-2.3**: `--since <duration>` controls activity feed window, default 30 days. Only affects the activity section; work item sections always show all open items regardless of `--since`.
+- **AC-2.4**: `--project <path>` scopes to a single project
+- **AC-2.5**: `--user <username>` overrides configured username
+- **AC-2.6**: `--all` flag shows all synced projects (overrides default_project)
+- **AC-2.7**: `--project` and `--all` are mutually exclusive — passing both is exit code 2
+- **AC-2.8**: Standard global flags: `--robot`/`-J`, `--fields`, `--color`, `--icons`
+
+### AC-3: "My Items" Definition
+
+- **AC-3.1**: Issues assigned to me (`issue_assignees.username`). Authorship alone does NOT qualify an issue.
+- **AC-3.2**: MRs authored by me (`merge_requests.author_username`)
+- **AC-3.3**: MRs where I'm a reviewer (`mr_reviewers.username`)
+- **AC-3.4**: Scope is **Assigned (issues) + Authored/Reviewing (MRs)** — no participation/mention expansion
+- **AC-3.5**: MR assignees (`mr_assignees`) are NOT used — in Pattern 1 workflows (author = assignee), this is redundant with authorship
+- **AC-3.6**: Activity feed uses CURRENT association only — if you've been unassigned from an issue, activity on it no longer appears. This keeps the query simple and the feed relevant.
+
+### AC-4: Attention State Model
+
+- **AC-4.1**: Computed per-item from synced GitLab data, no local state tracking
+- **AC-4.2**: Interaction signal: notes authored by the user (`notes.author_username = me` where `is_system = 0`)
+- **AC-4.3**: Future: award emoji will extend interaction signals (separate bead)
+- **AC-4.4**: States (evaluated in this order — first match wins):
+  1. `not_ready`: MR only — `draft=1` AND zero entries in `mr_reviewers`
+  2. `needs_attention`: Others' latest non-system note > user's latest non-system note
+  3. `stale`: Entity has at least one non-system note from someone, but the most recent note from anyone is older than 30 days. Items with ZERO notes are NOT stale — they're `not_started`.
+  4. `not_started`: User has zero non-system notes on this entity (regardless of whether others have commented)
+  5. `awaiting_response`: User's latest non-system note timestamp >= all others' latest non-system note timestamps (including when user is the only commenter)
+- **AC-4.5**: Applied to all item types (issues, authored MRs, reviewing MRs)
+
+### AC-5: Dashboard Sections
+
+**AC-5.1: Open Issues**
+- Source: `issue_assignees.username = me`, state = opened
+- Fields: project path, iid, title, status_name (work item status), attention state, relative time since updated
+- Sort: attention-first (needs_attention > not_started > awaiting_response > stale), then most recently updated within same state
+- No limit, no truncation — show all
+
+**AC-5.2: Open MRs — Authored**
+- Source: `merge_requests.author_username = me`, state = opened
+- Fields: project path, iid, title, draft indicator, detailed_merge_status, attention state, relative time
+- Sort: same as issues
+
+**AC-5.3: Open MRs — Reviewing**
+- Source: `mr_reviewers.username = me`, state = opened
+- Fields: project path, iid, title, MR author username, draft indicator, attention state, relative time
+- Sort: same as issues
+
+**AC-5.4: Activity Feed**
+- Sources (all within `--since` window, default 30d):
+  - Human comments (`notes.is_system = 0`) on my items
+  - State events (`resource_state_events`) on my items
+  - Label events (`resource_label_events`) on my items
+  - Milestone events (`resource_milestone_events`) on my items
+  - Assignment/reviewer system notes (see AC-12 for patterns) on my items
+- "My items" for the activity feed = items I'm CURRENTLY associated with per AC-3 (current assignment state, not historical)
+- Includes activity on items regardless of open/closed state
+- Own actions included but flagged (`is_own: true` in robot, `(you)` suffix + dimmed in human)
+- Sort: newest first (chronological descending)
+- No limit, no truncation — show all events
+
+**AC-5.5: Summary Header**
+- Counts: projects, open issues, authored MRs, reviewing MRs, needs_attention count
+- Attention legend (human mode): icon + label for each state
+
+### AC-6: Human Output — Visual Design
+
+**AC-6.1: Layout**
+- Section card style with `section_divider` headers
+- Legend at top explains attention icons
+- Two-line per item: main data on line 1, project path on line 2 (indented)
+- When scoped to single project (`--project`), suppress project path line (redundant)
+
+**AC-6.2: Attention Icons (three tiers)**
+
+| State | Nerd Font | Unicode | ASCII | Color |
+|-------|-----------|---------|-------|-------|
+| needs_attention | `\uf0f3` bell | `◆` | `[!]` | amber (warning) |
+| not_started | `\uf005` star | `★` | `[*]` | cyan (info) |
+| awaiting_response | `\uf017` clock | `◷` | `[~]` | dim (muted) |
+| stale | `\uf54c` skull | `☠` | `[x]` | dim (muted) |
+
+**AC-6.3: Color Vocabulary** (matches existing lore palette)
+- Issue refs (#N): cyan
+- MR refs (!N): purple
+- Usernames (@name): cyan
+- Opened state: green
+- Merged state: purple
+- Closed state: dim
+- Draft indicator: gray
+- Own actions: dimmed + `(you)` suffix
+- Timestamps: dim (relative time)
+
+**AC-6.4: Activity Event Badges**
+
+| Event | Nerd/Unicode (colored bg) | ASCII fallback |
+|-------|--------------------------|----------------|
+| note | cyan bg, dark text | `[note]` cyan text |
+| status | amber bg, dark text | `[status]` amber text |
+| label | purple bg, white text | `[label]` purple text |
+| assign | green bg, dark text | `[assign]` green text |
+| milestone | magenta bg, white text | `[milestone]` magenta text |
+
+Fallback: when background colors aren't available (ASCII mode), use colored text with brackets instead of background pills.
+
+**AC-6.5: Labels**
+- Human mode: not shown
+- Robot mode: included in JSON
+
+### AC-7: Robot Output
+
+- **AC-7.1**: Standard `{ok, data, meta}` envelope
+- **AC-7.2**: `data` contains: `username`, `since_iso`, `summary` (counts + `needs_attention_count`), `open_issues[]`, `open_mrs_authored[]`, `reviewing_mrs[]`, `activity[]`
+- **AC-7.3**: Each item includes: project, iid, title, state, attention_state (programmatic: `needs_attention`, `not_started`, `awaiting_response`, `stale`, `not_ready`), labels, updated_at_iso, web_url
+- **AC-7.4**: Issues include `status_name` (work item status)
+- **AC-7.5**: MRs include `draft`, `detailed_merge_status`, `author_username` (reviewing section)
+- **AC-7.6**: Activity items include: `timestamp_iso`, `event_type`, `entity_type`, `entity_iid`, `project`, `actor`, `is_own`, `summary`, `body_preview` (for notes, truncated to 200 chars)
+- **AC-7.7**: `--fields minimal` preset: `iid`, `title`, `attention_state`, `updated_at_iso` (work items); `timestamp_iso`, `event_type`, `entity_iid`, `actor` (activity)
+- **AC-7.8**: Metadata-only depth — agents drill into specific items with `timeline`, `issues`, `mrs` for full context
+- **AC-7.9**: No limits, no truncation on any array
+
+### AC-8: Cross-Project Behavior
+
+- **AC-8.1**: If `config.default_project` is set, scope to that project by default. If no default project, show all synced projects.
+- **AC-8.2**: `--all` flag overrides default project and shows all synced projects
+- **AC-8.3**: `--project` flag narrows to a specific project (supports fuzzy match like other commands)
+- **AC-8.4**: `--project` and `--all` are mutually exclusive (exit 2 if both passed)
+- **AC-8.5**: Project path shown per-item in both human and robot output (suppressed in human when single-project scoped per AC-6.1)
+
+### AC-9: Sort Order
+
+- **AC-9.1**: Work item sections: attention-first, then most recently updated
+- **AC-9.2**: Attention priority: `needs_attention` > `not_started` > `awaiting_response` > `stale` > `not_ready`
+- **AC-9.3**: Activity feed: chronological descending (newest first)
+
+### AC-10: Error Handling
+
+- **AC-10.1**: No username configured and no `--user` flag → exit 2 with suggestion
+- **AC-10.2**: No synced data → exit 17 with suggestion to run `lore sync`
+- **AC-10.3**: Username found but no matching items → empty sections with summary showing zeros
+- **AC-10.4**: `--project` and `--all` both passed → exit 2 with message
+
+### AC-11: Relationship to Existing Commands
+
+- **AC-11.1**: `who @username` remains for looking at anyone's workload
+- **AC-11.2**: `lore me` is the self-view with attention intelligence
+- **AC-11.3**: No deprecation of `who` — they serve different purposes
+
+### AC-12: New Assignments Detection
+
+- **AC-12.1**: Detect from system notes (`notes.is_system = 1`) matching these body patterns:
+  - `"assigned to @username"` — issue/MR assignment
+  - `"unassigned @username"` — removal (shown as `unassign` event type)
+  - `"requested review from @username"` — reviewer assignment (shown as `review_request` event type)
+- **AC-12.2**: These appear in the activity feed with appropriate event types
+- **AC-12.3**: Shows who performed the action (note author from the associated non-system context, or "system" if unavailable) and when (note created_at)
+- **AC-12.4**: Pattern matching is case-insensitive and matches username at word boundary
+
+---
+
+## Out of Scope (Follow-Up Work)
+
+- **Award emoji sync**: Extends attention signal with reaction timestamps. Requires new table + GitLab REST API integration. Note-level emoji sync has N+1 concern requiring smart batching.
+- **Participation/mention expansion**: Broadening "my items" beyond assigned+authored.
+- **Label filtering**: `--label` flag to scope dashboard by label.
+
+---
+
+## Design Notes
+
+### Why No High-Water Mark
+
+GitLab itself is the source of truth for "what I've engaged with." The attention state is computed by comparing the user's latest comment timestamp against others' latest comment timestamps on each item. No local cursor or mark is needed.
+
+### Why Comments-Only (For Now)
+
+Award emoji (reactions) are a valid "I've engaged" signal but aren't currently synced. The attention model is designed to incorporate emoji timestamps when available — adding them later requires no model changes.
+
+### Why MR Assignees Are Excluded
+
+GitLab MR workflows have three role fields: Author, Assignee, and Reviewer. In Pattern 1 workflows (the most common post-2020), the author assigns themselves — making assignee redundant with authorship. The Reviewing section uses `mr_reviewers` as the review signal.
+
+### Attention State Evaluation Order
+
+States are evaluated in priority order (first match wins):
+
+```
+1. not_ready    — MR-only: draft=1 AND no reviewers
+2. needs_attention — others commented after me
+3. stale        — had activity, but nothing in 30d (NOT for zero-comment items)
+4. not_started  — I have zero comments (may or may not have others' comments)
+5. awaiting_response — I commented last (or I'm the only commenter)
+```
+
+Edge cases:
+- Zero comments from anyone → `not_started` (NOT stale)
+- Only my comments, none from others → `awaiting_response`
+- Only others' comments, none from me → `not_started` (I haven't engaged)
+  - Wait: this conflicts with `needs_attention` (step 2). If others have commented and I haven't, then others' latest > my latest (NULL). This should be `needs_attention`, not `not_started`.
+
+Corrected logic:
+- `needs_attention` takes priority over `not_started` when others HAVE commented but I haven't. The distinction: `not_started` only applies when NOBODY has commented.
+
+```
+1. not_ready         — MR-only: draft=1 AND no reviewers
+2. needs_attention   — others have non-system notes AND (I have none OR others' latest > my latest)
+3. stale             — latest note from anyone is older than 30 days
+4. awaiting_response — my latest >= others' latest (I'm caught up)
+5. not_started       — zero non-system notes from anyone
+```
+
+### Attention State Computation (SQL Sketch)
+
+```sql
+WITH my_latest AS (
+    SELECT d.issue_id, d.merge_request_id, MAX(n.created_at) AS ts
+    FROM notes n
+    JOIN discussions d ON n.discussion_id = d.id
+    WHERE n.author_username = ?me AND n.is_system = 0
+    GROUP BY d.issue_id, d.merge_request_id
+),
+others_latest AS (
+    SELECT d.issue_id, d.merge_request_id, MAX(n.created_at) AS ts
+    FROM notes n
+    JOIN discussions d ON n.discussion_id = d.id
+    WHERE n.author_username != ?me AND n.is_system = 0
+    GROUP BY d.issue_id, d.merge_request_id
+),
+any_latest AS (
+    SELECT d.issue_id, d.merge_request_id, MAX(n.created_at) AS ts
+    FROM notes n
+    JOIN discussions d ON n.discussion_id = d.id
+    WHERE n.is_system = 0
+    GROUP BY d.issue_id, d.merge_request_id
+)
+SELECT
+    CASE
+        -- MR-only: draft with no reviewers
+        WHEN entity_type = 'mr' AND draft = 1
+             AND NOT EXISTS (SELECT 1 FROM mr_reviewers WHERE merge_request_id = entity_id)
+            THEN 'not_ready'
+        -- Others commented and I haven't caught up (or never engaged)
+        WHEN others.ts IS NOT NULL AND (my.ts IS NULL OR others.ts > my.ts)
+            THEN 'needs_attention'
+        -- Had activity but gone quiet for 30d
+        WHEN any.ts IS NOT NULL AND any.ts < ?now_minus_30d
+            THEN 'stale'
+        -- I've responded and I'm caught up
+        WHEN my.ts IS NOT NULL AND my.ts >= COALESCE(others.ts, 0)
+            THEN 'awaiting_response'
+        -- Nobody has commented at all
+        ELSE 'not_started'
+    END AS attention_state
+FROM ...
+```

docs/plan-expose-discussion-ids.feedback-3.md

@@ -1,5 +1,5 @@
 1. **Make `gitlab_note_id` explicit in all note-level payloads without breaking existing consumers**
-Rationale: Your Bridge Contract already requires `gitlab_note_id`, but current plan keeps `gitlab_id` only in `notes` list while adding `gitlab_note_id` only in `show`. That forces agents to special-case commands. Add `gitlab_note_id` as an alias field everywhere note-level data appears, while keeping `gitlab_id` for compatibility.
+Rationale: Your Bridge Contract already requires `gitlab_note_id`, but current plan keeps `gitlab_id` only in `notes` list while adding `gitlab_note_id` only in detail views. That forces agents to special-case commands. Add `gitlab_note_id` as an alias field everywhere note-level data appears, while keeping `gitlab_id` for compatibility.
 
 ```diff
 @@ Bridge Contract (Cross-Cutting)

docs/plan-expose-discussion-ids.feedback-5.md

@@ -0,0 +1,140 @@
+Your iteration 4 plan is already strong. The highest-impact revisions are around query shape, transaction boundaries, and contract stability for agents.
+
+1. **Switch discussions query to a two-phase page-first architecture**
+Analysis: Current `ranked_notes` runs over every filtered discussion before `LIMIT`, which can explode on project-wide queries. A page-first plan keeps complexity proportional to `limit`, improves tail latency, and reduces memory churn.
+```diff
+@@ ## 3c. SQL Query
+-Core query uses a CTE + ranked-notes rollup (window function) to avoid per-row correlated
+-subqueries.
++Core query is split into two phases for scalability:
++1) `paged_discussions` applies filters/sort/LIMIT and returns only page IDs.
++2) Note rollups and optional `--include-notes` expansion run only for those page IDs.
++This bounds note scanning to visible results and stabilizes latency on large projects.
+ 
+-WITH filtered_discussions AS (
++WITH filtered_discussions AS (
+   ...
+ ),
+-ranked_notes AS (
++paged_discussions AS (
++    SELECT id
++    FROM filtered_discussions
++    ORDER BY COALESCE({sort_column}, 0) {order}, id {order}
++    LIMIT ?
++),
++ranked_notes AS (
+   ...
+-    WHERE n.discussion_id IN (SELECT id FROM filtered_discussions)
++    WHERE n.discussion_id IN (SELECT id FROM paged_discussions)
+ )
+```
+
+2. **Move snapshot transaction ownership to handlers (not query helpers)**
+Analysis: This avoids nested transaction edge cases, keeps function signatures clean, and guarantees one snapshot across count + page + include-notes + serialization metadata.
+```diff
+@@ ## Cross-cutting: snapshot consistency
+-Wrap `query_notes` and `query_discussions` in a deferred read transaction.
++Open one deferred read transaction in each handler (`handle_notes`, `handle_discussions`)
++and pass `&Transaction` into query helpers. Query helpers do not open/commit transactions.
++This guarantees a single snapshot across all subqueries and avoids nested tx pitfalls.
+ 
+-pub fn query_discussions(conn: &Connection, ...)
++pub fn query_discussions(tx: &rusqlite::Transaction<'_>, ...)
+```
+
+3. **Add immutable input filter `--project-id` across notes/discussions/show**
+Analysis: You already expose `gitlab_project_id` because paths are mutable; input should support the same immutable selector. This removes failure modes after project renames/transfers.
+```diff
+@@ ## 3a. CLI Args
++    /// Filter by immutable GitLab project ID
++    #[arg(long, help_heading = "Filters", conflicts_with = "project")]
++    pub project_id: Option<i64>,
+@@ ## Bridge Contract
++Input symmetry rule: commands that accept `--project` should also accept `--project-id`.
++If both are present, return usage error (exit code 2).
+```
+
+4. **Enforce bridge fields for nested notes in `discussions --include-notes`**
+Analysis: Current guardrail is entity-level; nested notes can still lose required IDs under aggressive filtering. This is a contract hole for write-bridging.
+```diff
+@@ ### Field Filtering Guardrail
+-In robot mode, `filter_fields` MUST force-include Bridge Contract fields...
++In robot mode, `filter_fields` MUST force-include Bridge Contract fields at all returned levels:
++- discussion row fields
++- nested note fields when `discussions --include-notes` is used
+ 
++const BRIDGE_FIELDS_DISCUSSION_NOTES: &[&str] = &[
++    "project_path", "gitlab_project_id", "noteable_type", "parent_iid",
++    "gitlab_discussion_id", "gitlab_note_id",
++];
+```
+
+5. **Make ambiguity preflight scope-aware and machine-actionable**
+Analysis: Current preflight checks only `gitlab_discussion_id`, which can produce false ambiguity when additional filters already narrow to one project. Also, agents need structured candidates, not only free-text.
+```diff
+@@ ### Ambiguity Guardrail
+-SELECT DISTINCT p.path_with_namespace
++SELECT DISTINCT p.path_with_namespace, p.gitlab_project_id
+ FROM discussions d
+ JOIN projects p ON p.id = d.project_id
+-WHERE d.gitlab_discussion_id = ?
++WHERE d.gitlab_discussion_id = ?
++  /* plus active scope filters: noteable_type, for_issue/for_mr, since/path when present */
+ LIMIT 3
+ 
+-Return LoreError::Ambiguous with message
++Return LoreError::Ambiguous with structured details:
++`{ code, message, candidates:[{project_path, gitlab_project_id}], suggestion }`
+```
+
+6. **Add `--contains` filter to `discussions`**
+Analysis: This is a high-utility agent workflow gap. Agents frequently need “find thread by text then reply”; forcing a separate `notes` search round-trip is unnecessary.
+```diff
+@@ ## 3a. CLI Args
++    /// Filter discussions whose notes contain text
++    #[arg(long, help_heading = "Filters")]
++    pub contains: Option<String>,
+@@ ## 3d. Filters struct
++    pub contains: Option<String>,
+@@ ## 3d. Where-clause construction
++- `path` -> EXISTS (...)
++- `path` -> EXISTS (...)
++- `contains` -> EXISTS (
++    SELECT 1 FROM notes n
++    WHERE n.discussion_id = d.id
++      AND n.body LIKE ?
++  )
+```
+
+7. **Promote two baseline indexes from “candidate” to “required”**
+Analysis: These are directly hit by new primary paths; waiting for post-merge profiling risks immediate perf cliffs in real usage.
+```diff
+@@ ## 3h. Query-plan validation
+-Candidate indexes (add only if EXPLAIN QUERY PLAN shows they're needed):
+-- discussions(project_id, gitlab_discussion_id)
+-- notes(discussion_id, created_at DESC, id DESC)
++Required baseline indexes for this feature:
++- discussions(project_id, gitlab_discussion_id)
++- notes(discussion_id, created_at DESC, id DESC)
++Keep other indexes conditional on EXPLAIN QUERY PLAN.
+```
+
+8. **Add schema versioning and remove contradictory rejected items**
+Analysis: `robot-docs` contract drift is a long-term agent risk; explicit schema versions let clients fail safely. Also, rejected items currently contradict active sections, which creates implementation ambiguity.
+```diff
+@@ ## 4. Fix Robot-Docs Response Schemas
+ "meta": {"elapsed_ms": "int", ...}
++"meta": {"elapsed_ms":"int", ..., "schema_version":"string"}
++
++Schema version policy:
++- bump minor on additive fields
++- bump major on removals/renames
++- expose per-command versions in `robot-docs`
+@@ ## Rejected Recommendations
+-- Add `gitlab_note_id` to show-command note detail structs ... rejected ...
+-- Add `gitlab_discussion_id` to show-command discussion detail structs ... rejected ...
+-- Add `gitlab_project_id` to show-command discussion detail structs ... rejected ...
++Remove stale rejected entries that conflict with accepted workstreams in this plan iteration.
+```
+
+If you want, I can produce a fully rewritten iteration 5 plan document that applies all of the above edits cleanly end-to-end.

docs/plan-expose-discussion-ids.md

@@ -2,7 +2,7 @@
 plan: true
 title: ""
 status: iterating
-iteration: 4
+iteration: 5
 target_iterations: 8
 beads_revision: 0
 related_plans: []
@@ -43,7 +43,7 @@ construct API calls without a separate project-ID lookup, even after path change
 **Back-compat rule**: Note payloads in the `notes` list command continue exposing `gitlab_id`
 for existing consumers, but **MUST also** expose `gitlab_note_id` with the same value. This
 ensures agents can use a single field name (`gitlab_note_id`) across all commands — `notes`,
-`show`, and `discussions --include-notes` — without special-casing by command.
+`issues <IID>`/`mrs <IID>`, and `discussions --include-notes` — without special-casing by command.
 
 This contract exists so agents can deterministically construct `glab api` write calls without
 cross-referencing multiple commands. Each workstream below must satisfy these fields in its
@@ -52,8 +52,9 @@ output.
 ### Field Filtering Guardrail
 
 In robot mode, `filter_fields` **MUST** force-include Bridge Contract fields even when the
-caller passes a narrower `--fields` list. This prevents agents from accidentally stripping
+caller passes a narrower `--fields` list. This applies at **all nesting levels**: both the
-the identifiers they need for write operations.
+top-level entity fields and nested sub-entities (e.g., notes inside `discussions --include-notes`).
+This prevents agents from accidentally stripping the identifiers they need for write operations.
 
 **Implementation**: Add a `BRIDGE_FIELDS` constant map per entity type. In `filter_fields()`,
 when operating in robot mode, union the caller's requested fields with the bridge set before
@@ -69,70 +70,127 @@ const BRIDGE_FIELDS_DISCUSSIONS: &[&str] = &[
     "project_path", "gitlab_project_id", "noteable_type", "parent_iid",
     "gitlab_discussion_id",
 ];
+// Applied to nested notes within discussions --include-notes
+const BRIDGE_FIELDS_DISCUSSION_NOTES: &[&str] = &[
+    "project_path", "gitlab_project_id", "noteable_type", "parent_iid",
+    "gitlab_discussion_id", "gitlab_note_id",
+];
 ```
 
 In `filter_fields`, when entity is `"notes"` or `"discussions"`, merge the bridge set into the
-requested fields before filtering the JSON value. This is a ~5-line change to the existing
+requested fields before filtering the JSON value. For `"discussions"`, also apply
-function.
+`BRIDGE_FIELDS_DISCUSSION_NOTES` to each element of the nested `notes` array. This is a ~10-line
+change to the existing function.
+
+### Snapshot Consistency (Cross-Cutting)
+
+Multi-query commands (`handle_notes`, `handle_discussions`) **MUST** execute all their queries
+within a single deferred read transaction. This guarantees snapshot consistency when a concurrent
+sync/ingest is modifying the database.
+
+**Transaction ownership lives in handlers, not query helpers.** Each handler opens one deferred
+read transaction and passes it to query helpers. Query helpers accept `&Connection` (which
+`Transaction` derefs to via `std::ops::Deref`) so they remain testable with plain connections
+in unit tests. This avoids nested transaction edge cases and guarantees a single snapshot across
+count + page + include-notes + serialization.
+
+```rust
+// In handle_notes / handle_discussions:
+let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Deferred)?;
+let result = query_notes(&tx, &filters, &config)?;
+// ... serialize ...
+tx.commit()?;  // read-only, but closes cleanly
+```
+
+Query helpers keep their `conn: &Connection` signature — `Transaction<'_>` implements
+`Deref<Target = Connection>`, so `&tx` coerces to `&Connection` at call sites.
 
 ### Ambiguity Guardrail
 
 When filtering by `gitlab_discussion_id` (on either `notes` or `discussions` commands) without
 `--project`, if the query matches discussions in multiple projects:
 - Return an `Ambiguous` error (exit code 18, matching existing convention)
-- Include matching project paths in the error message
+- Include matching project paths **and `gitlab_project_id`s** in a structured candidates list
 - Suggest retry with `--project <path>`
 
-**Implementation**: Run a **preflight distinct-project check** before the main list query
+**Implementation**: Run a **scope-aware preflight distinct-project check** before the main list
-executes its `LIMIT`. This is critical because a post-query check on the paginated result set
+query executes its `LIMIT`. The preflight applies active scope filters (noteable_type, since,
-can silently miss cross-project ambiguity when `LIMIT` truncates results to rows from a single
+for_issue/for_mr) alongside the discussion ID check, so it won't produce false ambiguity when
-project. The preflight query is cheap (hits the `gitlab_discussion_id` index, returns at most
+other filters already narrow to one project. This is critical because a post-query check on the
-a few rows) and eliminates non-deterministic write-targeting risk.
+paginated result set can silently miss cross-project ambiguity when `LIMIT` truncates results to
+rows from a single project. The preflight query is cheap (hits the `gitlab_discussion_id` index,
+returns at most a few rows) and eliminates non-deterministic write-targeting risk.
 
 ```sql
--- Preflight ambiguity check (runs before main query)
+-- Preflight ambiguity check (runs before main query, includes active scope filters)
-SELECT DISTINCT p.path_with_namespace
+SELECT DISTINCT p.path_with_namespace, p.gitlab_project_id
 FROM discussions d
 JOIN projects p ON p.id = d.project_id
 WHERE d.gitlab_discussion_id = ?
+  -- scope filters applied dynamically:
+  -- AND d.noteable_type = ? (when --noteable-type present)
+  -- AND d.merge_request_id = (SELECT ...) (when --for-mr present)
+  -- AND d.issue_id = (SELECT ...) (when --for-issue present)
 LIMIT 3
 ```
 
-If more than one project is found, return `LoreError::Ambiguous` (exit code 18) with the
+If more than one project is found, return `LoreError::Ambiguous` (exit code 18) with structured
-distinct project paths and suggestion to retry with `--project <path>`.
+candidates for machine consumption:
 
 ```rust
 // In query_notes / query_discussions, before executing the main query:
 if let Some(ref disc_id) = filters.gitlab_discussion_id {
     if filters.project.is_none() {
-        let distinct_projects: Vec<String> = conn
+        let candidates: Vec<(String, i64)> = conn
             .prepare(
-                "SELECT DISTINCT p.path_with_namespace \
+                "SELECT DISTINCT p.path_with_namespace, p.gitlab_project_id \
                  FROM discussions d \
                  JOIN projects p ON p.id = d.project_id \
                  WHERE d.gitlab_discussion_id = ? \
                  LIMIT 3"
+                // Note: add scope filter clauses dynamically
             )?
-            .query_map([disc_id], |row| row.get(0))?
+            .query_map([disc_id], |row| Ok((row.get(0)?, row.get(1)?)))?
             .collect::<std::result::Result<Vec<_>, _>>()?;
 
-        if distinct_projects.len() > 1 {
+        if candidates.len() > 1 {
             return Err(LoreError::Ambiguous {
                 message: format!(
-                    "Discussion ID matches {} projects: {}. Use --project to disambiguate.",
+                    "Discussion ID matches {} projects. Use --project to disambiguate.",
-                    distinct_projects.len(),
+                    candidates.len(),
-                    distinct_projects.join(", ")
                 ),
+                candidates: candidates.into_iter()
+                    .map(|(path, id)| AmbiguousCandidate { project_path: path, gitlab_project_id: id })
+                    .collect(),
             });
         }
     }
 }
 ```
 
+In robot mode, the error serializes as:
+```json
+{
+  "error": {
+    "code": "AMBIGUOUS",
+    "message": "Discussion ID matches 2 projects. Use --project to disambiguate.",
+    "candidates": [
+      {"project_path": "group/repo-a", "gitlab_project_id": 42},
+      {"project_path": "group/repo-b", "gitlab_project_id": 99}
+    ],
+    "suggestion": "lore -J discussions --gitlab-discussion-id <id> --project <path>",
+    "actions": ["lore -J discussions --gitlab-discussion-id <id> --project group/repo-a"]
+  }
+}
+```
+
+This gives agents machine-actionable candidates: they can pick a project and retry immediately
+without parsing free-text error messages.
+
 #### 1h. Wrap `query_notes` in a read transaction
 
-Wrap the count query and page query in a deferred read transaction per the Snapshot Consistency
+Per the Snapshot Consistency cross-cutting requirement, `handle_notes` opens a deferred read
-cross-cutting requirement. See the Bridge Contract section for the pattern.
+transaction and passes it to `query_notes`. See the Snapshot Consistency section for the pattern.
 
 ### Tests
 
@@ -337,6 +395,7 @@ fn notes_ambiguous_gitlab_discussion_id_across_projects() {
     // (this can happen since IDs are per-project)
     // Filter by gitlab_discussion_id without --project
     // Assert LoreError::Ambiguous is returned with both project paths
+    // Assert candidates include gitlab_project_id for machine consumption
 }
 ```
 
@@ -352,6 +411,19 @@ fn notes_ambiguity_preflight_not_defeated_by_limit() {
 }
 ```
 
+#### Test 8: Ambiguity preflight respects scope filters (no false positives)
+
+```rust
+#[test]
+fn notes_ambiguity_preflight_respects_scope_filters() {
+    let conn = create_test_db();
+    // Insert 2 projects, each with a discussion sharing the same gitlab_discussion_id
+    // But one is Issue-type and the other MergeRequest-type
+    // Filter by gitlab_discussion_id + --noteable-type MergeRequest (narrows to 1 project)
+    // Assert NO ambiguity error — scope filters disambiguate
+}
+```
+
 ---
 
 ## 2. Add `gitlab_discussion_id` to Show Command Discussion Groups
@@ -644,6 +716,9 @@ lore -J discussions --gitlab-discussion-id 6a9c1750b37d
 
 # List unresolved threads with latest 2 notes inline (fewer round-trips)
 lore -J discussions --for-mr 99 --resolution unresolved --include-notes 2
+
+# Find discussions containing specific text
+lore -J discussions --for-mr 99 --contains "prefer the approach"
 ```
 
 ### Response Schema
@@ -801,6 +876,10 @@ pub struct DiscussionsArgs {
     #[arg(long, value_enum, help_heading = "Filters")]
     pub noteable_type: Option<NoteableTypeFilter>,
 
+    /// Filter discussions whose notes contain text (case-insensitive LIKE match)
+    #[arg(long, help_heading = "Filters")]
+    pub contains: Option<String>,
+
     /// Include up to N latest notes per discussion (0 = none, default; clamped to 20)
     #[arg(long, default_value = "0", help_heading = "Output")]
     pub include_notes: usize,
@@ -925,7 +1004,7 @@ The `included_note_count` is set to `notes.len()` and `has_more_notes` is set to
 `note_count > included_note_count` during the JSON conversion, providing per-discussion
 truncation signals.
 
-#### 3c. SQL Query
+#### 3c. SQL Query — Two-Phase Page-First Architecture
 
 **File**: `src/cli/commands/list.rs`
 
@@ -935,21 +1014,29 @@ pub fn query_discussions(
     filters: &DiscussionListFilters,
     config: &Config,
 ) -> Result<DiscussionListResult> {
-    // Wrap all queries in a deferred read transaction for snapshot consistency
+    // NOTE: Transaction is managed by the handler (handle_discussions).
-    let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Deferred)?;
+    // This function receives &Connection (which Transaction derefs to via `std::ops::Deref`).
 
     // Preflight ambiguity check (if gitlab_discussion_id without project)
     // ... see Ambiguity Guardrail section ...
 
-    // Main query + count query ...
+    // Phase 1: Filter + sort + LIMIT to get page IDs
-    // ... note expansion query (if include_notes > 0) ...
+    // Phase 2: Note rollups only for paged results
-
+    // Phase 3: Optional --include-notes expansion (separate query)
-    tx.commit()?;
+}
 ```
 
-Core query uses a CTE + ranked-notes rollup (window function) to avoid per-row correlated
+The query uses a **two-phase page-first architecture** for scalability:
-subqueries. The `ROW_NUMBER()` approach produces a single scan over the notes table, which
+
-is more predictable than repeated LIMIT 1 sub-selects at scale (200K+ discussions):
+1. **Phase 1** (`paged_discussions`): Apply all filters, sort, and LIMIT to produce just the
+   discussion IDs for the current page. This bounds the result set before any note scanning.
+2. **Phase 2** (`ranked_notes` + `note_rollup`): Run note aggregation only for the paged
+   discussion IDs. This ensures note scanning is proportional to `--limit`, not to the total
+   filtered discussion count.
+
+This architecture prevents the performance cliff that occurs on project-wide queries with
+thousands of discussions: instead of scanning notes for all filtered discussions (potentially
+200K+), we scan only for the 50 (or whatever `--limit` is) that will actually be returned.
 
 ```sql
 WITH filtered_discussions AS (
@@ -961,6 +1048,14 @@ WITH filtered_discussions AS (
     JOIN projects p ON d.project_id = p.id
     {where_sql}
 ),
+-- Phase 1: Page-first — apply sort + LIMIT before note scanning
+paged_discussions AS (
+    SELECT id
+    FROM filtered_discussions
+    ORDER BY COALESCE({sort_column}, 0) {order}, id {order}
+    LIMIT ?
+),
+-- Phase 2: Note rollups only for paged results
 ranked_notes AS (
     SELECT
         n.discussion_id,
@@ -980,7 +1075,7 @@ ranked_notes AS (
                      n.created_at, n.id
         ) AS rn_first_position
     FROM notes n
-    WHERE n.discussion_id IN (SELECT id FROM filtered_discussions)
+    WHERE n.discussion_id IN (SELECT id FROM paged_discussions)
 ),
 note_rollup AS (
     SELECT
@@ -1012,12 +1107,12 @@ SELECT
     nr.position_new_path,
     nr.position_new_line
 FROM filtered_discussions fd
+JOIN paged_discussions pd ON fd.id = pd.id
 JOIN projects p ON fd.project_id = p.id
 LEFT JOIN issues i ON fd.issue_id = i.id
 LEFT JOIN merge_requests m ON fd.merge_request_id = m.id
 LEFT JOIN note_rollup nr ON nr.discussion_id = fd.id
 ORDER BY COALESCE({sort_column}, 0) {order}, fd.id {order}
-LIMIT ?
 ```
 
 **Dual window function rationale**: The `ranked_notes` CTE uses two separate `ROW_NUMBER()`
@@ -1028,12 +1123,11 @@ displacing the first human author/body, and prevents a non-positioned note from
 the file location. The `MAX(CASE WHEN rn_xxx = 1 ...)` pattern extracts the correct value
 from each independently-ranked sequence.
 
-**Performance rationale**: The CTE pre-filters discussions before joining notes. The
+**Page-first scalability rationale**: The `paged_discussions` CTE applies LIMIT before note
-`ranked_notes` CTE uses `ROW_NUMBER()` (a single pass over the notes index) instead of
+scanning. For MR-scoped queries (50-200 discussions) the performance is equivalent to the
-correlated `(SELECT ... LIMIT 1)` sub-selects per discussion. For MR-scoped queries
+non-paged approach. For project-wide scans with thousands of discussions, the page-first
-(50-200 discussions) the performance is equivalent. For project-wide scans with thousands
+architecture avoids scanning notes for discussions that won't appear in the result, keeping
-of discussions, the window function approach avoids repeated index probes and produces a
+latency proportional to `--limit` rather than to the total filtered count.
-more predictable query plan.
 
 **Note on ordering**: The `COALESCE({sort_column}, 0)` with tiebreaker `fd.id` ensures
 deterministic ordering even when timestamps are NULL (partial sync states). The `id`
@@ -1042,6 +1136,10 @@ tiebreaker is cheap (primary key) and prevents unstable sort output.
 **Note on SQLite FILTER syntax**: SQLite does not support `COUNT(*) FILTER (WHERE ...)`.
 Use `SUM(CASE WHEN ... THEN 1 ELSE 0 END)` instead (as shown above).
 
+**Count query**: The total_count query runs separately against `filtered_discussions` (without
+the LIMIT) using `SELECT COUNT(*) FROM filtered_discussions`. This is needed for `has_more`
+metadata. The count uses the same filter CTEs but omits notes entirely.
+
 #### 3c-ii. Note expansion query (--include-notes)
 
 When `include_notes > 0`, after the main discussion query, run a **single batched query**
@@ -1103,6 +1201,7 @@ pub struct DiscussionListFilters {
     pub since: Option<String>,
     pub path: Option<String>,
     pub noteable_type: Option<NoteableTypeFilter>,
+    pub contains: Option<String>,
     pub sort: DiscussionSortField,
     pub order: SortDirection,
     pub include_notes: usize,
@@ -1117,6 +1216,7 @@ Where-clause construction uses `match` on typed enums — never raw string inter
 - `since` → `d.first_note_at >= ?` (using `parse_since()`)
 - `path` → `EXISTS (SELECT 1 FROM notes n WHERE n.discussion_id = d.id AND n.position_new_path LIKE ?)`
 - `noteable_type` → match: `Issue` → `d.noteable_type = 'Issue'`, `MergeRequest` → `d.noteable_type = 'MergeRequest'`
+- `contains` → `EXISTS (SELECT 1 FROM notes n WHERE n.discussion_id = d.id AND n.body LIKE '%' || ? || '%')`
 
 #### 3e. Handler wiring
 
@@ -1128,7 +1228,7 @@ Add match arm:
 Some(Commands::Discussions(args)) => handle_discussions(cli.config.as_deref(), args, robot_mode),
 ```
 
-Handler function:
+Handler function (with transaction ownership):
 
 ```rust
 fn handle_discussions(
@@ -1143,6 +1243,10 @@ fn handle_discussions(
 
     let effective_limit = args.limit.min(500);
     let effective_include_notes = args.include_notes.min(20);
+
+    // Snapshot consistency: one transaction across all queries
+    let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Deferred)?;
+
     let filters = DiscussionListFilters {
         limit: effective_limit,
         project: args.project,
@@ -1153,12 +1257,15 @@ fn handle_discussions(
         since: args.since,
         path: args.path,
         noteable_type: args.noteable_type,
+        contains: args.contains,
         sort: args.sort,
         order: args.order,
         include_notes: effective_include_notes,
     };
 
-    let result = query_discussions(&conn, &filters, &config)?;
+    let result = query_discussions(&tx, &filters, &config)?;
+
+    tx.commit()?;  // read-only, but closes cleanly
 
     let format = if robot_mode && args.format == "table" {
         "json"
@@ -1247,7 +1354,7 @@ CSV view: all fields, following same pattern as `print_list_notes_csv`.
     .collect(),
 ```
 
-#### 3h. Query-plan validation
+#### 3h. Query-plan validation and indexes
 
 Before merging the discussions command, capture `EXPLAIN QUERY PLAN` output for the three
 primary query patterns:
@@ -1255,17 +1362,26 @@ primary query patterns:
 - `--project <path> --since 7d --sort last-note`
 - `--gitlab-discussion-id <id>`
 
-If plans show table scans on `notes` or `discussions` for these patterns, add targeted indexes
+**Required baseline index** (directly hit by `--include-notes` expansion, which runs a
-to the `MIGRATIONS` array in `src/core/db.rs`:
+`ROW_NUMBER() OVER (PARTITION BY discussion_id ORDER BY created_at DESC, id DESC)` window
+on the notes table):
 
-**Candidate indexes** (add only if EXPLAIN QUERY PLAN shows they're needed):
+```sql
+CREATE INDEX IF NOT EXISTS idx_notes_discussion_created_desc
+ON notes(discussion_id, created_at DESC, id DESC);
+```
+
+This index is non-negotiable because the include-notes expansion query's performance is
+directly proportional to how efficiently it can scan notes per discussion. Without it, SQLite
+falls back to a full table scan of the 282K-row notes table for each batch.
+
+**Conditional indexes** (add only if EXPLAIN QUERY PLAN shows they're needed):
 - `discussions(project_id, gitlab_discussion_id)` — for ambiguity preflight + direct ID lookup
 - `discussions(merge_request_id, last_note_at, id)` — for MR-scoped + sorted queries
-- `notes(discussion_id, created_at DESC, id DESC)` — for `--include-notes` expansion
 - `notes(discussion_id, is_system, created_at, id)` — for ranked_notes CTE ordering
 
-This is a measured approach: profile first, add indexes only where the query plan demands them.
+This is a measured approach: one required index for the critical new path, remaining indexes
-No speculative index creation.
+added only where the query plan demands them.
 
 ### Tests
 
@@ -1500,7 +1616,7 @@ fn discussions_ambiguous_gitlab_discussion_id_across_projects() {
     };
     let result = query_discussions(&conn, &filters, &Config::default());
     assert!(result.is_err());
-    // Error should be Ambiguous with both project paths
+    // Error should be Ambiguous with both project paths and gitlab_project_ids
 }
 ```
 
@@ -1579,6 +1695,99 @@ fn discussions_first_note_rollup_skips_system_notes() {
 }
 ```
 
+#### Test 15: --contains filter returns matching discussions
+
+```rust
+#[test]
+fn query_discussions_contains_filter() {
+    let conn = create_test_db();
+    insert_project(&conn, 1);
+    insert_mr(&conn, 1, 1, 99, "Test MR");
+    insert_discussion(&conn, 1, "disc-match", 1, None, Some(1), "MergeRequest");
+    insert_discussion(&conn, 2, "disc-nomatch", 1, None, Some(1), "MergeRequest");
+    insert_note_in_discussion(&conn, 1, 500, 1, 1, "alice", "I really do prefer this approach");
+    insert_note_in_discussion(&conn, 2, 501, 2, 1, "bob", "Looks good to me");
+
+    let filters = DiscussionListFilters {
+        contains: Some("really do prefer".to_string()),
+        ..DiscussionListFilters::default_for_mr(99)
+    };
+    let result = query_discussions(&conn, &filters, &Config::default()).unwrap();
+
+    assert_eq!(result.discussions.len(), 1);
+    assert_eq!(result.discussions[0].gitlab_discussion_id, "disc-match");
+}
+```
+
+#### Test 16: Nested note bridge fields survive --fields filtering in robot mode
+
+```rust
+#[test]
+fn discussions_nested_note_bridge_fields_forced_in_robot_mode() {
+    // When discussions --include-notes returns nested notes,
+    // bridge fields on nested notes must survive --fields filtering
+    let mut value = serde_json::json!({
+        "data": {
+            "discussions": [{
+                "gitlab_discussion_id": "abc",
+                "noteable_type": "MergeRequest",
+                "parent_iid": 99,
+                "project_path": "group/repo",
+                "gitlab_project_id": 42,
+                "note_count": 1,
+                "notes": [{
+                    "body": "test note",
+                    "project_path": "group/repo",
+                    "gitlab_project_id": 42,
+                    "noteable_type": "MergeRequest",
+                    "parent_iid": 99,
+                    "gitlab_discussion_id": "abc",
+                    "gitlab_note_id": 500
+                }]
+            }]
+        }
+    });
+
+    // Agent requests only "body" on notes — bridge fields must still appear
+    filter_fields_robot(
+        &mut value,
+        "discussions",
+        &["note_count".to_string()],
+    );
+
+    let note = &value["data"]["discussions"][0]["notes"][0];
+    assert!(note.get("gitlab_discussion_id").is_some());
+    assert!(note.get("gitlab_note_id").is_some());
+    assert!(note.get("gitlab_project_id").is_some());
+}
+```
+
+#### Test 17: Ambiguity preflight respects scope filters (no false positives)
+
+```rust
+#[test]
+fn discussions_ambiguity_preflight_respects_scope_filters() {
+    let conn = create_test_db();
+    insert_project(&conn, 1);  // "group/repo-a"
+    insert_project(&conn, 2);  // "group/repo-b"
+    // Same gitlab_discussion_id in both projects
+    // But different noteable_types
+    insert_discussion(&conn, 1, "shared-id", 1, Some(1), None, "Issue");
+    insert_discussion(&conn, 2, "shared-id", 2, None, Some(1), "MergeRequest");
+
+    // Filter by noteable_type narrows to one project — should NOT fire ambiguity
+    let filters = DiscussionListFilters {
+        gitlab_discussion_id: Some("shared-id".to_string()),
+        noteable_type: Some(NoteableTypeFilter::MergeRequest),
+        project: None,
+        ..DiscussionListFilters::default()
+    };
+    let result = query_discussions(&conn, &filters, &Config::default());
+    assert!(result.is_ok());
+    assert_eq!(result.unwrap().discussions.len(), 1);
+}
+```
+
 ---
 
 ## 4. Fix Robot-Docs Response Schemas
@@ -1629,6 +1838,7 @@ With:
         "--since <period>",
         "--path <filepath>",
         "--noteable-type <Issue|MergeRequest>",
+        "--contains <text>",
         "--include-notes <N>",
         "--sort <first-note|last-note>",
         "--order <asc|desc>",
@@ -1831,14 +2041,13 @@ Changes 1 and 2 can be done in parallel. Change 4 must come last since it docume
 final schema of all preceding changes.
 
 **Cross-cutting**: The Bridge Contract field guardrail (force-including bridge fields in robot
-mode) should be implemented as part of Change 1, since it modifies `filter_fields` in
+mode, including nested notes) should be implemented as part of Change 1, since it modifies
-`robot.rs` which all subsequent changes depend on. The `BRIDGE_FIELDS_*` constants are defined
+`filter_fields` in `robot.rs` which all subsequent changes depend on. The `BRIDGE_FIELDS_*`
-once and reused by Changes 3 and 4.
+constants are defined once and reused by Changes 3 and 4.
 
-**Cross-cutting**: The snapshot consistency pattern (deferred read transaction) should be
+**Cross-cutting**: The snapshot consistency pattern (deferred read transaction in handlers)
-implemented in Change 1 for `query_notes` and carried forward to Change 3 for
+should be implemented in Change 1 for `handle_notes` and carried forward to Change 3 for
-`query_discussions`. This is a one-line wrapper that provides correctness guarantees with
+`handle_discussions`. Transaction ownership lives in handlers; query helpers accept `&Connection`.
-zero performance cost.
 
 ---
 
@@ -1850,40 +2059,52 @@ After all changes:
    `gitlab_discussion_id`, `gitlab_note_id`, and `gitlab_project_id` in the response
 2. An agent can run `lore -J discussions --for-mr 3929 --resolution unresolved` to see all
    open threads with their IDs
-3. An agent can run `lore -J mrs 3929` and see `gitlab_discussion_id`, `resolvable`,
+3. An agent can run `lore -J discussions --for-mr 3929 --contains "prefer the approach"` to
+   find threads by text content without a separate `notes` round-trip
+4. An agent can run `lore -J mrs 3929` and see `gitlab_discussion_id`, `resolvable`,
    `resolved`, and `last_note_at_iso` on each discussion group, plus `gitlab_note_id` on
    each note within
-4. `lore robot-docs` lists actual field names for all commands
+5. `lore robot-docs` lists actual field names for all commands
-5. All existing tests still pass
+6. All existing tests still pass
-6. No clippy warnings (pedantic + nursery)
+7. No clippy warnings (pedantic + nursery)
-7. Robot-docs contract tests pass with field-set parity (not just string-contains), preventing
+8. Robot-docs contract tests pass with field-set parity (not just string-contains), preventing
    future schema drift in both directions
-8. Bridge Contract fields (`project_path`, `gitlab_project_id`, `noteable_type`, `parent_iid`,
+9. Bridge Contract fields (`project_path`, `gitlab_project_id`, `noteable_type`, `parent_iid`,
    `gitlab_discussion_id`, `gitlab_note_id`) are present in every applicable read payload
-9. Bridge Contract fields survive `--fields` filtering in robot mode (guardrail enforced)
+10. Bridge Contract fields survive `--fields` filtering in robot mode (guardrail enforced),
-10. `--gitlab-discussion-id` filter works on both `notes` and `discussions` commands
+    including nested notes within `discussions --include-notes`
-11. `--include-notes N` populates inline notes on `discussions` output via single batched query
+11. `--gitlab-discussion-id` filter works on both `notes` and `discussions` commands
-12. CLI-level contract integration tests verify bridge fields through the full handler path
+12. `--include-notes N` populates inline notes on `discussions` output via single batched query
-13. `gitlab_note_id` is available in notes list output (alongside `gitlab_id` for back-compat)
+13. CLI-level contract integration tests verify bridge fields through the full handler path
+14. `gitlab_note_id` is available in notes list output (alongside `gitlab_id` for back-compat)
     and in show detail notes, providing a uniform field name across all commands
-14. Ambiguity guardrail fires when `--gitlab-discussion-id` matches multiple projects without
+15. Ambiguity guardrail fires when `--gitlab-discussion-id` matches multiple projects without
     `--project` specified — **including when LIMIT would have hidden the ambiguity** (preflight
-    query runs before LIMIT)
+    query runs before LIMIT). Error includes structured candidates with `gitlab_project_id`
-15. Output guardrails clamp `--limit` to 500 and `--include-notes` to 20; `meta` reports
+    for machine consumption
+16. Ambiguity preflight is scope-aware: active filters (noteable_type, for_issue/for_mr) are
+    applied alongside the discussion ID check, preventing false ambiguity when scope already
+    narrows to one project
+17. Output guardrails clamp `--limit` to 500 and `--include-notes` to 20; `meta` reports
     effective values and `has_more` truncation flag
-16. Discussion and show queries use deterministic ordering (COALESCE + id tiebreaker) to
+18. Discussion and show queries use deterministic ordering (COALESCE + id tiebreaker) to
     prevent unstable output during partial sync states
-17. Per-discussion truncation signals (`included_note_count`, `has_more_notes`) are accurate
+19. Per-discussion truncation signals (`included_note_count`, `has_more_notes`) are accurate
     for `--include-notes` output
-18. Multi-query commands (`query_notes`, `query_discussions`) use deferred read transactions
+20. Multi-query handlers (`handle_notes`, `handle_discussions`) open deferred read transactions;
-    for snapshot consistency during concurrent ingest
+    query helpers accept `&Connection` for snapshot consistency and testability
-19. Discussion filters (`resolution`, `noteable_type`, `sort`, `order`) use typed enums
+21. Discussion filters (`resolution`, `noteable_type`, `sort`, `order`) use typed enums
     with match-to-SQL mapping — no raw string interpolation in query construction
-20. First-note rollup correctly handles discussions with leading system notes — `first_author`
+22. First-note rollup correctly handles discussions with leading system notes — `first_author`
     and `first_note_body_snippet` always reflect the first non-system note
-21. Query plans for primary discussion query patterns (`--for-mr`, `--project --since`,
+23. Query plans for primary discussion query patterns (`--for-mr`, `--project --since`,
     `--gitlab-discussion-id`) have been validated via EXPLAIN QUERY PLAN; targeted indexes
     added only where scans were observed
+24. The `notes(discussion_id, created_at DESC, id DESC)` index is present for `--include-notes`
+    expansion performance
+25. Discussion query uses page-first CTE architecture: note rollups scan only the paged result
+    set, not all filtered discussions, keeping latency proportional to `--limit`
+26. `--contains` filter on `discussions` returns only discussions with matching note text
 
 ---
 
@@ -1902,6 +2123,6 @@ After all changes:
 - **`--with-write-hints` flag for inline glab endpoint templates** — rejected because this couples lore's read surface to glab's API surface, violating the read/write split principle. The Bridge Contract gives agents the raw identifiers; constructing glab commands is the agent's responsibility. Adding endpoint templates would require lore to track glab API changes, creating an unnecessary maintenance burden.
 - **Show-command note ordering change (`ORDER BY COALESCE(position, ...), created_at, id`)** — rejected because show-command note ordering within a discussion thread is out of scope for this plan. The existing ordering works correctly for present data; the defensive COALESCE pattern is applied to discussion-level ordering where it matters for agent workflows.
 - **Query-plan validation as a separate numbered workstream** — rejected because it adds delivery overhead without proportional benefit. Query-plan validation is integrated into workstream 3 as a pre-merge validation step (section 3h), with candidate indexes listed but only added when EXPLAIN QUERY PLAN shows they're needed. This keeps the measured approach without inflating the workstream count.
-- **Add `gitlab_note_id` to show-command note detail structs** — rejected because show-command note detail structs already have `gitlab_id` (same value as `id`). The field is unambiguous and consistent with the Bridge Contract. Adding `gitlab_note_id` would create a duplicate and increase payload size without benefit.
+- **`--project-id` immutable input filter across notes/discussions/show** — rejected because this is scope creep touching every command and changing CLI ergonomics. Agents already get `gitlab_project_id` in output to construct API calls; the input-side concern (project renames breaking `--project`) is theoretical and hasn't been observed in practice. The `--project` flag already supports fuzzy matching which handles most rename scenarios. If real-world evidence surfaces, this can be added later without breaking changes.
-- **Add `gitlab_discussion_id` to show-command discussion detail structs** — rejected because show-command discussion detail structs already have `gitlab_discussion_id`. The field is unambiguous and consistent with the Bridge Contract. Adding `gitlab_discussion_id` would create a duplicate and increase payload size without benefit.
+- **Schema versioning in robot-docs (`schema_version` field + semver policy)** — rejected because this tool has zero external consumers beyond our own agents, and the contract tests (field-set parity assertions) catch drift at compile time. Schema versioning adds bureaucratic overhead (version bumps, compatibility matrices, deprecation policies) without proportional benefit for an internal tool in early development. If lore gains external consumers, this can be reconsidered.
-- **Add `gitlab_project_id` to show-command discussion detail structs** — rejected because show-command discussion detail structs already have `gitlab_project_id`. The field is unambiguous and consistent with the Bridge Contract. Adding `gitlab_project_id` would create a duplicate and increase payload size without benefit.
+- **Remove "stale" rejected items that "conflict" with active sections** — rejected because the prior entries about show-command structs were stale from iteration 2 and have been cleaned up independently. The rejected section is cumulative by design — it prevents future reviewers from re-proposing changes that have already been evaluated.

gitlore-sync-explorer.html

@@ -1,844 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Gitlore Sync Pipeline Explorer</title>
-<style>
-  :root {
-    --bg: #0d1117;
-    --bg-secondary: #161b22;
-    --bg-tertiary: #1c2129;
-    --border: #30363d;
-    --text: #c9d1d9;
-    --text-dim: #8b949e;
-    --text-bright: #f0f6fc;
-    --cyan: #58a6ff;
-    --green: #3fb950;
-    --amber: #d29922;
-    --red: #f85149;
-    --purple: #bc8cff;
-    --pink: #f778ba;
-    --cyan-dim: rgba(88,166,255,0.15);
-    --green-dim: rgba(63,185,80,0.15);
-    --amber-dim: rgba(210,153,34,0.15);
-    --red-dim: rgba(248,81,73,0.15);
-    --purple-dim: rgba(188,140,255,0.15);
-  }
-  * { margin: 0; padding: 0; box-sizing: border-box; }
-  body {
-    font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', 'JetBrains Mono', monospace;
-    background: var(--bg); color: var(--text);
-    display: flex; height: 100vh; overflow: hidden;
-  }
-  .sidebar {
-    width: 220px; min-width: 220px; background: var(--bg-secondary);
-    border-right: 1px solid var(--border); display: flex; flex-direction: column; padding: 16px 0;
-  }
-  .sidebar-title {
-    font-size: 11px; font-weight: 700; text-transform: uppercase;
-    letter-spacing: 1.2px; color: var(--text-dim); padding: 0 16px 12px;
-  }
-  .logo {
-    padding: 0 16px 20px; font-size: 15px; font-weight: 700; color: var(--cyan);
-    display: flex; align-items: center; gap: 8px;
-  }
-  .logo svg { width: 20px; height: 20px; }
-  .nav-item {
-    padding: 10px 16px; cursor: pointer; font-size: 13px; color: var(--text-dim);
-    transition: all 0.15s; border-left: 3px solid transparent;
-    display: flex; align-items: center; gap: 10px;
-  }
-  .nav-item:hover { background: var(--bg-tertiary); color: var(--text); }
-  .nav-item.active { background: var(--cyan-dim); color: var(--cyan); border-left-color: var(--cyan); }
-  .nav-dot { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; }
-  .main { flex: 1; display: flex; flex-direction: column; overflow: hidden; }
-  .header {
-    padding: 16px 24px; border-bottom: 1px solid var(--border);
-    display: flex; align-items: center; justify-content: space-between;
-  }
-  .header h1 { font-size: 16px; font-weight: 600; color: var(--text-bright); }
-  .header-badge {
-    font-size: 11px; padding: 3px 10px; border-radius: 12px;
-    background: var(--cyan-dim); color: var(--cyan);
-  }
-  .canvas-wrapper { flex: 1; overflow: auto; position: relative; }
-  .canvas { padding: 32px; min-height: 100%; }
-  .flow-container { display: none; }
-  .flow-container.active { display: block; }
-  .phase { margin-bottom: 32px; }
-  .phase-header { display: flex; align-items: center; gap: 12px; margin-bottom: 16px; }
-  .phase-number {
-    width: 28px; height: 28px; border-radius: 50%; display: flex; align-items: center;
-    justify-content: center; font-size: 13px; font-weight: 700; flex-shrink: 0;
-  }
-  .phase-title { font-size: 14px; font-weight: 600; color: var(--text-bright); }
-  .phase-subtitle { font-size: 11px; color: var(--text-dim); margin-left: 4px; font-weight: 400; }
-  .flow-row {
-    display: flex; align-items: stretch; gap: 0; flex-wrap: wrap;
-    margin-left: 14px; padding-left: 26px; border-left: 2px solid var(--border);
-  }
-  .flow-row:last-child { border-left-color: transparent; }
-  .node {
-    position: relative; padding: 12px 16px; border-radius: 8px;
-    border: 1px solid var(--border); background: var(--bg-secondary);
-    font-size: 12px; cursor: pointer; transition: all 0.2s;
-    min-width: 180px; max-width: 260px; margin: 4px 0;
-  }
-  .node:hover {
-    border-color: var(--cyan); transform: translateY(-1px);
-    box-shadow: 0 4px 12px rgba(0,0,0,0.3);
-  }
-  .node.selected {
-    border-color: var(--cyan);
-    box-shadow: 0 0 0 1px var(--cyan), 0 4px 16px rgba(88,166,255,0.15);
-  }
-  .node-title { font-weight: 600; font-size: 12px; margin-bottom: 4px; color: var(--text-bright); }
-  .node-desc { font-size: 11px; color: var(--text-dim); line-height: 1.5; }
-  .node.api { border-left: 3px solid var(--cyan); }
-  .node.transform { border-left: 3px solid var(--purple); }
-  .node.db { border-left: 3px solid var(--green); }
-  .node.decision { border-left: 3px solid var(--amber); }
-  .node.error { border-left: 3px solid var(--red); }
-  .node.queue { border-left: 3px solid var(--pink); }
-  .arrow {
-    display: flex; align-items: center; padding: 0 6px;
-    color: var(--text-dim); font-size: 16px; flex-shrink: 0;
-  }
-  .arrow-down {
-    display: flex; justify-content: center; padding: 4px 0;
-    color: var(--text-dim); font-size: 16px; margin-left: 14px;
-    padding-left: 26px; border-left: 2px solid var(--border);
-  }
-  .branch-container {
-    margin-left: 14px; padding-left: 26px;
-    border-left: 2px solid var(--border); padding-bottom: 8px;
-  }
-  .branch-row { display: flex; gap: 12px; margin: 8px 0; flex-wrap: wrap; }
-  .branch-label {
-    font-size: 11px; font-weight: 600; margin: 8px 0 4px;
-    display: flex; align-items: center; gap: 6px;
-  }
-  .branch-label.success { color: var(--green); }
-  .branch-label.error { color: var(--red); }
-  .branch-label.retry { color: var(--amber); }
-  .diff-badge {
-    display: inline-block; font-size: 10px; padding: 2px 6px;
-    border-radius: 4px; margin-top: 6px; font-weight: 600;
-  }
-  .diff-badge.changed { background: var(--amber-dim); color: var(--amber); }
-  .diff-badge.same { background: var(--green-dim); color: var(--green); }
-  .detail-panel {
-    position: fixed; right: 0; top: 0; bottom: 0; width: 380px;
-    background: var(--bg-secondary); border-left: 1px solid var(--border);
-    transform: translateX(100%); transition: transform 0.25s ease;
-    z-index: 100; display: flex; flex-direction: column; overflow: hidden;
-  }
-  .detail-panel.open { transform: translateX(0); }
-  .detail-header {
-    padding: 16px 20px; border-bottom: 1px solid var(--border);
-    display: flex; align-items: center; justify-content: space-between;
-  }
-  .detail-header h2 { font-size: 14px; font-weight: 600; color: var(--text-bright); }
-  .detail-close {
-    cursor: pointer; color: var(--text-dim); font-size: 18px;
-    background: none; border: none; padding: 4px 8px; border-radius: 4px;
-  }
-  .detail-close:hover { background: var(--bg-tertiary); color: var(--text); }
-  .detail-body { flex: 1; overflow-y: auto; padding: 20px; }
-  .detail-section { margin-bottom: 20px; }
-  .detail-section h3 {
-    font-size: 11px; text-transform: uppercase; letter-spacing: 0.8px;
-    color: var(--text-dim); margin-bottom: 8px;
-  }
-  .detail-section p { font-size: 12px; line-height: 1.7; color: var(--text); }
-  .sql-block {
-    background: var(--bg); border: 1px solid var(--border); border-radius: 6px;
-    padding: 12px; font-size: 11px; line-height: 1.6; color: var(--green);
-    overflow-x: auto; white-space: pre; margin-top: 8px;
-  }
-  .detail-tag {
-    display: inline-block; font-size: 10px; padding: 2px 8px;
-    border-radius: 10px; margin: 2px 4px 2px 0;
-  }
-  .detail-tag.file { background: var(--purple-dim); color: var(--purple); }
-  .detail-tag.type-api { background: var(--cyan-dim); color: var(--cyan); }
-  .detail-tag.type-db { background: var(--green-dim); color: var(--green); }
-  .detail-tag.type-transform { background: var(--purple-dim); color: var(--purple); }
-  .detail-tag.type-decision { background: var(--amber-dim); color: var(--amber); }
-  .detail-tag.type-error { background: var(--red-dim); color: var(--red); }
-  .detail-tag.type-queue { background: rgba(247,120,186,0.15); color: var(--pink); }
-  .watermark-panel { border-top: 1px solid var(--border); background: var(--bg-secondary); }
-  .watermark-toggle {
-    padding: 10px 24px; cursor: pointer; font-size: 12px; color: var(--text-dim);
-    display: flex; align-items: center; gap: 8px; user-select: none;
-  }
-  .watermark-toggle:hover { color: var(--text); }
-  .watermark-toggle .chevron { transition: transform 0.2s; font-size: 10px; }
-  .watermark-toggle .chevron.open { transform: rotate(180deg); }
-  .watermark-content { display: none; padding: 0 24px 16px; max-height: 260px; overflow-y: auto; }
-  .watermark-content.open { display: block; }
-  .wm-table { width: 100%; border-collapse: collapse; font-size: 11px; }
-  .wm-table th {
-    text-align: left; padding: 6px 12px; color: var(--text-dim); font-weight: 600;
-    border-bottom: 1px solid var(--border); font-size: 10px;
-    text-transform: uppercase; letter-spacing: 0.5px;
-  }
-  .wm-table td { padding: 6px 12px; border-bottom: 1px solid var(--border); color: var(--text); }
-  .wm-table td:first-child { color: var(--cyan); font-weight: 600; }
-  .wm-table td:nth-child(2) { color: var(--green); }
-  .overview-pipeline { display: flex; gap: 0; align-items: stretch; margin: 24px 0; flex-wrap: wrap; }
-  .overview-stage {
-    flex: 1; min-width: 200px; background: var(--bg-secondary);
-    border: 1px solid var(--border); border-radius: 10px; padding: 20px;
-    cursor: pointer; transition: all 0.2s;
-  }
-  .overview-stage:hover {
-    border-color: var(--cyan); transform: translateY(-2px);
-    box-shadow: 0 6px 20px rgba(0,0,0,0.3);
-  }
-  .overview-arrow { display: flex; align-items: center; padding: 0 8px; font-size: 20px; color: var(--text-dim); }
-  .stage-num { font-size: 10px; font-weight: 700; text-transform: uppercase; letter-spacing: 1px; margin-bottom: 8px; }
-  .stage-title { font-size: 15px; font-weight: 700; color: var(--text-bright); margin-bottom: 6px; }
-  .stage-desc { font-size: 11px; color: var(--text-dim); line-height: 1.6; }
-  .stage-detail {
-    margin-top: 12px; padding-top: 12px; border-top: 1px solid var(--border);
-    font-size: 11px; color: var(--text-dim); line-height: 1.6;
-  }
-  .stage-detail code {
-    color: var(--amber); background: var(--amber-dim); padding: 1px 5px;
-    border-radius: 3px; font-size: 10px;
-  }
-  .info-box {
-    background: var(--bg-tertiary); border: 1px solid var(--border);
-    border-radius: 8px; padding: 16px; margin: 16px 0; font-size: 12px; line-height: 1.7;
-  }
-  .info-box-title { font-weight: 600; color: var(--cyan); margin-bottom: 6px; display: flex; align-items: center; gap: 6px; }
-  .info-box ul { margin-left: 16px; color: var(--text-dim); }
-  .info-box li { margin: 4px 0; }
-  .info-box code {
-    color: var(--amber); background: var(--amber-dim);
-    padding: 1px 5px; border-radius: 3px; font-size: 11px;
-  }
-  .legend {
-    display: flex; gap: 16px; flex-wrap: wrap; margin-bottom: 24px;
-    padding: 12px 16px; background: var(--bg-secondary);
-    border: 1px solid var(--border); border-radius: 8px;
-  }
-  .legend-item { display: flex; align-items: center; gap: 6px; font-size: 11px; color: var(--text-dim); }
-  .legend-color { width: 12px; height: 3px; border-radius: 2px; }
-  ::-webkit-scrollbar { width: 8px; height: 8px; }
-  ::-webkit-scrollbar-track { background: transparent; }
-  ::-webkit-scrollbar-thumb { background: var(--border); border-radius: 4px; }
-  ::-webkit-scrollbar-thumb:hover { background: var(--text-dim); }
-</style>
-</head>
-<body>
-
-<div class="sidebar">
-  <div class="logo">
-    <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5">
-      <circle cx="10" cy="10" r="8"/><path d="M10 6v4l3 2"/>
-    </svg>
-    lore sync
-  </div>
-  <div class="sidebar-title">Entity Flows</div>
-  <div class="nav-item active" data-view="overview" onclick="switchView('overview')">
-    <div class="nav-dot" style="background:var(--cyan)"></div>Full Sync Overview
-  </div>
-  <div class="nav-item" data-view="issues" onclick="switchView('issues')">
-    <div class="nav-dot" style="background:var(--green)"></div>Issues
-  </div>
-  <div class="nav-item" data-view="mrs" onclick="switchView('mrs')">
-    <div class="nav-dot" style="background:var(--purple)"></div>Merge Requests
-  </div>
-  <div class="nav-item" data-view="docs" onclick="switchView('docs')">
-    <div class="nav-dot" style="background:var(--amber)"></div>Documents
-  </div>
-  <div class="nav-item" data-view="embed" onclick="switchView('embed')">
-    <div class="nav-dot" style="background:var(--pink)"></div>Embeddings
-  </div>
-</div>
-
-<div class="main">
-  <div class="header">
-    <h1 id="view-title">Full Sync Overview</h1>
-    <span class="header-badge" id="view-badge">4 stages</span>
-  </div>
-
-  <div class="canvas-wrapper"><div class="canvas">
-
-    <!-- OVERVIEW -->
-    <div class="flow-container active" id="view-overview">
-      <div class="overview-pipeline">
-        <div class="overview-stage" onclick="switchView('issues')">
-          <div class="stage-num" style="color:var(--green)">Stage 1</div>
-          <div class="stage-title">Ingest Issues</div>
-          <div class="stage-desc">Fetch issues + discussions + resource events from GitLab API</div>
-          <div class="stage-detail">Cursor-based incremental sync.<br>Sequential discussion fetch.<br>Queue-based resource events.</div>
-        </div>
-        <div class="overview-arrow">&rarr;</div>
-        <div class="overview-stage" onclick="switchView('mrs')">
-          <div class="stage-num" style="color:var(--purple)">Stage 2</div>
-          <div class="stage-title">Ingest MRs</div>
-          <div class="stage-desc">Fetch merge requests + discussions + resource events</div>
-          <div class="stage-detail">Page-based incremental sync.<br>Parallel prefetch discussions.<br>Queue-based resource events.</div>
-        </div>
-        <div class="overview-arrow">&rarr;</div>
-        <div class="overview-stage" onclick="switchView('docs')">
-          <div class="stage-num" style="color:var(--amber)">Stage 3</div>
-          <div class="stage-title">Generate Docs</div>
-          <div class="stage-desc">Regenerate searchable documents for changed entities</div>
-          <div class="stage-detail">Driven by <code>dirty_sources</code> table.<br>Triple-hash skip optimization.<br>FTS5 index auto-updated.</div>
-        </div>
-        <div class="overview-arrow">&rarr;</div>
-        <div class="overview-stage" onclick="switchView('embed')">
-          <div class="stage-num" style="color:var(--pink)">Stage 4</div>
-          <div class="stage-title">Embed</div>
-          <div class="stage-desc">Generate vector embeddings via Ollama for semantic search</div>
-          <div class="stage-detail">Hash-based change detection.<br>Chunked, batched API calls.<br><b>Non-fatal</b> &mdash; graceful if Ollama down.</div>
-        </div>
-      </div>
-      <div class="info-box">
-        <div class="info-box-title">Concurrency Model</div>
-        <ul>
-          <li>Stages 1 &amp; 2 process <b>projects concurrently</b> via <code>buffer_unordered(primary_concurrency)</code></li>
-          <li>Each project gets its own <b>SQLite connection</b>; rate limiter is <b>shared</b></li>
-          <li>Discussions: <b>sequential</b> (issues) or <b>batched parallel prefetch</b> (MRs)</li>
-          <li>Resource events use a <b>persistent job queue</b> with atomic claim + exponential backoff</li>
-        </ul>
-      </div>
-      <div class="info-box">
-        <div class="info-box-title">Sync Flags</div>
-        <ul>
-          <li><code>--full</code> &mdash; Resets all cursors &amp; watermarks, forces complete re-fetch</li>
-          <li><code>--no-docs</code> &mdash; Skips Stage 3 (document generation)</li>
-          <li><code>--no-embed</code> &mdash; Skips Stage 4 (embedding generation)</li>
-          <li><code>--force</code> &mdash; Overrides stale single-flight lock</li>
-          <li><code>--project &lt;path&gt;</code> &mdash; Sync only one project (fuzzy matching)</li>
-        </ul>
-      </div>
-      <div class="info-box">
-        <div class="info-box-title">Single-Flight Lock</div>
-        <ul>
-          <li>Table-based lock (<code>AppLock</code>) prevents concurrent syncs</li>
-          <li>Heartbeat keeps the lock alive; stale locks auto-detected</li>
-          <li>Use <code>--force</code> to override a stale lock</li>
-        </ul>
-      </div>
-    </div>
-
-    <!-- ISSUES -->
-    <div class="flow-container" id="view-issues">
-      <div class="legend">
-        <div class="legend-item"><div class="legend-color" style="background:var(--cyan)"></div>API Call</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--purple)"></div>Transform</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--green)"></div>Database</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--amber)"></div>Decision</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--red)"></div>Error Path</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--pink)"></div>Queue</div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:var(--cyan-dim);color:var(--cyan)">1</div>
-          <div class="phase-title">Fetch Issues <span class="phase-subtitle">Cursor-Based Incremental Sync</span></div>
-        </div>
-        <div class="flow-row">
-          <div class="node api" data-detail="issue-api-call"><div class="node-title">GitLab API Call</div><div class="node-desc">paginate_issues() with<br>updated_after = cursor - rewind</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node decision" data-detail="issue-cursor-filter"><div class="node-title">Cursor Filter</div><div class="node-desc">updated_at &gt; cursor_ts<br>OR tie_breaker check</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node transform" data-detail="issue-transform"><div class="node-title">transform_issue()</div><div class="node-desc">GitLab API shape &rarr;<br>local DB row shape</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node db" data-detail="issue-transaction"><div class="node-title">Transaction</div><div class="node-desc">store_payload &rarr; upsert &rarr;<br>mark_dirty &rarr; relink</div></div>
-        </div>
-        <div class="arrow-down">&darr;</div>
-        <div class="flow-row">
-          <div class="node db" data-detail="issue-cursor-update"><div class="node-title">Update Cursor</div><div class="node-desc">Every 100 issues + final<br>sync_cursors table</div></div>
-        </div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:var(--green-dim);color:var(--green)">2</div>
-          <div class="phase-title">Discussion Sync <span class="phase-subtitle">Sequential, Watermark-Based</span></div>
-        </div>
-        <div class="flow-row">
-          <div class="node db" data-detail="issue-disc-query"><div class="node-title">Query Stale Issues</div><div class="node-desc">updated_at &gt; COALESCE(<br>discussions_synced_for_<br>updated_at, 0)</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node api" data-detail="issue-disc-fetch"><div class="node-title">Paginate Discussions</div><div class="node-desc">Sequential per issue<br>paginate_issue_discussions()</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node transform" data-detail="issue-disc-transform"><div class="node-title">Transform</div><div class="node-desc">transform_discussion()<br>transform_notes()</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node db" data-detail="issue-disc-write"><div class="node-title">Write Discussion</div><div class="node-desc">store_payload &rarr; upsert<br>DELETE notes &rarr; INSERT notes</div></div>
-        </div>
-        <div class="branch-container">
-          <div class="branch-label success">&#10003; On Success (all pages fetched)</div>
-          <div class="branch-row">
-            <div class="node db" data-detail="issue-disc-stale"><div class="node-title">Remove Stale</div><div class="node-desc">DELETE discussions not<br>seen in this fetch</div></div>
-            <div class="arrow">&rarr;</div>
-            <div class="node db" data-detail="issue-disc-watermark"><div class="node-title">Advance Watermark</div><div class="node-desc">discussions_synced_for_<br>updated_at = updated_at</div></div>
-          </div>
-          <div class="branch-label error">&#10007; On Pagination Error</div>
-          <div class="branch-row">
-            <div class="node error" data-detail="issue-disc-fail"><div class="node-title">Skip Stale Removal</div><div class="node-desc">Watermark NOT advanced<br>Will retry next sync</div></div>
-          </div>
-        </div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:rgba(247,120,186,0.15);color:var(--pink)">3</div>
-          <div class="phase-title">Resource Events <span class="phase-subtitle">Queue-Based, Concurrent Fetch</span></div>
-        </div>
-        <div class="flow-row">
-          <div class="node queue" data-detail="re-cleanup"><div class="node-title">Cleanup Obsolete</div><div class="node-desc">DELETE jobs where entity<br>watermark is current</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node queue" data-detail="re-enqueue"><div class="node-title">Enqueue Jobs</div><div class="node-desc">INSERT for entities where<br>updated_at &gt; watermark</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node queue" data-detail="re-claim"><div class="node-title">Claim Jobs</div><div class="node-desc">Atomic UPDATE...RETURNING<br>with lock acquisition</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node api" data-detail="re-fetch"><div class="node-title">Fetch Events</div><div class="node-desc">3 concurrent: state +<br>label + milestone</div></div>
-        </div>
-        <div class="branch-container">
-          <div class="branch-label success">&#10003; On Success</div>
-          <div class="branch-row">
-            <div class="node db" data-detail="re-store"><div class="node-title">Store Events</div><div class="node-desc">Transaction: upsert all<br>3 event types</div></div>
-            <div class="arrow">&rarr;</div>
-            <div class="node db" data-detail="re-complete"><div class="node-title">Complete + Watermark</div><div class="node-desc">DELETE job row<br>Advance watermark</div></div>
-          </div>
-          <div class="branch-label error">&#10007; Permanent Error (404 / 403)</div>
-          <div class="branch-row">
-            <div class="node error" data-detail="re-permanent"><div class="node-title">Skip Permanently</div><div class="node-desc">complete_job + advance<br>watermark (coalesced)</div></div>
-          </div>
-          <div class="branch-label retry">&#8635; Transient Error</div>
-          <div class="branch-row">
-            <div class="node error" data-detail="re-transient"><div class="node-title">Backoff Retry</div><div class="node-desc">fail_job: 30s x 2^(n-1)<br>capped at 480s</div></div>
-          </div>
-        </div>
-      </div>
-    </div>
-
-    <!-- MERGE REQUESTS -->
-    <div class="flow-container" id="view-mrs">
-      <div class="legend">
-        <div class="legend-item"><div class="legend-color" style="background:var(--cyan)"></div>API Call</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--purple)"></div>Transform</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--green)"></div>Database</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--amber)"></div>Diff from Issues</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--red)"></div>Error Path</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--pink)"></div>Queue</div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:var(--cyan-dim);color:var(--cyan)">1</div>
-          <div class="phase-title">Fetch MRs <span class="phase-subtitle">Page-Based Incremental Sync</span></div>
-        </div>
-        <div class="flow-row">
-          <div class="node api" data-detail="mr-api-call"><div class="node-title">GitLab API Call</div><div class="node-desc">fetch_merge_requests_page()<br>with cursor rewind</div><div class="diff-badge changed">Page-based, not streaming</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node decision" data-detail="mr-cursor-filter"><div class="node-title">Cursor Filter</div><div class="node-desc">Same logic as issues:<br>timestamp + tie-breaker</div><div class="diff-badge same">Same as issues</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node transform" data-detail="mr-transform"><div class="node-title">transform_merge_request()</div><div class="node-desc">Maps API shape &rarr;<br>local DB row</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node db" data-detail="mr-transaction"><div class="node-title">Transaction</div><div class="node-desc">store &rarr; upsert &rarr; dirty &rarr;<br>labels + assignees + reviewers</div><div class="diff-badge changed">3 junction tables (not 2)</div></div>
-        </div>
-        <div class="arrow-down">&darr;</div>
-        <div class="flow-row">
-          <div class="node db" data-detail="mr-cursor-update"><div class="node-title">Update Cursor</div><div class="node-desc">Per page (not every 100)</div><div class="diff-badge changed">Per page boundary</div></div>
-        </div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:var(--green-dim);color:var(--green)">2</div>
-          <div class="phase-title">MR Discussion Sync <span class="phase-subtitle">Parallel Prefetch + Serial Write</span></div>
-        </div>
-        <div class="info-box" style="margin-left:40px;margin-bottom:16px;">
-          <div class="info-box-title">Key Differences from Issue Discussions</div>
-          <ul>
-            <li><b>Parallel prefetch</b> &mdash; fetches all discussions for a batch concurrently via <code>join_all()</code></li>
-            <li><b>Upsert pattern</b> &mdash; notes use INSERT...ON CONFLICT (not delete-all + re-insert)</li>
-            <li><b>Sweep stale</b> &mdash; uses <code>last_seen_at</code> timestamp comparison (not set difference)</li>
-            <li><b>Sync health tracking</b> &mdash; records <code>discussions_sync_attempts</code> and <code>last_error</code></li>
-          </ul>
-        </div>
-        <div class="flow-row">
-          <div class="node db" data-detail="mr-disc-query"><div class="node-title">Query Stale MRs</div><div class="node-desc">updated_at &gt; COALESCE(<br>discussions_synced_for_<br>updated_at, 0)</div><div class="diff-badge same">Same watermark logic</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node decision" data-detail="mr-disc-batch"><div class="node-title">Batch by Concurrency</div><div class="node-desc">dependent_concurrency<br>MRs per batch</div><div class="diff-badge changed">Batched processing</div></div>
-        </div>
-        <div class="arrow-down">&darr;</div>
-        <div class="flow-row">
-          <div class="node api" data-detail="mr-disc-prefetch"><div class="node-title">Parallel Prefetch</div><div class="node-desc">join_all() fetches all<br>discussions for batch</div><div class="diff-badge changed">Parallel (not sequential)</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node transform" data-detail="mr-disc-transform"><div class="node-title">Transform In-Memory</div><div class="node-desc">transform_mr_discussion()<br>+ diff position notes</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node db" data-detail="mr-disc-write"><div class="node-title">Serial Write</div><div class="node-desc">upsert discussion<br>upsert notes (ON CONFLICT)</div><div class="diff-badge changed">Upsert, not delete+insert</div></div>
-        </div>
-        <div class="branch-container">
-          <div class="branch-label success">&#10003; On Full Success</div>
-          <div class="branch-row">
-            <div class="node db" data-detail="mr-disc-sweep"><div class="node-title">Sweep Stale</div><div class="node-desc">DELETE WHERE last_seen_at<br>&lt; run_seen_at (disc + notes)</div><div class="diff-badge changed">last_seen_at sweep</div></div>
-            <div class="arrow">&rarr;</div>
-            <div class="node db" data-detail="mr-disc-watermark"><div class="node-title">Advance Watermark</div><div class="node-desc">discussions_synced_for_<br>updated_at = updated_at</div></div>
-          </div>
-          <div class="branch-label error">&#10007; On Failure</div>
-          <div class="branch-row">
-            <div class="node error" data-detail="mr-disc-fail"><div class="node-title">Record Sync Health</div><div class="node-desc">Watermark NOT advanced<br>Tracks attempts + last_error</div><div class="diff-badge changed">Health tracking</div></div>
-          </div>
-        </div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:rgba(247,120,186,0.15);color:var(--pink)">3</div>
-          <div class="phase-title">Resource Events <span class="phase-subtitle">Same as Issues</span></div>
-        </div>
-        <div class="info-box" style="margin-left:40px">
-          <div class="info-box-title">Identical to Issue Resource Events</div>
-          <ul>
-            <li>Same queue-based approach: cleanup &rarr; enqueue &rarr; claim &rarr; fetch &rarr; store/fail</li>
-            <li>Same watermark column: <code>resource_events_synced_for_updated_at</code></li>
-            <li>Same error handling: 404/403 coalesced to empty, transient errors get backoff</li>
-            <li>entity_type = <code>"merge_request"</code> instead of <code>"issue"</code></li>
-          </ul>
-        </div>
-      </div>
-    </div>
-
-    <!-- DOCUMENTS -->
-    <div class="flow-container" id="view-docs">
-      <div class="legend">
-        <div class="legend-item"><div class="legend-color" style="background:var(--cyan)"></div>Trigger</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--purple)"></div>Extract</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--green)"></div>Database</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--amber)"></div>Decision</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--red)"></div>Error</div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:var(--cyan-dim);color:var(--cyan)">1</div>
-          <div class="phase-title">Dirty Source Queue <span class="phase-subtitle">Populated During Ingestion</span></div>
-        </div>
-        <div class="flow-row">
-          <div class="node api" data-detail="doc-trigger"><div class="node-title">mark_dirty_tx()</div><div class="node-desc">Called during every issue/<br>MR/discussion upsert</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node db" data-detail="doc-dirty-table"><div class="node-title">dirty_sources Table</div><div class="node-desc">INSERT (source_type, source_id)<br>ON CONFLICT reset backoff</div></div>
-        </div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:var(--amber-dim);color:var(--amber)">2</div>
-          <div class="phase-title">Drain Loop <span class="phase-subtitle">Batch 500, Respects Backoff</span></div>
-        </div>
-        <div class="flow-row">
-          <div class="node db" data-detail="doc-drain"><div class="node-title">Get Dirty Sources</div><div class="node-desc">Batch 500, ORDER BY<br>attempt_count, queued_at</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node decision" data-detail="doc-dispatch"><div class="node-title">Dispatch by Type</div><div class="node-desc">issue / mr / discussion<br>&rarr; extract function</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node decision" data-detail="doc-deleted-check"><div class="node-title">Source Exists?</div><div class="node-desc">If deleted: remove doc row<br>(cascade cleans FTS + embeds)</div></div>
-        </div>
-        <div class="arrow-down">&darr;</div>
-        <div class="flow-row">
-          <div class="node transform" data-detail="doc-extract"><div class="node-title">Extract Content</div><div class="node-desc">Structured text:<br>header + metadata + body</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node decision" data-detail="doc-triple-hash"><div class="node-title">Triple-Hash Check</div><div class="node-desc">content_hash + labels_hash<br>+ paths_hash all match?</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node db" data-detail="doc-write"><div class="node-title">SAVEPOINT Write</div><div class="node-desc">Atomic: document row +<br>labels + paths</div></div>
-        </div>
-        <div class="branch-container">
-          <div class="branch-label success">&#10003; On Success</div>
-          <div class="branch-row">
-            <div class="node db" data-detail="doc-clear"><div class="node-title">clear_dirty()</div><div class="node-desc">Remove from dirty_sources</div></div>
-          </div>
-          <div class="branch-label error">&#10007; On Error</div>
-          <div class="branch-row">
-            <div class="node error" data-detail="doc-error"><div class="node-title">record_dirty_error()</div><div class="node-desc">Increment attempt_count<br>Exponential backoff</div></div>
-          </div>
-          <div class="branch-label" style="color:var(--purple)">&#8801; Triple-Hash Match (skip)</div>
-          <div class="branch-row">
-            <div class="node db" data-detail="doc-skip"><div class="node-title">Skip Write</div><div class="node-desc">All 3 hashes match &rarr;<br>no WAL churn, clear dirty</div></div>
-          </div>
-        </div>
-      </div>
-      <div class="info-box">
-        <div class="info-box-title">Full Mode (<code>--full</code>)</div>
-        <ul>
-          <li>Seeds <b>ALL</b> entities into <code>dirty_sources</code> via keyset pagination</li>
-          <li>Triple-hash optimization prevents redundant writes even in full mode</li>
-          <li>Runs FTS <code>OPTIMIZE</code> after drain completes</li>
-        </ul>
-      </div>
-    </div>
-
-    <!-- EMBEDDINGS -->
-    <div class="flow-container" id="view-embed">
-      <div class="legend">
-        <div class="legend-item"><div class="legend-color" style="background:var(--cyan)"></div>API (Ollama)</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--purple)"></div>Processing</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--green)"></div>Database</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--amber)"></div>Decision</div>
-        <div class="legend-item"><div class="legend-color" style="background:var(--red)"></div>Error</div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:var(--amber-dim);color:var(--amber)">1</div>
-          <div class="phase-title">Change Detection <span class="phase-subtitle">Hash + Config Drift</span></div>
-        </div>
-        <div class="flow-row">
-          <div class="node decision" data-detail="embed-detect"><div class="node-title">find_pending_documents()</div><div class="node-desc">No metadata row? OR<br>document_hash mismatch? OR<br>config drift?</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node db" data-detail="embed-paginate"><div class="node-title">Keyset Pagination</div><div class="node-desc">500 documents per page<br>ordered by doc ID</div></div>
-        </div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:var(--purple-dim);color:var(--purple)">2</div>
-          <div class="phase-title">Chunking <span class="phase-subtitle">Split + Overflow Guard</span></div>
-        </div>
-        <div class="flow-row">
-          <div class="node transform" data-detail="embed-chunk"><div class="node-title">split_into_chunks()</div><div class="node-desc">Split by paragraph boundaries<br>with configurable overlap</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node decision" data-detail="embed-overflow"><div class="node-title">Overflow Guard</div><div class="node-desc">Too many chunks?<br>Skip to prevent rowid collision</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node transform" data-detail="embed-work"><div class="node-title">Build ChunkWork</div><div class="node-desc">Assign encoded chunk IDs<br>per document</div></div>
-        </div>
-      </div>
-      <div class="phase">
-        <div class="phase-header">
-          <div class="phase-number" style="background:var(--cyan-dim);color:var(--cyan)">3</div>
-          <div class="phase-title">Ollama Embedding <span class="phase-subtitle">Batched API Calls</span></div>
-        </div>
-        <div class="flow-row">
-          <div class="node api" data-detail="embed-batch"><div class="node-title">Batch Embed</div><div class="node-desc">32 chunks per Ollama<br>API call</div></div>
-          <div class="arrow">&rarr;</div>
-          <div class="node db" data-detail="embed-store"><div class="node-title">Store Vectors</div><div class="node-desc">sqlite-vec embeddings table<br>+ embedding_metadata</div></div>
-        </div>
-        <div class="branch-container">
-          <div class="branch-label success">&#10003; On Success</div>
-          <div class="branch-row">
-            <div class="node db" data-detail="embed-success"><div class="node-title">SAVEPOINT Commit</div><div class="node-desc">Atomic per page:<br>clear old + write new</div></div>
-          </div>
-          <div class="branch-label retry">&#8635; Context-Length Error</div>
-          <div class="branch-row">
-            <div class="node error" data-detail="embed-ctx-error"><div class="node-title">Retry Individually</div><div class="node-desc">Re-embed each chunk solo<br>to isolate oversized one</div></div>
-          </div>
-          <div class="branch-label error">&#10007; Other Error</div>
-          <div class="branch-row">
-            <div class="node error" data-detail="embed-other-error"><div class="node-title">Record Error</div><div class="node-desc">Store in embedding_metadata<br>for retry next run</div></div>
-          </div>
-        </div>
-      </div>
-      <div class="info-box">
-        <div class="info-box-title">Full Mode (<code>--full</code>)</div>
-        <ul>
-          <li>DELETEs all <code>embedding_metadata</code> and <code>embeddings</code> rows first</li>
-          <li>Every document re-processed from scratch</li>
-        </ul>
-      </div>
-      <div class="info-box">
-        <div class="info-box-title">Non-Fatal in Sync</div>
-        <ul>
-          <li>Stage 4 failures (Ollama down, model missing) are <b>graceful</b></li>
-          <li>Sync completes successfully; embeddings just won't be updated</li>
-          <li>Semantic search degrades to FTS-only mode</li>
-        </ul>
-      </div>
-    </div>
-
-  </div></div>
-
-  <!-- Watermark Panel -->
-  <div class="watermark-panel">
-    <div class="watermark-toggle" onclick="toggleWatermarks()">
-      <span class="chevron" id="wm-chevron">&#9650;</span>
-      Watermark &amp; Cursor Reference
-    </div>
-    <div class="watermark-content" id="wm-content">
-      <table class="wm-table">
-        <thead><tr><th>Table</th><th>Column(s)</th><th>Purpose</th></tr></thead>
-        <tbody>
-          <tr><td>sync_cursors</td><td>updated_at_cursor + tie_breaker_id</td><td>Incremental fetch: "last entity we saw" per project+type</td></tr>
-          <tr><td>issues</td><td>discussions_synced_for_updated_at</td><td>Per-issue discussion watermark</td></tr>
-          <tr><td>issues</td><td>resource_events_synced_for_updated_at</td><td>Per-issue resource event watermark</td></tr>
-          <tr><td>merge_requests</td><td>discussions_synced_for_updated_at</td><td>Per-MR discussion watermark</td></tr>
-          <tr><td>merge_requests</td><td>resource_events_synced_for_updated_at</td><td>Per-MR resource event watermark</td></tr>
-          <tr><td>dirty_sources</td><td>queued_at + next_attempt_at</td><td>Document regeneration queue with backoff</td></tr>
-          <tr><td>embedding_metadata</td><td>document_hash + chunk_max_bytes + model + dims</td><td>Embedding staleness detection</td></tr>
-          <tr><td>pending_dependent_fetches</td><td>locked_at + next_retry_at + attempts</td><td>Resource event job queue with backoff</td></tr>
-        </tbody>
-      </table>
-    </div>
-  </div>
-</div>
-
-<!-- Detail Panel -->
-<div class="detail-panel" id="detail-panel">
-  <div class="detail-header">
-    <h2 id="detail-title">Node Details</h2>
-    <button class="detail-close" onclick="closeDetail()">&times;</button>
-  </div>
-  <div class="detail-body" id="detail-body"></div>
-</div>
-
-<script>
-const viewTitles = {
-  overview: 'Full Sync Overview', issues: 'Issue Ingestion Flow',
-  mrs: 'Merge Request Ingestion Flow', docs: 'Document Generation Flow',
-  embed: 'Embedding Generation Flow',
-};
-const viewBadges = {
-  overview: '4 stages', issues: '3 phases', mrs: '3 phases',
-  docs: '2 phases', embed: '3 phases',
-};
-
-function switchView(view) {
-  document.querySelectorAll('.flow-container').forEach(function(el) { el.classList.remove('active'); });
-  document.getElementById('view-' + view).classList.add('active');
-  document.querySelectorAll('.nav-item').forEach(function(el) {
-    el.classList.toggle('active', el.dataset.view === view);
-  });
-  document.getElementById('view-title').textContent = viewTitles[view];
-  document.getElementById('view-badge').textContent = viewBadges[view];
-  closeDetail();
-}
-
-function toggleWatermarks() {
-  document.getElementById('wm-content').classList.toggle('open');
-  document.getElementById('wm-chevron').classList.toggle('open');
-}
-
-var details = {
-  'issue-api-call': { title: 'GitLab API: Paginate Issues', type: 'api', file: 'src/ingestion/issues.rs:51-140', desc: 'Streams issues from the GitLab API using cursor-based incremental sync. The API is called with updated_after set to the last known cursor minus a configurable rewind window (to handle clock skew between GitLab and the local database).', sql: 'GET /api/v4/projects/{id}/issues\n  ?updated_after={cursor - rewind_seconds}\n  &order_by=updated_at&sort=asc\n  &per_page=100' },
-  'issue-cursor-filter': { title: 'Cursor Filter (Dedup)', type: 'decision', file: 'src/ingestion/issues.rs:95-110', desc: 'Because of the cursor rewind, some issues will be re-fetched that we already have. The cursor filter skips these using a two-part comparison: primary on updated_at timestamp, with gitlab_id as a tie-breaker when timestamps are equal.', sql: '// Pseudocode:\nif issue.updated_at > cursor_ts:\n    ACCEPT  // newer than cursor\nelif issue.updated_at == cursor_ts\n     AND issue.gitlab_id > tie_breaker_id:\n    ACCEPT  // same timestamp, higher ID\nelse:\n    SKIP    // already processed' },
-  'issue-transform': { title: 'Transform Issue', type: 'transform', file: 'src/gitlab/transformers/issue.rs', desc: 'Maps the GitLab API response shape to the local database row shape. Parses ISO 8601 timestamps to milliseconds-since-epoch, extracts label names, assignee usernames, milestone info, and due dates.' },
-  'issue-transaction': { title: 'Issue Write Transaction', type: 'db', file: 'src/ingestion/issues.rs:190-220', desc: 'All operations for a single issue are wrapped in one SQLite transaction for atomicity. If any step fails, the entire issue write is rolled back.', sql: 'BEGIN;\n-- 1. Store raw JSON payload (compressed, deduped)\nINSERT INTO payloads ...;\n-- 2. Upsert issue row\nINSERT INTO issues ... ON CONFLICT(gitlab_id)\n  DO UPDATE SET ...;\n-- 3. Mark dirty for document regen\nINSERT INTO dirty_sources ...;\n-- 4. Relink labels\nDELETE FROM issue_labels WHERE issue_id = ?;\nINSERT INTO labels ... ON CONFLICT DO UPDATE;\nINSERT INTO issue_labels ...;\n-- 5. Relink assignees\nDELETE FROM issue_assignees WHERE issue_id = ?;\nINSERT INTO issue_assignees ...;\nCOMMIT;' },
-  'issue-cursor-update': { title: 'Update Sync Cursor', type: 'db', file: 'src/ingestion/issues.rs:130-140', desc: 'The sync cursor is updated every 100 issues (for crash recovery) and once at the end of the stream. If the process crashes mid-sync, it resumes from at most 100 issues back.', sql: 'INSERT INTO sync_cursors\n  (project_id, resource_type,\n   updated_at_cursor, tie_breaker_id)\nVALUES (?1, \'issues\', ?2, ?3)\nON CONFLICT(project_id, resource_type)\n  DO UPDATE SET\n    updated_at_cursor = ?2,\n    tie_breaker_id = ?3;' },
-  'issue-disc-query': { title: 'Query Issues Needing Discussion Sync', type: 'db', file: 'src/ingestion/issues.rs:450-471', desc: 'Finds all issues in this project whose updated_at timestamp exceeds their per-row discussion watermark. Issues that have not changed since their last discussion sync are skipped entirely.', sql: 'SELECT id, iid, updated_at\nFROM issues\nWHERE project_id = ?1\n  AND updated_at > COALESCE(\n    discussions_synced_for_updated_at, 0\n  );' },
-  'issue-disc-fetch': { title: 'Paginate Issue Discussions', type: 'api', file: 'src/ingestion/discussions.rs:73-205', desc: 'Discussions are fetched sequentially per issue (rusqlite Connection is not Send, so async parallelism is not possible here). Each issue\'s discussions are streamed page by page from the GitLab API.', sql: 'GET /api/v4/projects/{id}/issues/{iid}\n    /discussions?per_page=100' },
-  'issue-disc-transform': { title: 'Transform Discussion + Notes', type: 'transform', file: 'src/gitlab/transformers/discussion.rs', desc: 'Transforms the raw GitLab discussion payload into normalized rows. Sets NoteableRef::Issue. Computes resolvable/resolved status, first_note_at/last_note_at timestamps, and per-note position indices.' },
-  'issue-disc-write': { title: 'Write Discussion (Full Refresh)', type: 'db', file: 'src/ingestion/discussions.rs:140-180', desc: 'Issue discussions use a full-refresh pattern: all existing notes for a discussion are deleted and re-inserted. This is simpler than upsert but means partial failures lose the previous state.', sql: 'BEGIN;\nINSERT INTO payloads ...;\nINSERT INTO discussions ... ON CONFLICT DO UPDATE;\nINSERT INTO dirty_sources ...;\n-- Full refresh: delete all then re-insert\nDELETE FROM notes WHERE discussion_id = ?;\nINSERT INTO notes VALUES (...);\nCOMMIT;' },
-  'issue-disc-stale': { title: 'Remove Stale Discussions', type: 'db', file: 'src/ingestion/discussions.rs:185-195', desc: 'After successfully fetching ALL discussion pages for an issue, any discussions in the DB that were not seen in this fetch are deleted. Uses a temp table for >500 IDs to avoid SQLite\'s 999-variable limit.', sql: '-- For small sets (<= 500):\nDELETE FROM discussions\nWHERE issue_id = ?\n  AND gitlab_id NOT IN (...);\n\n-- For large sets (> 500):\nCREATE TEMP TABLE seen_ids(id TEXT);\nINSERT INTO seen_ids ...;\nDELETE FROM discussions\nWHERE issue_id = ?\n  AND gitlab_id NOT IN\n    (SELECT id FROM seen_ids);\nDROP TABLE seen_ids;' },
-  'issue-disc-watermark': { title: 'Advance Discussion Watermark', type: 'db', file: 'src/ingestion/discussions.rs:198', desc: 'Sets the per-issue watermark to the issue\'s current updated_at, signaling that discussions are now synced for this version of the issue.', sql: 'UPDATE issues\nSET discussions_synced_for_updated_at\n    = updated_at\nWHERE id = ?;' },
-  'issue-disc-fail': { title: 'Pagination Error Handling', type: 'error', file: 'src/ingestion/discussions.rs:182', desc: 'If pagination fails mid-stream, stale discussion removal is skipped (we don\'t know the full set) and the watermark is NOT advanced. The issue will be retried on the next sync run.' },
-  're-cleanup': { title: 'Cleanup Obsolete Jobs', type: 'queue', file: 'src/ingestion/orchestrator.rs:490-520', desc: 'Before enqueuing new jobs, delete any existing jobs for entities whose watermark is already current. These are leftover from a previous run.', sql: 'DELETE FROM pending_dependent_fetches\nWHERE project_id = ?\n  AND job_type = \'resource_events\'\n  AND entity_local_id IN (\n    SELECT id FROM issues\n    WHERE project_id = ?\n      AND updated_at <= COALESCE(\n        resource_events_synced_for_updated_at, 0\n      )\n  );' },
-  're-enqueue': { title: 'Enqueue Resource Event Jobs', type: 'queue', file: 'src/ingestion/orchestrator.rs:525-555', desc: 'For each entity whose updated_at exceeds its resource event watermark, insert a job into the queue. Uses INSERT OR IGNORE for idempotency.', sql: 'INSERT OR IGNORE INTO pending_dependent_fetches\n  (project_id, entity_type, entity_iid,\n   entity_local_id, job_type, enqueued_at)\nSELECT project_id, \'issue\', iid, id,\n       \'resource_events\', ?now\nFROM issues\nWHERE project_id = ?\n  AND updated_at > COALESCE(\n    resource_events_synced_for_updated_at, 0\n  );' },
-  're-claim': { title: 'Claim Jobs (Atomic Lock)', type: 'queue', file: 'src/core/dependent_queue.rs', desc: 'Atomically claims a batch of unlocked jobs whose backoff period has elapsed. Uses UPDATE...RETURNING for lock acquisition in a single statement.', sql: 'UPDATE pending_dependent_fetches\nSET locked_at = ?now\nWHERE rowid IN (\n  SELECT rowid\n  FROM pending_dependent_fetches\n  WHERE project_id = ?\n    AND job_type = \'resource_events\'\n    AND locked_at IS NULL\n    AND (next_retry_at IS NULL\n         OR next_retry_at <= ?now)\n  ORDER BY enqueued_at ASC\n  LIMIT ?batch_size\n)\nRETURNING *;' },
-  're-fetch': { title: 'Fetch 3 Event Types Concurrently', type: 'api', file: 'src/gitlab/client.rs:732-771', desc: 'Uses tokio::join! (not try_join!) to fetch state, label, and milestone events concurrently. Permanent errors (404, 403) are coalesced to empty vecs via coalesce_inaccessible().', sql: 'tokio::join!(\n  fetch_issue_state_events(proj, iid),\n  fetch_issue_label_events(proj, iid),\n  fetch_issue_milestone_events(proj, iid),\n)\n// Each: coalesce_inaccessible()\n// 404/403 -> Ok(vec![])\n// Other errors -> propagated' },
-  're-store': { title: 'Store Resource Events', type: 'db', file: 'src/ingestion/orchestrator.rs:620-640', desc: 'All three event types are upserted in a single transaction.', sql: 'BEGIN;\nINSERT INTO resource_state_events ...\n  ON CONFLICT DO UPDATE;\nINSERT INTO resource_label_events ...\n  ON CONFLICT DO UPDATE;\nINSERT INTO resource_milestone_events ...\n  ON CONFLICT DO UPDATE;\nCOMMIT;' },
-  're-complete': { title: 'Complete Job + Advance Watermark', type: 'db', file: 'src/ingestion/orchestrator.rs:645-660', desc: 'After successful storage, the job row is deleted and the entity\'s watermark is advanced.', sql: 'DELETE FROM pending_dependent_fetches\n  WHERE rowid = ?;\n\nUPDATE issues\nSET resource_events_synced_for_updated_at\n    = updated_at\nWHERE id = ?;' },
-  're-permanent': { title: 'Permanent Error: Skip Entity', type: 'error', file: 'src/ingestion/orchestrator.rs:665-680', desc: '404 (endpoint doesn\'t exist) and 403 (insufficient permissions) are permanent. The job is completed and watermark advanced, so this entity is permanently skipped until next updated on GitLab.' },
-  're-transient': { title: 'Transient Error: Exponential Backoff', type: 'error', file: 'src/core/dependent_queue.rs', desc: 'Network errors, 500s, rate limits get exponential backoff. Formula: 30s * 2^(attempts-1), capped at 480s (8 minutes).', sql: 'UPDATE pending_dependent_fetches\nSET locked_at = NULL,\n    attempts = attempts + 1,\n    next_retry_at = ?now\n      + 30000 * pow(2, attempts),\n    -- capped at 480000ms (8 min)\n    last_error = ?error_msg\nWHERE rowid = ?;' },
-  'mr-api-call': { title: 'GitLab API: Fetch MR Pages', type: 'api', file: 'src/ingestion/merge_requests.rs:51-151', desc: 'Unlike issues which stream, MRs use explicit page-based pagination via fetch_merge_requests_page(). Each page returns items plus a next_page indicator.', sql: 'GET /api/v4/projects/{id}/merge_requests\n  ?updated_after={cursor - rewind}\n  &order_by=updated_at&sort=asc\n  &per_page=100&page={n}' },
-  'mr-cursor-filter': { title: 'Cursor Filter', type: 'decision', file: 'src/ingestion/merge_requests.rs:90-105', desc: 'Identical logic to issues: timestamp comparison with gitlab_id tie-breaker.' },
-  'mr-transform': { title: 'Transform Merge Request', type: 'transform', file: 'src/gitlab/transformers/mr.rs', desc: 'Maps GitLab MR response to local row. Handles draft detection (prefers draft field, falls back to work_in_progress), detailed_merge_status, merge_user resolution, and reviewer extraction.' },
-  'mr-transaction': { title: 'MR Write Transaction', type: 'db', file: 'src/ingestion/merge_requests.rs:170-210', desc: 'Same pattern as issues but with THREE junction tables: labels, assignees, AND reviewers.', sql: 'BEGIN;\nINSERT INTO payloads ...;\nINSERT INTO merge_requests ...\n  ON CONFLICT DO UPDATE;\nINSERT INTO dirty_sources ...;\n-- 3 junction tables:\nDELETE FROM mr_labels WHERE mr_id = ?;\nINSERT INTO mr_labels ...;\nDELETE FROM mr_assignees WHERE mr_id = ?;\nINSERT INTO mr_assignees ...;\nDELETE FROM mr_reviewers WHERE mr_id = ?;\nINSERT INTO mr_reviewers ...;\nCOMMIT;' },
-  'mr-cursor-update': { title: 'Update Cursor Per Page', type: 'db', file: 'src/ingestion/merge_requests.rs:140-150', desc: 'Unlike issues (every 100 items), MR cursor is updated at each page boundary for better crash recovery.' },
-  'mr-disc-query': { title: 'Query MRs Needing Discussion Sync', type: 'db', file: 'src/ingestion/merge_requests.rs:430-451', desc: 'Same watermark pattern as issues. Runs AFTER MR ingestion to avoid memory growth.', sql: 'SELECT id, iid, updated_at\nFROM merge_requests\nWHERE project_id = ?1\n  AND updated_at > COALESCE(\n    discussions_synced_for_updated_at, 0\n  );' },
-  'mr-disc-batch': { title: 'Batch by Concurrency', type: 'decision', file: 'src/ingestion/orchestrator.rs:420-465', desc: 'MRs are processed in batches sized by dependent_concurrency. Each batch first prefetches all discussions in parallel, then writes serially.' },
-  'mr-disc-prefetch': { title: 'Parallel Prefetch', type: 'api', file: 'src/ingestion/mr_discussions.rs:66-120', desc: 'All MRs in the batch have their discussions fetched concurrently via join_all(). Each MR\'s discussions are fetched in one call, transformed in memory, and returned as PrefetchedMrDiscussions.', sql: '// For each MR in batch, concurrently:\nGET /api/v4/projects/{id}/merge_requests\n    /{iid}/discussions?per_page=100\n\n// All fetched + transformed in memory\n// before any DB writes happen' },
-  'mr-disc-transform': { title: 'Transform MR Discussions', type: 'transform', file: 'src/ingestion/mr_discussions.rs:125-160', desc: 'Uses transform_mr_discussion() which additionally handles DiffNote positions (file paths, line ranges, SHA triplets).' },
-  'mr-disc-write': { title: 'Serial Write (Upsert Pattern)', type: 'db', file: 'src/ingestion/mr_discussions.rs:165-220', desc: 'Unlike issue discussions (delete-all + re-insert), MR discussions use INSERT...ON CONFLICT DO UPDATE for both discussions and notes. Safer for partial failures.', sql: 'BEGIN;\nINSERT INTO payloads ...;\nINSERT INTO discussions ...\n  ON CONFLICT DO UPDATE\n  SET ..., last_seen_at = ?run_ts;\nINSERT INTO dirty_sources ...;\n-- Upsert notes (not delete+insert):\nINSERT INTO notes ...\n  ON CONFLICT DO UPDATE\n  SET ..., last_seen_at = ?run_ts;\nCOMMIT;' },
-  'mr-disc-sweep': { title: 'Sweep Stale (last_seen_at)', type: 'db', file: 'src/ingestion/mr_discussions.rs:225-245', desc: 'Staleness detected via last_seen_at timestamps. Both discussions AND notes are swept independently.', sql: '-- Sweep stale discussions:\nDELETE FROM discussions\nWHERE merge_request_id = ?\n  AND last_seen_at < ?run_seen_at;\n\n-- Sweep stale notes:\nDELETE FROM notes\nWHERE discussion_id IN (\n  SELECT id FROM discussions\n  WHERE merge_request_id = ?\n) AND last_seen_at < ?run_seen_at;' },
-  'mr-disc-watermark': { title: 'Advance MR Discussion Watermark', type: 'db', file: 'src/ingestion/mr_discussions.rs:248', desc: 'Same as issues: stamps the per-MR watermark.', sql: 'UPDATE merge_requests\nSET discussions_synced_for_updated_at\n    = updated_at\nWHERE id = ?;' },
-  'mr-disc-fail': { title: 'Failure: Sync Health Tracking', type: 'error', file: 'src/ingestion/mr_discussions.rs:252-260', desc: 'Unlike issues, MR discussion failures are tracked: discussions_sync_attempts is incremented and discussions_sync_last_error is recorded. Watermark is NOT advanced.' },
-  'doc-trigger': { title: 'mark_dirty_tx()', type: 'api', file: 'src/ingestion/dirty_tracker.rs', desc: 'Called during every upsert in ingestion. Inserts into dirty_sources, or on conflict resets backoff. This bridges ingestion (stages 1-2) and document generation (stage 3).', sql: 'INSERT INTO dirty_sources\n  (source_type, source_id, queued_at)\nVALUES (?1, ?2, ?now)\nON CONFLICT(source_type, source_id)\n  DO UPDATE SET\n    queued_at = ?now,\n    attempt_count = 0,\n    next_attempt_at = NULL,\n    last_error = NULL;' },
-  'doc-dirty-table': { title: 'dirty_sources Table', type: 'db', file: 'src/ingestion/dirty_tracker.rs', desc: 'Persistent queue of entities needing document regeneration. Supports exponential backoff for failed extractions.' },
-  'doc-drain': { title: 'Get Dirty Sources (Batched)', type: 'db', file: 'src/documents/regenerator.rs:35-45', desc: 'Fetches up to 500 dirty entries per batch, prioritizing fewer attempts. Respects exponential backoff.', sql: 'SELECT source_type, source_id\nFROM dirty_sources\nWHERE next_attempt_at IS NULL\n   OR next_attempt_at <= ?now\nORDER BY attempt_count ASC,\n         queued_at ASC\nLIMIT 500;' },
-  'doc-dispatch': { title: 'Dispatch by Source Type', type: 'decision', file: 'src/documents/extractor.rs', desc: 'Routes to the appropriate extraction function: "issue" -> extract_issue_document(), "merge_request" -> extract_mr_document(), "discussion" -> extract_discussion_document().' },
-  'doc-deleted-check': { title: 'Source Exists Check', type: 'decision', file: 'src/documents/regenerator.rs:48-55', desc: 'If the source entity was deleted, the extractor returns None. The regenerator deletes the document row. FK cascades clean up FTS and embeddings.' },
-  'doc-extract': { title: 'Extract Structured Content', type: 'transform', file: 'src/documents/extractor.rs', desc: 'Builds searchable text:\n[[Issue]] #42: Title\nProject: group/repo\nURL: ...\nLabels: [bug, urgent]\nState: opened\n\n--- Description ---\n...\n\nDiscussions inherit parent labels and extract DiffNote file paths.' },
-  'doc-triple-hash': { title: 'Triple-Hash Write Optimization', type: 'decision', file: 'src/documents/regenerator.rs:55-62', desc: 'Checks content_hash + labels_hash + paths_hash against existing document. If ALL three match, write is completely skipped. Critical for --full mode performance.' },
-  'doc-write': { title: 'SAVEPOINT Atomic Write', type: 'db', file: 'src/documents/regenerator.rs:58-65', desc: 'Document, labels, and paths written inside a SAVEPOINT for atomicity.', sql: 'SAVEPOINT doc_write;\nINSERT INTO documents ...\n  ON CONFLICT DO UPDATE SET\n    content = ?, content_hash = ?,\n    labels_hash = ?, paths_hash = ?;\nDELETE FROM document_labels\n  WHERE doc_id = ?;\nINSERT INTO document_labels ...;\nDELETE FROM document_paths\n  WHERE doc_id = ?;\nINSERT INTO document_paths ...;\nRELEASE doc_write;' },
-  'doc-clear': { title: 'Clear Dirty Entry', type: 'db', file: 'src/ingestion/dirty_tracker.rs', desc: 'On success, the dirty_sources row is deleted.', sql: 'DELETE FROM dirty_sources\nWHERE source_type = ?\n  AND source_id = ?;' },
-  'doc-error': { title: 'Record Error + Backoff', type: 'error', file: 'src/ingestion/dirty_tracker.rs', desc: 'Increments attempt_count, sets next_attempt_at with exponential backoff. Entry stays for retry.', sql: 'UPDATE dirty_sources\nSET attempt_count = attempt_count + 1,\n    next_attempt_at = ?now\n      + compute_backoff(attempt_count),\n    last_error = ?error_msg\nWHERE source_type = ?\n  AND source_id = ?;' },
-  'doc-skip': { title: 'Skip Write (Hash Match)', type: 'db', file: 'src/documents/regenerator.rs:57', desc: 'When all three hashes match, the document has not actually changed. Common when updated_at changes but content/labels/paths remain the same. Dirty entry is cleared without writes.' },
-  'embed-detect': { title: 'Change Detection', type: 'decision', file: 'src/embedding/change_detector.rs', desc: 'Document needs re-embedding if: (1) No embedding_metadata row, (2) document_hash mismatch, (3) Config drift in chunk_max_bytes, model, or dims.', sql: 'SELECT d.id, d.content, d.content_hash\nFROM documents d\nLEFT JOIN embedding_metadata em\n  ON em.document_id = d.id\nWHERE em.document_id IS NULL\n   OR em.document_hash != d.content_hash\n   OR em.chunk_max_bytes != ?config\n   OR em.model != ?model\n   OR em.dims != ?dims;' },
-  'embed-paginate': { title: 'Keyset Pagination', type: 'db', file: 'src/embedding/pipeline.rs:80-100', desc: '500 documents per page using keyset pagination. Each page wrapped in a SAVEPOINT.' },
-  'embed-chunk': { title: 'Split Into Chunks', type: 'transform', file: 'src/embedding/chunking.rs', desc: 'Splits content at paragraph boundaries with configurable max size and overlap.' },
-  'embed-overflow': { title: 'Overflow Guard', type: 'decision', file: 'src/embedding/pipeline.rs:110-120', desc: 'If a document produces too many chunks, it is skipped to prevent rowid collisions in the encoded chunk ID scheme.' },
-  'embed-work': { title: 'Build ChunkWork Items', type: 'transform', file: 'src/embedding/pipeline.rs:125-140', desc: 'Each chunk gets an encoded ID (document_id * 1000000 + chunk_index) for the sqlite-vec primary key.' },
-  'embed-batch': { title: 'Batch Embed via Ollama', type: 'api', file: 'src/embedding/pipeline.rs:150-200', desc: 'Sends 32 chunks per Ollama API call. Model default: nomic-embed-text.', sql: 'POST http://localhost:11434/api/embed\n{\n  "model": "nomic-embed-text",\n  "input": ["chunk1...", "chunk2...", ...]\n}' },
-  'embed-store': { title: 'Store Vectors', type: 'db', file: 'src/embedding/pipeline.rs:205-230', desc: 'Vectors stored in sqlite-vec virtual table. Metadata in embedding_metadata. Old embeddings cleared on first successful chunk.', sql: '-- Clear old embeddings:\nDELETE FROM embeddings\n  WHERE rowid / 1000000 = ?doc_id;\n\n-- Insert new vector:\nINSERT INTO embeddings(rowid, embedding)\nVALUES (?chunk_id, ?vector_blob);\n\n-- Update metadata:\nINSERT INTO embedding_metadata ...\n  ON CONFLICT DO UPDATE SET\n    document_hash = ?,\n    chunk_max_bytes = ?,\n    model = ?, dims = ?;' },
-  'embed-success': { title: 'SAVEPOINT Commit', type: 'db', file: 'src/embedding/pipeline.rs:240-250', desc: 'Each page of 500 documents wrapped in a SAVEPOINT. Completed pages survive crashes.' },
-  'embed-ctx-error': { title: 'Context-Length Retry', type: 'error', file: 'src/embedding/pipeline.rs:260-280', desc: 'If Ollama returns context-length error for a batch, each chunk is retried individually to isolate the oversized one.' },
-  'embed-other-error': { title: 'Record Error for Retry', type: 'error', file: 'src/embedding/pipeline.rs:285-295', desc: 'Network/model errors recorded in embedding_metadata. Document detected as pending again on next run.' },
-};
-
-function escapeHtml(str) {
-  var div = document.createElement('div');
-  div.appendChild(document.createTextNode(str));
-  return div.textContent;
-}
-
-function buildDetailContent(d) {
-  var container = document.createDocumentFragment();
-
-  // Tags section
-  var tagSection = document.createElement('div');
-  tagSection.className = 'detail-section';
-  var typeTag = document.createElement('span');
-  typeTag.className = 'detail-tag type-' + d.type;
-  typeTag.textContent = d.type.toUpperCase();
-  tagSection.appendChild(typeTag);
-  if (d.file) {
-    var fileTag = document.createElement('span');
-    fileTag.className = 'detail-tag file';
-    fileTag.textContent = d.file;
-    tagSection.appendChild(fileTag);
-  }
-  container.appendChild(tagSection);
-
-  // Description
-  var descSection = document.createElement('div');
-  descSection.className = 'detail-section';
-  var descH3 = document.createElement('h3');
-  descH3.textContent = 'Description';
-  descSection.appendChild(descH3);
-  var descP = document.createElement('p');
-  descP.textContent = d.desc;
-  descSection.appendChild(descP);
-  container.appendChild(descSection);
-
-  // SQL
-  if (d.sql) {
-    var sqlSection = document.createElement('div');
-    sqlSection.className = 'detail-section';
-    var sqlH3 = document.createElement('h3');
-    sqlH3.textContent = 'Key Query / Code';
-    sqlSection.appendChild(sqlH3);
-    var sqlBlock = document.createElement('div');
-    sqlBlock.className = 'sql-block';
-    sqlBlock.textContent = d.sql;
-    sqlSection.appendChild(sqlBlock);
-    container.appendChild(sqlSection);
-  }
-
-  return container;
-}
-
-function showDetail(key) {
-  var d = details[key];
-  if (!d) return;
-  var panel = document.getElementById('detail-panel');
-  document.getElementById('detail-title').textContent = d.title;
-  var body = document.getElementById('detail-body');
-  while (body.firstChild) body.removeChild(body.firstChild);
-  body.appendChild(buildDetailContent(d));
-  document.querySelectorAll('.node.selected').forEach(function(n) { n.classList.remove('selected'); });
-  var clicked = document.querySelector('[data-detail="' + key + '"]');
-  if (clicked) clicked.classList.add('selected');
-  panel.classList.add('open');
-}
-
-function closeDetail() {
-  document.getElementById('detail-panel').classList.remove('open');
-  document.querySelectorAll('.node.selected').forEach(function(n) { n.classList.remove('selected'); });
-}
-
-document.addEventListener('click', function(e) {
-  var node = e.target.closest('.node[data-detail]');
-  if (node) { showDetail(node.dataset.detail); return; }
-  if (!e.target.closest('.detail-panel') && !e.target.closest('.node')) closeDetail();
-});
-document.addEventListener('keydown', function(e) { if (e.key === 'Escape') closeDetail(); });
-</script>
-</body>
-</html>

migrations/022_notes_query_index.sql

@@ -19,3 +19,6 @@ CREATE INDEX IF NOT EXISTS idx_discussions_mr_id ON discussions(merge_request_id
 -- Immutable author identity column (GitLab numeric user ID)
 ALTER TABLE notes ADD COLUMN author_id INTEGER;
 CREATE INDEX IF NOT EXISTS idx_notes_author_id ON notes(author_id) WHERE author_id IS NOT NULL;
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (22, strftime('%s', 'now') * 1000, '022_notes_query_index');

migrations/024_note_documents.sql

@@ -151,3 +151,6 @@ END;
 
 DROP TABLE IF EXISTS _doc_labels_backup;
 DROP TABLE IF EXISTS _doc_paths_backup;
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (24, strftime('%s', 'now') * 1000, '024_note_documents');

migrations/025_note_dirty_backfill.sql

@@ -6,3 +6,6 @@ FROM notes n
 LEFT JOIN documents d ON d.source_type = 'note' AND d.source_id = n.id
 WHERE n.is_system = 0 AND d.id IS NULL
 ON CONFLICT(source_type, source_id) DO NOTHING;
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (25, strftime('%s', 'now') * 1000, '025_note_dirty_backfill');

migrations/026_scoring_indexes.sql

@@ -18,3 +18,6 @@ CREATE INDEX IF NOT EXISTS idx_notes_diffnote_discussion_author
 CREATE INDEX IF NOT EXISTS idx_notes_old_path_project_created
   ON notes(position_old_path, project_id, created_at)
   WHERE note_type = 'DiffNote' AND is_system = 0 AND position_old_path IS NOT NULL;
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (26, strftime('%s', 'now') * 1000, '026_scoring_indexes');

migrations/027_surgical_sync_runs.sql

@@ -0,0 +1,23 @@
+-- Migration 027: Extend sync_runs for surgical sync observability
+-- Adds mode/phase tracking and surgical-specific counters.
+
+ALTER TABLE sync_runs ADD COLUMN mode TEXT;
+ALTER TABLE sync_runs ADD COLUMN phase TEXT;
+ALTER TABLE sync_runs ADD COLUMN surgical_iids_json TEXT;
+ALTER TABLE sync_runs ADD COLUMN issues_fetched INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE sync_runs ADD COLUMN mrs_fetched INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE sync_runs ADD COLUMN issues_ingested INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE sync_runs ADD COLUMN mrs_ingested INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE sync_runs ADD COLUMN skipped_stale INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE sync_runs ADD COLUMN docs_regenerated INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE sync_runs ADD COLUMN docs_embedded INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE sync_runs ADD COLUMN warnings_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE sync_runs ADD COLUMN cancelled_at INTEGER;
+
+CREATE INDEX IF NOT EXISTS idx_sync_runs_mode_started
+    ON sync_runs(mode, started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_sync_runs_status_phase_started
+    ON sync_runs(status, phase, started_at DESC);
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (27, strftime('%s', 'now') * 1000, '027_surgical_sync_runs');

migrations/028_discussions_mr_fk.sql

@@ -0,0 +1,58 @@
+-- Migration 028: Add FK constraint on discussions.merge_request_id
+-- Schema version: 28
+-- Fixes missing foreign key that causes orphaned discussions when MRs are deleted
+
+-- SQLite doesn't support ALTER TABLE ADD CONSTRAINT, so we must recreate the table.
+
+-- Step 1: Create new table with the FK constraint
+CREATE TABLE discussions_new (
+    id INTEGER PRIMARY KEY,
+    gitlab_discussion_id TEXT NOT NULL,
+    project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    issue_id INTEGER REFERENCES issues(id) ON DELETE CASCADE,
+    merge_request_id INTEGER REFERENCES merge_requests(id) ON DELETE CASCADE,  -- FK was missing!
+    noteable_type TEXT NOT NULL CHECK (noteable_type IN ('Issue', 'MergeRequest')),
+    individual_note INTEGER NOT NULL DEFAULT 0,
+    first_note_at INTEGER,
+    last_note_at INTEGER,
+    last_seen_at INTEGER NOT NULL,
+    resolvable INTEGER NOT NULL DEFAULT 0,
+    resolved INTEGER NOT NULL DEFAULT 0,
+    raw_payload_id INTEGER REFERENCES raw_payloads(id),  -- Added in migration 004
+    CHECK (
+        (noteable_type = 'Issue' AND issue_id IS NOT NULL AND merge_request_id IS NULL) OR
+        (noteable_type = 'MergeRequest' AND merge_request_id IS NOT NULL AND issue_id IS NULL)
+    )
+);
+
+-- Step 2: Copy data (only rows with valid FK references to avoid constraint violations)
+INSERT INTO discussions_new
+SELECT d.* FROM discussions d
+WHERE (d.merge_request_id IS NULL OR EXISTS (SELECT 1 FROM merge_requests m WHERE m.id = d.merge_request_id));
+
+-- Step 3: Drop old table and rename
+DROP TABLE discussions;
+ALTER TABLE discussions_new RENAME TO discussions;
+
+-- Step 4: Recreate ALL indexes that were on the discussions table
+-- From migration 002 (original table)
+CREATE UNIQUE INDEX uq_discussions_project_discussion_id ON discussions(project_id, gitlab_discussion_id);
+CREATE INDEX idx_discussions_issue ON discussions(issue_id);
+CREATE INDEX idx_discussions_mr ON discussions(merge_request_id);
+CREATE INDEX idx_discussions_last_note ON discussions(last_note_at);
+-- From migration 003 (orphan detection)
+CREATE INDEX idx_discussions_last_seen ON discussions(last_seen_at);
+-- From migration 006 (MR indexes)
+CREATE INDEX idx_discussions_mr_id ON discussions(merge_request_id);
+CREATE INDEX idx_discussions_mr_resolved ON discussions(merge_request_id, resolved, resolvable);
+-- From migration 017 (who command indexes)
+CREATE INDEX idx_discussions_unresolved_recent ON discussions(project_id, last_note_at) WHERE resolvable = 1 AND resolved = 0;
+CREATE INDEX idx_discussions_unresolved_recent_global ON discussions(last_note_at) WHERE resolvable = 1 AND resolved = 0;
+-- From migration 019 (list performance)
+CREATE INDEX idx_discussions_issue_resolved ON discussions(issue_id, resolvable, resolved);
+-- From migration 022 (notes query optimization)
+CREATE INDEX idx_discussions_issue_id ON discussions(issue_id);
+
+-- Record migration
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (28, strftime('%s', 'now') * 1000, 'Add FK constraint on discussions.merge_request_id');

plans/asupersync-migration.md

@@ -0,0 +1,867 @@
+# Plan: Replace Tokio + Reqwest with Asupersync
+
+**Date:** 2026-03-06
+**Status:** Draft
+**Decisions:** Adapter layer (yes), timeouts in adapter, deep Cx threading, reference doc only
+
+---
+
+## Context
+
+Gitlore uses tokio as its async runtime and reqwest as its HTTP client. Both work, but:
+
+- Ctrl+C during `join_all` silently drops in-flight HTTP requests with no cleanup
+- `ShutdownSignal` is a hand-rolled `AtomicBool` with no structured cancellation
+- No deterministic testing for concurrent ingestion patterns
+- tokio provides no structured concurrency guarantees
+
+Asupersync is a cancel-correct async runtime with region-owned tasks, obligation tracking, and deterministic lab testing. Replacing tokio+reqwest gives us structured shutdown, cancel-correct ingestion, and testable concurrency.
+
+**Trade-offs accepted:**
+- Nightly Rust required (asupersync dependency)
+- Pre-1.0 runtime dependency (mitigated by adapter layer + version pinning)
+- Deeper function signature changes for Cx threading
+
+### Why not tokio CancellationToken + JoinSet?
+
+The core problems (Ctrl+C drops requests, no structured cancellation) *can* be fixed without replacing the runtime. Tokio's `CancellationToken` + `JoinSet` + explicit task tracking gives structured cancellation for fan-out patterns. This was considered and rejected for two reasons:
+
+1. **Obligation tracking is the real win.** CancellationToken/JoinSet fix the "cancel cleanly" problem but don't give us obligation tracking (compile-time proof that all spawned work is awaited) or deterministic lab testing. These are the features that prevent *future* concurrency bugs, not just the current Ctrl+C issue.
+2. **Separation of concerns.** Fixing Ctrl+C with tokio primitives first, then migrating the runtime second, doubles the migration effort (rewrite fan-out twice). Since we have no users and no backwards compatibility concerns, a single clean migration is lower total cost.
+
+If asupersync proves unviable (nightly breakage, API instability), the fallback is exactly this: tokio + CancellationToken + JoinSet.
+
+---
+
+## Current Tokio Usage Inventory
+
+### Production code (must migrate)
+
+| Location | API | Purpose |
+|----------|-----|---------|
+| `main.rs:53` | `#[tokio::main]` | Runtime entrypoint |
+| `main.rs` (4 sites) | `tokio::spawn` + `tokio::signal::ctrl_c` | Ctrl+C signal handlers |
+| `gitlab/client.rs:9` | `tokio::sync::Mutex` | Rate limiter lock |
+| `gitlab/client.rs:10` | `tokio::time::sleep` | Rate limiter backoff |
+| `gitlab/client.rs:729,736` | `tokio::join!` | Parallel pagination |
+
+### Production code (reqwest -- must replace)
+
+| Location | Usage |
+|----------|-------|
+| `gitlab/client.rs` | REST API: GET with headers/query, response status/headers/JSON, pagination via x-next-page and Link headers, retry on 429 |
+| `gitlab/graphql.rs` | GraphQL: POST with Bearer auth + JSON body, response JSON parsing |
+| `embedding/ollama.rs` | Ollama: GET health check, POST JSON embedding requests |
+
+### Test code (keep on tokio via dev-dep)
+
+| File | Tests | Uses wiremock? |
+|------|-------|----------------|
+| `gitlab/graphql_tests.rs` | 30 | Yes |
+| `gitlab/client_tests.rs` | 4 | Yes |
+| `embedding/pipeline_tests.rs` | 4 | Yes |
+| `ingestion/surgical_tests.rs` | 4 async | Yes |
+
+### Test code (switch to asupersync)
+
+| File | Tests | Why safe |
+|------|-------|----------|
+| `core/timeline_seed_tests.rs` | 13 | Pure CPU/SQLite, no HTTP, no tokio APIs |
+
+### Test code (already sync `#[test]` -- no changes)
+
+~35 test files across documents/, core/, embedding/, gitlab/transformers/, ingestion/, cli/commands/, tests/
+
+---
+
+## Phase 0: Preparation (no runtime change)
+
+Goal: Reduce tokio surface area before the swap. Each step is independently valuable.
+
+### 0a. Extract signal handler
+
+The 4 identical Ctrl+C handlers in `main.rs` (lines 1020, 2341, 2493, 2524) become one function in `core/shutdown.rs`:
+
+```rust
+pub fn install_ctrl_c_handler(signal: ShutdownSignal) {
+    tokio::spawn(async move {
+        let _ = tokio::signal::ctrl_c().await;
+        eprintln!("\nInterrupted, finishing current batch... (Ctrl+C again to force quit)");
+        signal.cancel();
+        let _ = tokio::signal::ctrl_c().await;
+        std::process::exit(130);
+    });
+}
+```
+
+4 spawn sites -> 1 function. The function body changes in Phase 3.
+
+### 0b. Replace tokio::sync::Mutex with std::sync::Mutex
+
+In `gitlab/client.rs`, the rate limiter lock guards a tiny sync critical section (check `Instant::now()`, compute delay). No async work inside the lock. `std::sync::Mutex` is correct and removes a tokio dependency:
+
+```rust
+// Before
+use tokio::sync::Mutex;
+let delay = self.rate_limiter.lock().await.check_delay();
+
+// After
+use std::sync::Mutex;
+let delay = self.rate_limiter.lock().expect("rate limiter poisoned").check_delay();
+```
+
+Note: `.expect()` over `.unwrap()` for clarity. Poisoning is near-impossible here (the critical section is a trivial `Instant::now()` check), but the explicit message aids debugging if it ever fires.
+
+**Contention constraint:** `std::sync::Mutex` blocks the executor thread while held. This is safe *only* because the critical section is a single `Instant::now()` comparison with no I/O. If the rate limiter ever grows to include async work (HTTP calls, DB queries), it must move back to an async-aware lock. Document this constraint with a comment at the lock site.
+
+### 0c. Replace tokio::join! with futures::join!
+
+In `gitlab/client.rs:729,736`. `futures::join!` is runtime-agnostic and already in deps.
+
+**After Phase 0, remaining tokio in production code:**
+- `#[tokio::main]` (1 site)
+- `tokio::spawn` + `tokio::signal::ctrl_c` (1 function)
+- `tokio::time::sleep` (1 import)
+
+---
+
+## Phase 0d: Error Type Migration (must precede adapter layer)
+
+The adapter layer (Phase 1) uses `GitLabNetworkError { detail: Option<String> }`, which requires this error type change before the adapter compiles. Placed here so Phases 1-3 compile as a unit.
+
+### `src/core/error.rs`
+
+```rust
+// Remove:
+#[error("HTTP error: {0}")]
+Http(#[from] reqwest::Error),
+
+// Change:
+#[error("Cannot connect to GitLab at {base_url}")]
+GitLabNetworkError {
+    base_url: String,
+    // Before: source: Option<reqwest::Error>
+    // After:
+    detail: Option<String>,
+},
+```
+
+The adapter layer stringifies HTTP client errors at the boundary so `LoreError` doesn't depend on any HTTP client's error types. This also means the existing reqwest call sites that construct `GitLabNetworkError` must be updated to pass `detail: Some(format!("{e:?}"))` instead of `source: Some(e)` -- but those sites are rewritten in Phase 2 anyway, so no extra work.
+
+**Note on error granularity:** Flattening all HTTP errors to `detail: Option<String>` loses the distinction between timeouts, TLS failures, DNS resolution failures, and connection resets. To preserve actionable error categories without coupling `LoreError` to any HTTP client, add a lightweight `NetworkErrorKind` enum:
+
+```rust
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum NetworkErrorKind {
+    Timeout,
+    ConnectionRefused,
+    DnsResolution,
+    Tls,
+    Other,
+}
+
+#[error("Cannot connect to GitLab at {base_url}")]
+GitLabNetworkError {
+    base_url: String,
+    kind: NetworkErrorKind,
+    detail: Option<String>,
+},
+```
+
+The adapter's `execute()` method classifies errors at the boundary:
+- Timeout from `asupersync::time::timeout` → `NetworkErrorKind::Timeout`
+- Transport errors from the HTTP client → classified by error type into the appropriate kind
+- Unknown errors → `NetworkErrorKind::Other`
+
+This keeps `LoreError` client-agnostic while preserving the ability to make retry decisions based on error *type* (e.g., retry on timeout but not on TLS). The adapter's `execute()` method is the single place where this mapping happens, so adding new kinds is localized.
+
+---
+
+## Phase 1: Build the HTTP Adapter Layer
+
+### Why
+
+Asupersync's `HttpClient` is lower-level than reqwest:
+- Headers: `Vec<(String, String)>` not typed `HeaderMap`/`HeaderValue`
+- Body: `Vec<u8>` not a builder with `.json()`
+- Status: raw `u16` not `StatusCode` enum
+- Response: body already buffered, no async `.json().await`
+- No per-request timeout
+
+Without an adapter, every call site becomes 5-6 lines of boilerplate. The adapter also isolates gitlore from asupersync's pre-1.0 HTTP API.
+
+### New file: `src/http.rs` (~100 LOC)
+
+```rust
+use asupersync::http::h1::{HttpClient, HttpClientConfig, PoolConfig};
+use asupersync::http::h1::types::Method;
+use asupersync::time::timeout;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use std::time::Duration;
+
+use crate::core::error::{LoreError, Result};
+
+pub struct Client {
+    inner: HttpClient,
+    timeout: Duration,
+}
+
+pub struct Response {
+    pub status: u16,
+    pub reason: String,
+    pub headers: Vec<(String, String)>,
+    body: Vec<u8>,
+}
+
+impl Client {
+    pub fn with_timeout(timeout: Duration) -> Self {
+        Self {
+            inner: HttpClient::with_config(HttpClientConfig {
+                pool_config: PoolConfig::builder()
+                    .max_connections_per_host(6)
+                    .max_total_connections(100)
+                    .idle_timeout(Duration::from_secs(90))
+                    .build(),
+                ..Default::default()
+            }),
+            timeout,
+        }
+    }
+
+    pub async fn get(&self, url: &str, headers: &[(&str, &str)]) -> Result<Response> {
+        self.execute(Method::Get, url, headers, Vec::new()).await
+    }
+
+    pub async fn get_with_query(
+        &self,
+        url: &str,
+        params: &[(&str, String)],
+        headers: &[(&str, &str)],
+    ) -> Result<Response> {
+        let full_url = append_query_params(url, params);
+        self.execute(Method::Get, &full_url, headers, Vec::new()).await
+    }
+
+    pub async fn post_json<T: Serialize>(
+        &self,
+        url: &str,
+        headers: &[(&str, &str)],
+        body: &T,
+    ) -> Result<Response> {
+        let body_bytes = serde_json::to_vec(body)
+            .map_err(|e| LoreError::Other(format!("JSON serialization failed: {e}")))?;
+        let mut all_headers = headers.to_vec();
+        all_headers.push(("Content-Type", "application/json"));
+        self.execute(Method::Post, url, &all_headers, body_bytes).await
+    }
+
+    async fn execute(
+        &self,
+        method: Method,
+        url: &str,
+        headers: &[(&str, &str)],
+        body: Vec<u8>,
+    ) -> Result<Response> {
+        let header_tuples: Vec<(String, String)> = headers
+            .iter()
+            .map(|(k, v)| ((*k).to_owned(), (*v).to_owned()))
+            .collect();
+
+        let raw = timeout(self.timeout, self.inner.request(method, url, header_tuples, body))
+            .await
+            .map_err(|_| LoreError::GitLabNetworkError {
+                base_url: url.to_string(),
+                kind: NetworkErrorKind::Timeout,
+                detail: Some(format!("Request timed out after {:?}", self.timeout)),
+            })?
+            .map_err(|e| LoreError::GitLabNetworkError {
+                base_url: url.to_string(),
+                kind: classify_transport_error(&e),
+                detail: Some(format!("{e:?}")),
+            })?;
+
+        Ok(Response {
+            status: raw.status,
+            reason: raw.reason,
+            headers: raw.headers,
+            body: raw.body,
+        })
+    }
+}
+
+impl Response {
+    pub fn is_success(&self) -> bool {
+        (200..300).contains(&self.status)
+    }
+
+    pub fn json<T: DeserializeOwned>(&self) -> Result<T> {
+        serde_json::from_slice(&self.body)
+            .map_err(|e| LoreError::Other(format!("JSON parse error: {e}")))
+    }
+
+    pub fn text(self) -> Result<String> {
+        String::from_utf8(self.body)
+            .map_err(|e| LoreError::Other(format!("UTF-8 decode error: {e}")))
+    }
+
+    pub fn header(&self, name: &str) -> Option<&str> {
+        self.headers
+            .iter()
+            .find(|(k, _)| k.eq_ignore_ascii_case(name))
+            .map(|(_, v)| v.as_str())
+    }
+
+    /// Returns all values for a header name (case-insensitive).
+    /// Needed for multi-value headers like `Link` used in pagination.
+    pub fn headers_all(&self, name: &str) -> Vec<&str> {
+        self.headers
+            .iter()
+            .filter(|(k, _)| k.eq_ignore_ascii_case(name))
+            .map(|(_, v)| v.as_str())
+            .collect()
+    }
+}
+
+/// Appends query parameters to a URL.
+///
+/// Edge cases handled:
+/// - URLs with existing `?query` → appends with `&`
+/// - URLs with `#fragment` → inserts query before fragment
+/// - Empty params → returns URL unchanged
+/// - Repeated keys → preserved as-is (GitLab API uses repeated `labels[]`)
+fn append_query_params(url: &str, params: &[(&str, String)]) -> String {
+    if params.is_empty() {
+        return url.to_string();
+    }
+    let query: String = params
+        .iter()
+        .map(|(k, v)| format!("{}={}", urlencoding::encode(k), urlencoding::encode(v)))
+        .collect::<Vec<_>>()
+        .join("&");
+
+    // Preserve URL fragments: split on '#', insert query, rejoin
+    let (base, fragment) = match url.split_once('#') {
+        Some((b, f)) => (b, Some(f)),
+        None => (url, None),
+    };
+    let with_query = if base.contains('?') {
+        format!("{base}&{query}")
+    } else {
+        format!("{base}?{query}")
+    };
+    match fragment {
+        Some(f) => format!("{with_query}#{f}"),
+        None => with_query,
+    }
+}
+```
+
+### Response body size guard
+
+The adapter buffers entire response bodies in memory (`Vec<u8>`). A misconfigured endpoint or unexpected redirect to a large file could cause unbounded memory growth. Add a max response body size check in `execute()`:
+
+```rust
+const MAX_RESPONSE_BODY_BYTES: usize = 64 * 1024 * 1024; // 64 MiB — generous for JSON, catches runaways
+
+// In execute(), after receiving raw response:
+if raw.body.len() > MAX_RESPONSE_BODY_BYTES {
+    return Err(LoreError::Other(format!(
+        "Response body too large: {} bytes (max {})",
+        raw.body.len(),
+        MAX_RESPONSE_BODY_BYTES,
+    )));
+}
+```
+
+This is a safety net, not a tight constraint. GitLab JSON responses are typically < 1 MiB. Ollama embedding responses are < 100 KiB per batch. The 64 MiB limit catches runaways without interfering with normal operation.
+
+### Timeout behavior
+
+Every request is wrapped with `asupersync::time::timeout(self.timeout, ...)`. Default timeouts:
+- GitLab REST/GraphQL: 30s
+- Ollama: configurable (default 60s)
+- Ollama health check: 5s
+
+---
+
+## Phase 2: Migrate the 3 HTTP Modules
+
+### 2a. `gitlab/client.rs` (REST API)
+
+**Imports:**
+```rust
+// Remove
+use reqwest::header::{ACCEPT, HeaderMap, HeaderValue};
+use reqwest::{Client, Response, StatusCode};
+
+// Add
+use crate::http::{Client, Response};
+```
+
+**Client construction** (lines 68-96):
+```rust
+// Before: reqwest::Client::builder().default_headers(h).timeout(d).build()
+// After:
+let client = Client::with_timeout(Duration::from_secs(30));
+```
+
+**request() method** (lines 129-170):
+```rust
+// Before
+let response = self.client.get(&url)
+    .header("PRIVATE-TOKEN", &self.token)
+    .send().await
+    .map_err(|e| LoreError::GitLabNetworkError { ... })?;
+
+// After
+let response = self.client.get(&url, &[
+    ("PRIVATE-TOKEN", &self.token),
+    ("Accept", "application/json"),
+]).await?;
+```
+
+**request_with_headers() method** (lines 510-559):
+```rust
+// Before
+let response = self.client.get(&url)
+    .query(params)
+    .header("PRIVATE-TOKEN", &self.token)
+    .send().await?;
+let headers = response.headers().clone();
+
+// After
+let response = self.client.get_with_query(&url, params, &[
+    ("PRIVATE-TOKEN", &self.token),
+    ("Accept", "application/json"),
+]).await?;
+// headers already owned in response.headers
+```
+
+**handle_response()** (lines 182-219):
+```rust
+// Before: async fn (consumed body with .text().await)
+// After: sync fn (body already buffered in Response)
+fn handle_response<T: DeserializeOwned>(&self, response: Response, path: &str) -> Result<T> {
+    match response.status {
+        401 => Err(LoreError::GitLabAuthFailed),
+        404 => Err(LoreError::GitLabNotFound { resource: path.into() }),
+        429 => {
+            let retry_after = response.header("retry-after")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(60);
+            Err(LoreError::GitLabRateLimited { retry_after })
+        }
+        s if (200..300).contains(&s) => response.json::<T>(),
+        s => Err(LoreError::Other(format!("GitLab API error: {} {}", s, response.reason))),
+    }
+}
+```
+
+**Pagination** -- No structural changes. `async_stream::stream!` and header parsing stay the same. Only the response type changes:
+```rust
+// Before: headers.get("x-next-page").and_then(|v| v.to_str().ok())
+// After:  response.header("x-next-page")
+```
+
+**parse_link_header_next** -- Change signature from `(headers: &HeaderMap)` to `(headers: &[(String, String)])` and find by case-insensitive name.
+
+### 2b. `gitlab/graphql.rs`
+
+```rust
+// Before
+let response = self.http.post(&url)
+    .header("Authorization", format!("Bearer {}", self.token))
+    .header("Content-Type", "application/json")
+    .json(&body).send().await?;
+let json: Value = response.json().await?;
+
+// After
+let bearer = format!("Bearer {}", self.token);
+let response = self.http.post_json(&url, &[
+    ("Authorization", &bearer),
+], &body).await?;
+let json: Value = response.json()?;
+```
+
+Status matching changes from `response.status().as_u16()` to `response.status` (already u16).
+
+### 2c. `embedding/ollama.rs`
+
+```rust
+// Health check
+let response = self.client.get(&url, &[]).await?;
+let tags: TagsResponse = response.json()?;
+
+// Embed batch
+let response = self.client.post_json(&url, &[], &request).await?;
+if !response.is_success() {
+    let status = response.status; // capture before .text() consumes response
+    let body = response.text()?;
+    return Err(LoreError::EmbeddingFailed { document_id: 0, reason: format!("HTTP {status}: {body}") });
+}
+let embed_response: EmbedResponse = response.json()?;
+```
+
+**Standalone health check** (`check_ollama_health`): Currently creates a temporary `reqwest::Client`. Replace with temporary `crate::http::Client`:
+```rust
+pub async fn check_ollama_health(base_url: &str) -> bool {
+    let client = Client::with_timeout(Duration::from_secs(5));
+    let url = format!("{base_url}/api/tags");
+    client.get(&url, &[]).await.map_or(false, |r| r.is_success())
+}
+```
+
+---
+
+## Phase 3: Swap the Runtime + Deep Cx Threading
+
+### 3a. Cargo.toml
+
+```toml
+[dependencies]
+# Remove:
+# reqwest = { version = "0.12", features = ["json"] }
+# tokio = { version = "1", features = ["rt-multi-thread", "macros", "time", "signal"] }
+
+# Add:
+asupersync = { version = "0.2", features = ["tls", "tls-native-roots"] }
+
+# Keep unchanged:
+async-stream = "0.3"
+futures = { version = "0.3", default-features = false, features = ["alloc"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+urlencoding = "2"
+
+[dev-dependencies]
+tempfile = "3"
+wiremock = "0.6"
+tokio = { version = "1", features = ["rt", "macros"] }
+```
+
+### 3b. rust-toolchain.toml
+
+```toml
+[toolchain]
+channel = "nightly-2026-03-01"  # Pin specific date to avoid surprise breakage
+```
+
+Update the date as needed when newer nightlies are verified. Never use bare `"nightly"` in production.
+
+### 3c. Entrypoint (`main.rs:53`)
+
+```rust
+// Before
+#[tokio::main]
+async fn main() -> Result<()> { ... }
+
+// After
+#[asupersync::main]
+async fn main(cx: &Cx) -> Outcome<()> { ... }
+```
+
+### 3d. Signal handler (`core/shutdown.rs`)
+
+```rust
+// After (Phase 0 extracted it; now rewrite for asupersync)
+pub async fn install_ctrl_c_handler(cx: &Cx, signal: ShutdownSignal) {
+    cx.spawn("ctrl-c-handler", async move |cx| {
+        cx.shutdown_signal().await;
+        eprintln!("\nInterrupted, finishing current batch... (Ctrl+C again to force quit)");
+        signal.cancel();
+        // Preserve hard-exit on second Ctrl+C (same behavior as Phase 0a)
+        cx.shutdown_signal().await;
+        std::process::exit(130);
+    });
+}
+```
+
+**Cleanup concern:** `std::process::exit(130)` on second Ctrl+C bypasses all drop guards, flush operations, and asupersync region cleanup. This is intentional (user demanded hard exit) but means any in-progress DB transaction will be abandoned mid-write. SQLite's journaling makes this safe (uncommitted transactions are rolled back on next open), but verify this holds for WAL mode if enabled. Consider logging a warning before exit so users understand incomplete operations may need re-sync.
+
+### 3e. Rate limiter sleep
+
+```rust
+// Before
+use tokio::time::sleep;
+
+// After
+use asupersync::time::sleep;
+```
+
+### 3f. Deep Cx threading
+
+Thread `Cx` from `main()` through command dispatch into the orchestrator and ingestion modules. This enables region-scoped cancellation for `join_all` batches.
+
+**Function signatures that need `cx: &Cx` added:**
+
+| Module | Functions |
+|--------|-----------|
+| `main.rs` | Command dispatch match arms for `sync`, `ingest`, `embed` |
+| `cli/commands/sync.rs` | `run_sync()` |
+| `cli/commands/ingest.rs` | `run_ingest_command()`, `run_ingest()` |
+| `cli/commands/embed.rs` | `run_embed()` |
+| `cli/commands/sync_surgical.rs` | `run_sync_surgical()` |
+| `ingestion/orchestrator.rs` | `ingest_issues()`, `ingest_merge_requests()`, `ingest_discussions()`, etc. |
+| `ingestion/surgical.rs` | `surgical_sync()` |
+| `embedding/pipeline.rs` | `embed_documents()`, `embed_batch_group()` |
+
+**Region wrapping for join_all batches** (orchestrator.rs):
+```rust
+// Before
+let prefetched_batch = join_all(prefetch_futures).await;
+
+// After -- cancel-correct region with result collection
+let (tx, rx) = std::sync::mpsc::channel();
+cx.region(|scope| async {
+    for future in prefetch_futures {
+        let tx = tx.clone();
+        scope.spawn(async move |_cx| {
+            let result = future.await;
+            let _ = tx.send(result);
+        });
+    }
+    drop(tx);
+}).await;
+let prefetched_batch: Vec<_> = rx.into_iter().collect();
+```
+
+**IMPORTANT: Semantic differences beyond ordering.** Replacing `join_all` with region-spawned tasks changes three behaviors:
+
+1. **Ordering:** `join_all` preserves input order — results\[i\] corresponds to futures\[i\]. The `std::sync::mpsc` channel pattern does NOT (results arrive in completion order). If downstream logic assumes positional alignment (e.g., zipping results with input items by index), this is a silent correctness bug. Options:
+   - Send `(index, result)` tuples through the channel and sort by index after collection.
+   - If `scope.spawn()` returns a `JoinHandle<T>`, collect handles in order and await them sequentially.
+
+2. **Error aggregation:** `join_all` runs all futures to completion even if some fail, collecting all results. Region-spawned tasks with a channel will also run all tasks, but if the region is cancelled mid-flight (e.g., Ctrl+C), some results are lost. Decide per call site: should partial results be processed, or should the entire batch be retried?
+
+3. **Backpressure:** `join_all` with N futures creates N concurrent tasks. Region-spawned tasks behave similarly, but if the region has concurrency limits, backpressure semantics change. Verify asupersync's region API does not impose implicit concurrency caps.
+
+4. **Late result loss on cancellation:** When a region is cancelled, tasks that have completed but whose results haven't been received yet may have already sent to the channel. However, tasks that are mid-flight will be dropped, and their results never sent. The channel receiver must drain whatever was sent, but the caller must treat a cancelled region's results as incomplete — never assume all N results arrived. Document per call site whether partial results are safe to process or whether the entire batch should be discarded on cancellation.
+
+Audit every `join_all` call site for all four assumptions before choosing the pattern.
+
+Note: The exact result-collection pattern depends on asupersync's region API. If `scope.spawn()` returns a `JoinHandle<T>`, prefer collecting handles and awaiting them (preserves ordering and simplifies error handling).
+
+This is the biggest payoff: if Ctrl+C fires during a prefetch batch, the region cancels all in-flight HTTP requests with bounded cleanup instead of silently dropping them.
+
+**Estimated signature changes:** ~15 functions gain a `cx: &Cx` parameter.
+
+**Phasing the Cx threading (risk reduction):** Rather than threading `cx` through all ~15 functions at once, split into two steps:
+
+- **Step 1:** Thread `cx` through the orchestration path only (`main.rs` dispatch → `run_sync`/`run_ingest` → orchestrator functions). This is where region-wrapping `join_all` batches happens — the actual cancellation payoff. Verify invariants pass.
+- **Step 2:** Widen to the command layer and embedding pipeline (`run_embed`, `embed_documents`, `embed_batch_group`, `sync_surgical`). These are lower-risk since they don't have the same fan-out patterns.
+
+This reduces the blast radius of Step 1 and provides an earlier validation checkpoint. If Step 1 surfaces problems, Step 2 hasn't been started yet.
+
+---
+
+## Phase 4: Test Migration
+
+### Keep on `#[tokio::test]` (wiremock tests -- 42 tests)
+
+No changes. `tokio` is in `[dev-dependencies]` with `features = ["rt", "macros"]`.
+
+**Coverage gap:** These tests validate protocol correctness (request format, response parsing, status code handling, pagination) through the adapter layer, but they do NOT exercise asupersync's runtime behavior (timeouts, connection pooling, cancellation). This is acceptable because:
+1. Protocol correctness is the higher-value test target — it catches most regressions
+2. Runtime-specific behavior is covered by the new cancellation integration tests (below)
+3. The adapter layer is thin enough that runtime differences are unlikely to affect request/response semantics
+
+**Adapter-layer test gap:** The 42 wiremock tests validate protocol correctness (request format, response parsing) but run on tokio, not asupersync. This means the adapter's actual behavior under the production runtime is untested by mocked-response tests. To close this gap, add 3-5 asupersync-native integration tests that exercise the adapter against a simple HTTP server (e.g., `hyper` or a raw TCP listener) rather than wiremock:
+
+1. **GET with headers + JSON response** — verify header passing and JSON deserialization through the adapter.
+2. **POST with JSON body** — verify Content-Type injection and body serialization.
+3. **429 + Retry-After** — verify the adapter surfaces rate-limit responses correctly.
+4. **Timeout** — verify the adapter's `asupersync::time::timeout` wrapper fires.
+5. **Large response rejection** — verify the body size guard triggers.
+
+These tests are cheap to write (~50 LOC each) and close the "works on tokio but does it work on asupersync?" gap that GPT 5.3 flagged.
+
+| File | Tests |
+|------|-------|
+| `gitlab/graphql_tests.rs` | 30 |
+| `gitlab/client_tests.rs` | 4 |
+| `embedding/pipeline_tests.rs` | 4 |
+| `ingestion/surgical_tests.rs` | 4 |
+
+### Switch to `#[asupersync::test]` (no wiremock -- 13 tests)
+
+| File | Tests |
+|------|-------|
+| `core/timeline_seed_tests.rs` | 13 |
+
+### Already `#[test]` (sync -- ~35 files)
+
+No changes needed.
+
+### New: Cancellation integration tests (asupersync-native)
+
+Wiremock tests on tokio validate protocol/serialization correctness but cannot test asupersync's cancellation and region semantics. Add asupersync-native integration tests for:
+
+1. **Ctrl+C during fan-out:** Simulate cancellation mid-batch in orchestrator. Verify all in-flight tasks are drained, no task leaks, no obligation leaks.
+2. **Region quiescence:** Verify that after a region completes (normal or cancelled), no background tasks remain running.
+3. **Transaction integrity under cancellation:** Cancel during an ingestion batch that has fetched data but not yet written to DB. Verify no partial data is committed.
+
+These tests use asupersync's deterministic lab runtime, which is one of the primary motivations for this migration.
+
+---
+
+## Phase 5: Verify and Harden
+
+### Verification checklist
+
+```bash
+cargo check --all-targets
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+cargo test
+```
+
+### Specific things to verify
+
+1. **async-stream on nightly** -- Does `async_stream 0.3` compile on current nightly?
+2. **TLS root certs on macOS** -- Does `tls-native-roots` pick up system CA certs?
+3. **Connection pool under concurrency** -- Do `join_all` batches (4-8 concurrent requests to same host) work without pool deadlock?
+4. **Pagination streams** -- Do `async_stream::stream!` pagination generators work unchanged?
+5. **Wiremock test isolation** -- Do wiremock tests pass with tokio only in dev-deps?
+
+### HTTP behavior parity acceptance criteria
+
+reqwest provides several implicit behaviors that asupersync's h1 client may not. Each must pass a concrete acceptance test before the migration is considered complete:
+
+| reqwest default | Acceptance criterion | Pass/Fail test |
+|-----------------|---------------------|----------------|
+| Automatic redirect following (up to 10) | If GitLab returns 3xx, gitlore must not silently lose the response. Either follow the redirect or surface a clear error. | Send a request to wiremock returning 301 → verify adapter returns the redirect status (not an opaque failure) |
+| Automatic gzip/deflate decompression | Not required — JSON responses are small. | N/A (no test needed) |
+| Proxy from `HTTP_PROXY`/`HTTPS_PROXY` env | If `HTTP_PROXY` is set, requests must route through it. If asupersync lacks proxy support, document this as a known limitation. | Set `HTTP_PROXY=http://127.0.0.1:9999` → verify connection attempt targets the proxy, or document that proxy is unsupported |
+| Connection keep-alive | Pagination batches (4-8 sequential requests to same host) must reuse connections. | Measure with `ss`/`netstat`: 8 paginated requests should use ≤2 TCP connections |
+| System DNS resolution | Hostnames must resolve via OS resolver. | Verify `lore sync` works against a hostname (not just IP) |
+| Request body Content-Length | POST requests must include Content-Length header (some proxies/WAFs require it). | Inspect outgoing request headers in wiremock test |
+| TLS certificate validation | HTTPS requests must validate server certificates using system CA store. | Verify `lore sync` succeeds against production GitLab (valid cert) and fails against self-signed cert |
+
+### Cancellation + DB transaction invariants
+
+Region-based cancellation stops HTTP tasks cleanly, but partial ingestion can leave the database in an inconsistent state if cancellation fires between "fetched data" and "wrote to DB". The following invariants must hold and be tested:
+
+**INV-1: Atomic batch writes.** Each ingestion batch (issues, MRs, discussions) writes to the DB inside a single `unchecked_transaction()`. If the transaction is not committed, no partial data from that batch is visible. This is already the case for most ingestion paths — audit all paths and fix any that write outside a transaction.
+
+**INV-2: Region cancellation cannot corrupt committed data.** A cancelled region may abandon in-flight HTTP requests, but it must not interrupt a DB transaction mid-write. This holds naturally because SQLite transactions are synchronous (not async) — once `tx.execute()` starts, it runs to completion on the current thread regardless of task cancellation. Verify this assumption holds for WAL mode.
+
+**Hard rule: no `.await` between transaction open and commit/rollback.** Cancellation can fire at any `.await` point. If an `.await` exists between `unchecked_transaction()` and `tx.commit()`, a cancelled region could drop the transaction guard mid-batch, rolling back partial writes silently. Audit all ingestion paths to confirm this invariant holds. If any path must do async work mid-transaction (e.g., fetching related data), restructure to fetch-then-write: complete all async work first, then open the transaction, write synchronously, and commit.
+
+**INV-3: No partial batch visibility.** If cancellation fires after fetching N items but before the batch transaction commits, zero items from that batch are persisted. The next sync picks up where it left off using cursor-based pagination.
+
+**INV-4: ShutdownSignal + region cancellation are complementary.** The existing `ShutdownSignal` check-before-write pattern in orchestrator loops (`if signal.is_cancelled() { break; }`) remains the first line of defense. Region cancellation is the second — it ensures in-flight HTTP tasks are drained even if the orchestrator loop has already moved past the signal check. Both mechanisms must remain active.
+
+**Test plan for invariants:**
+- INV-1: Cancellation integration test — cancel mid-batch, verify DB has zero partial rows from that batch
+- INV-2: Verify `unchecked_transaction()` commit is not interruptible by task cancellation (lab runtime test)
+- INV-3: Cancel after fetch, re-run sync, verify no duplicates and no gaps
+- INV-4: Verify both ShutdownSignal and region cancellation are triggered on Ctrl+C
+
+---
+
+## File Change Summary
+
+| File | Change | LOC |
+|------|--------|-----|
+| `Cargo.toml` | Swap deps | ~10 |
+| `rust-toolchain.toml` | NEW -- set nightly | 3 |
+| `src/http.rs` | NEW -- adapter layer | ~100 |
+| `src/main.rs` | Entrypoint macro, Cx threading, remove 4 signal handlers | ~40 |
+| `src/core/shutdown.rs` | Extract + rewrite signal handler | ~20 |
+| `src/core/error.rs` | Remove reqwest::Error, change GitLabNetworkError (Phase 0d) | ~10 |
+| `src/gitlab/client.rs` | Replace reqwest, remove tokio imports, adapt all methods | ~80 |
+| `src/gitlab/graphql.rs` | Replace reqwest | ~20 |
+| `src/embedding/ollama.rs` | Replace reqwest | ~20 |
+| `src/cli/commands/sync.rs` | Add Cx param | ~5 |
+| `src/cli/commands/ingest.rs` | Add Cx param | ~5 |
+| `src/cli/commands/embed.rs` | Add Cx param | ~5 |
+| `src/cli/commands/sync_surgical.rs` | Add Cx param | ~5 |
+| `src/ingestion/orchestrator.rs` | Add Cx param, region-wrap join_all | ~30 |
+| `src/ingestion/surgical.rs` | Add Cx param | ~10 |
+| `src/embedding/pipeline.rs` | Add Cx param | ~10 |
+| `src/core/timeline_seed_tests.rs` | Swap test macro | ~13 |
+
+**Total: ~16 files modified, 1 new file, ~400-500 LOC changed.**
+
+---
+
+## Execution Order
+
+```
+Phase 0a-0c (prep, safe, independent)
+  |
+  v
+Phase 0d (error type migration -- required before adapter compiles)
+  |
+  v
+DECISION GATE: verify nightly + asupersync + tls-native-roots compile AND behavioral smoke tests pass
+  |
+  v
+Phase 1 (adapter layer, compiles but unused) ----+
+  |                                               |
+  v                                               |  These 3 are one
+Phase 2 (migrate 3 HTTP modules to adapter) ------+  atomic commit
+  |                                               |
+  v                                               |
+Phase 3 (swap runtime, Cx threading) ------------+
+  |
+  v
+Phase 4 (test migration)
+  |
+  v
+Phase 5 (verify + harden)
+```
+
+Phase 0a-0c can be committed independently (good cleanup regardless).
+Phase 0d (error types) can also land independently, but MUST precede the adapter layer.
+**Decision gate:** After Phase 0d, create `rust-toolchain.toml` with nightly pin and verify `asupersync = "0.2"` compiles with `tls-native-roots` on macOS. Then run behavioral smoke tests in a throwaway binary or integration test:
+
+1. **TLS validation:** HTTPS GET to a public endpoint (e.g., `https://gitlab.com/api/v4/version`) succeeds with valid cert.
+2. **DNS resolution:** Request using hostname (not IP) resolves correctly.
+3. **Redirect handling:** GET to a 301/302 endpoint — verify the adapter returns the redirect status (not an opaque error) so call sites can decide whether to follow.
+4. **Timeout behavior:** Request to a slow/non-responsive endpoint times out within the configured duration.
+5. **Connection pooling:** 4 sequential requests to the same host reuse connections (verify via debug logging or `ss`/`netstat`).
+
+If compilation fails or any behavioral test reveals a showstopper (e.g., TLS doesn't work on macOS, timeouts don't fire), stop and evaluate the tokio CancellationToken fallback before investing in Phases 1-3.
+
+Compile-only gating is insufficient — this migration's failure modes are semantic (HTTP behavior parity), not just syntactic.
+
+Phases 1-3 must land together (removing reqwest requires both the adapter AND the new runtime).
+Phases 4-5 are cleanup that can be incremental.
+
+---
+
+## Rollback Strategy
+
+If the migration stalls or asupersync proves unviable after partial completion:
+
+- **Phase 0a-0c completed:** No rollback needed. These are independently valuable cleanup regardless of runtime choice.
+- **Phase 0d completed:** `GitLabNetworkError { detail }` is runtime-agnostic. Keep it.
+- **Phases 1-3 partially completed:** These must land atomically. If any phase in 1-3 fails, revert the entire atomic commit. The adapter layer (Phase 1) imports asupersync types, so it cannot exist without the runtime.
+- **Full rollback to tokio:** If asupersync is abandoned entirely, the fallback path is tokio + `CancellationToken` + `JoinSet` (see "Why not tokio CancellationToken + JoinSet?" above). The adapter layer design is still valid — swap `asupersync::http` for `reqwest` behind the same `crate::http::Client` API.
+
+**Decision point:** After Phase 0 is complete, verify asupersync compiles on the pinned nightly with `tls-native-roots` before committing to Phases 1-3. If TLS or nightly issues surface, stop and evaluate the tokio fallback.
+
+**Concrete escape hatch triggers (abandon asupersync, fall back to tokio + CancellationToken + JoinSet):**
+1. **Nightly breakage > 7 days:** If the pinned nightly breaks and no newer nightly restores compilation within 7 days, abort.
+2. **TLS incompatibility:** If `tls-native-roots` cannot validate certificates on macOS (system CA store) and `tls-webpki-roots` also fails, abort.
+3. **API instability:** If asupersync releases a breaking change to `HttpClient`, `region()`, or `Cx` APIs before our migration is complete, evaluate migration cost. If > 2 days of rework, abort.
+4. **Wiremock incompatibility:** If keeping wiremock tests on tokio while production runs asupersync causes test failures or flaky behavior that cannot be resolved in 1 day, abort.
+
+---
+
+## Risks
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| asupersync pre-1.0 API changes | High | Adapter layer isolates call sites. Pin exact version. |
+| Nightly Rust breakage | Medium-High | Pin nightly date in rust-toolchain.toml. CI tests on nightly. Coupling runtime + toolchain migration amplifies risk — escape hatch triggers defined in Rollback Strategy. |
+| TLS cert issues on macOS | Medium | Test early in Phase 5. Fallback: `tls-webpki-roots` (Mozilla bundle). |
+| Connection pool behavior under load | Medium | Stress test with `join_all` of 8+ concurrent requests in Phase 5. |
+| async-stream nightly compat | Low | Widely used crate, likely fine. Fallback: manual Stream impl. |
+| Build time increase | Low | Measure before/after. asupersync may be heavier than tokio. |
+| Reqwest behavioral drift | Medium | reqwest has implicit redirect/proxy/compression handling. Audit each (see Phase 5 table). GitLab API doesn't redirect, so low actual risk. |
+| Partial ingestion on cancel | Medium | Region cancellation can fire between HTTP fetch and DB write. Verify transaction boundaries align with region scope (see Phase 5). |
+| Unbounded response body buffering | Low | Adapter buffers full response bodies. Mitigated by 64 MiB size guard in adapter `execute()`. |
+| Manual URL/header handling correctness | Low-Medium | `append_query_params` and case-insensitive header scans replicate reqwest behavior manually. Mitigated by unit tests for edge cases (existing query params, fragments, repeated keys, case folding). |

plans/gitlab-todos-notifications-integration.md

@@ -0,0 +1,652 @@
+---
+plan: true
+title: "GitLab TODOs Integration"
+status: proposed
+iteration: 4
+target_iterations: 4
+beads_revision: 1
+related_plans: []
+created: 2026-02-23
+updated: 2026-02-26
+audit_revision: 4
+---
+
+# GitLab TODOs Integration
+
+## Summary
+
+Add GitLab TODO support to lore. Todos are fetched during sync, stored locally, and surfaced through a standalone `lore todos` command and integration into the `lore me` dashboard.
+
+**Scope:** Read-only. No mark-as-done operations.
+
+---
+
+## Workflows
+
+### Workflow 1: Morning Triage (Human)
+
+1. User runs `lore me` to see personal dashboard
+2. Summary header shows "5 pending todos" alongside issue/MR counts
+3. Todos section groups items: 2 Assignments, 2 Mentions, 1 Approval Required
+4. User scans Assignments — sees issue #42 assigned by @manager
+5. User runs `lore todos` for full detail with body snippets
+6. User clicks target URL to address highest-priority item
+7. After marking done in GitLab, next `lore sync` removes it locally
+
+### Workflow 2: Agent Polling (Robot Mode)
+
+1. Agent runs `lore --robot health` as pre-flight check
+2. Agent runs `lore --robot me --fields minimal` for dashboard
+3. Agent extracts `pending_todo_count` from summary — if 0, skip todos
+4. If count > 0, agent runs `lore --robot todos`
+5. Agent iterates `data.todos[]`, filtering by `action` type
+6. Agent prioritizes `approval_required` and `build_failed` for immediate attention
+7. Agent logs external todos (`is_external: true`) for manual review
+
+### Workflow 3: Cross-Project Visibility
+
+1. User is mentioned in a project they don't sync (e.g., company-wide repo)
+2. `lore sync` fetches the todo anyway (account-wide fetch)
+3. `lore todos` shows item with `[external]` indicator and project path
+4. User can still click target URL to view in GitLab
+5. Target title may be unavailable — graceful fallback to "Untitled"
+
+---
+
+## Acceptance Criteria
+
+Behavioral contract. Each AC is a single testable statement.
+
+### Storage
+
+| ID | Behavior |
+|----|----------|
+| AC-1 | Todos are persisted locally in SQLite |
+| AC-2 | Each todo is uniquely identified by its GitLab todo ID |
+| AC-3 | Todos from non-synced projects are stored with their project path |
+
+### Sync
+
+| ID | Behavior |
+|----|----------|
+| AC-4 | `lore sync` fetches all pending todos from GitLab |
+| AC-5 | Sync fetches todos account-wide, not per-project |
+| AC-6 | Todos marked done in GitLab are removed locally on next sync |
+| AC-7 | Transient sync errors do not delete valid local todos |
+| AC-8 | `lore sync --no-todos` skips todo fetching |
+| AC-9 | Sync logs todo statistics (fetched, inserted, updated, deleted) |
+
+### `lore todos` Command
+
+| ID | Behavior |
+|----|----------|
+| AC-10 | `lore todos` displays all pending todos |
+| AC-11 | Todos are grouped by action type: Assignments, Mentions, Approvals, Build Issues |
+| AC-12 | Each todo shows: target title, project path, author, age |
+| AC-13 | Non-synced project todos display `[external]` indicator |
+| AC-14 | `lore todos --limit N` limits output to N todos |
+| AC-15 | `lore --robot todos` returns JSON with standard `{ok, data, meta}` envelope |
+| AC-16 | `lore --robot todos --fields minimal` returns reduced field set |
+| AC-17 | `todo` and `td` are recognized as aliases for `todos` |
+
+### `lore me` Integration
+
+| ID | Behavior |
+|----|----------|
+| AC-18 | `lore me` summary includes pending todo count |
+| AC-19 | `lore me` includes a todos section in the full dashboard |
+| AC-20 | `lore me --todos` shows only the todos section |
+| AC-21 | Todos are NOT filtered by `--project` flag (always account-wide) |
+| AC-22 | Warning is displayed if `--project` is passed with `--todos` |
+| AC-23 | Todo events appear in the activity feed for local entities |
+
+### Action Types
+
+| ID | Behavior |
+|----|----------|
+| AC-24 | Core actions are displayed: assigned, mentioned, directly_addressed, approval_required, build_failed, unmergeable |
+| AC-25 | Niche actions are stored but not displayed: merge_train_removed, member_access_requested, marked |
+
+### Attention State
+
+| ID | Behavior |
+|----|----------|
+| AC-26 | Todos do not affect attention state calculation |
+| AC-27 | Todos do not appear in "since last check" cursor-based inbox |
+
+### Error Handling
+
+| ID | Behavior |
+|----|----------|
+| AC-28 | 403 Forbidden on todos API logs warning and continues sync |
+| AC-29 | 429 Rate Limited respects Retry-After header |
+| AC-30 | Malformed todo JSON logs warning, skips that item, and disables purge for that sync |
+
+### Documentation
+
+| ID | Behavior |
+|----|----------|
+| AC-31 | `lore todos` appears in CLI help |
+| AC-32 | `lore robot-docs` includes todos schema |
+| AC-33 | CLAUDE.md documents the todos command |
+
+### Quality
+
+| ID | Behavior |
+|----|----------|
+| AC-34 | All quality gates pass: check, clippy, fmt, test |
+
+---
+
+## Architecture
+
+Designed to fulfill the acceptance criteria above.
+
+### Module Structure
+
+```
+src/
+├── gitlab/
+│   ├── client.rs      # fetch_todos() method (AC-4, AC-5)
+│   └── types.rs       # GitLabTodo struct
+├── ingestion/
+│   └── todos.rs       # sync_todos(), purge-safe deletion (AC-6, AC-7)
+├── cli/commands/
+│   ├── todos.rs       # lore todos command (AC-10-17)
+│   └── me/
+│       ├── types.rs   # MeTodo, extend MeSummary (AC-18)
+│       └── queries.rs # query_todos() (AC-19, AC-23)
+└── core/
+    └── db.rs          # Migration 028 (AC-1, AC-2, AC-3)
+```
+
+### Data Flow
+
+```
+GitLab API                Local SQLite              CLI Output
+───────────               ────────────              ──────────
+GET /api/v4/todos    →    todos table          →   lore todos
+(account-wide)            (purge-safe sync)        lore me --todos
+```
+
+### Key Design Decisions
+
+| Decision | Rationale | ACs |
+|----------|-----------|-----|
+| Account-wide fetch | GitLab todos API is user-scoped, not project-scoped | AC-5, AC-21 |
+| Purge-safe deletion | Transient errors should not delete valid data | AC-7 |
+| Separate from attention | Todos are notifications, not engagement signals | AC-26, AC-27 |
+| Store all actions, display core | Future-proofs for new action types | AC-24, AC-25 |
+
+### Existing Code to Extend
+
+| Type | Location | Extension |
+|------|----------|-----------|
+| `MeSummary` | `src/cli/commands/me/types.rs` | Add `pending_todo_count` field |
+| `ActivityEventType` | `src/cli/commands/me/types.rs` | Add `Todo` variant |
+| `MeDashboard` | `src/cli/commands/me/types.rs` | Add `todos: Vec<MeTodo>` field |
+| `SyncArgs` | `src/cli/mod.rs` | Add `--no-todos` flag |
+| `MeArgs` | `src/cli/mod.rs` | Add `--todos` flag |
+
+---
+
+## Implementation Specifications
+
+Each IMP section details HOW to fulfill specific ACs.
+
+### IMP-1: Database Schema
+
+**Fulfills:** AC-1, AC-2, AC-3
+
+**Migration 028:**
+
+```sql
+CREATE TABLE todos (
+    id INTEGER PRIMARY KEY,
+    gitlab_todo_id INTEGER NOT NULL UNIQUE,
+    project_id INTEGER REFERENCES projects(id) ON DELETE SET NULL,
+    gitlab_project_id INTEGER,
+    target_type TEXT NOT NULL,
+    target_id TEXT,
+    target_iid INTEGER,
+    target_url TEXT NOT NULL,
+    target_title TEXT,
+    action_name TEXT NOT NULL,
+    author_id INTEGER,
+    author_username TEXT,
+    body TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    synced_at INTEGER NOT NULL,
+    sync_generation INTEGER NOT NULL DEFAULT 0,
+    project_path TEXT
+);
+
+CREATE INDEX idx_todos_action_created ON todos(action_name, created_at DESC);
+CREATE INDEX idx_todos_target ON todos(target_type, target_id);
+CREATE INDEX idx_todos_created ON todos(created_at DESC);
+CREATE INDEX idx_todos_sync_gen ON todos(sync_generation);
+CREATE INDEX idx_todos_gitlab_project ON todos(gitlab_project_id);
+CREATE INDEX idx_todos_target_lookup ON todos(target_type, project_id, target_iid);
+```
+
+**Notes:**
+- `project_id` nullable for non-synced projects (AC-3)
+- `gitlab_project_id` nullable — TODO targets include non-project entities (Namespace, etc.)
+- No `state` column — we only store pending todos
+- `sync_generation` enables two-generation grace purge (AC-7)
+
+---
+
+### IMP-2: GitLab API Client
+
+**Fulfills:** AC-4, AC-5
+
+**Endpoint:** `GET /api/v4/todos?state=pending`
+
+**Types to add in `src/gitlab/types.rs`:**
+
+```rust
+#[derive(Debug, Deserialize)]
+pub struct GitLabTodo {
+    pub id: i64,
+    pub project: Option<GitLabTodoProject>,
+    pub author: Option<GitLabTodoAuthor>,
+    pub action_name: String,
+    pub target_type: String,
+    pub target: Option<GitLabTodoTarget>,
+    pub target_url: String,
+    pub body: Option<String>,
+    pub state: String,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct GitLabTodoProject {
+    pub id: i64,
+    pub path_with_namespace: String,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct GitLabTodoTarget {
+    pub id: serde_json::Value,  // i64 or String (commit SHA)
+    pub iid: Option<i64>,
+    pub title: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct GitLabTodoAuthor {
+    pub id: i64,
+    pub username: String,
+}
+```
+
+**Client method in `src/gitlab/client.rs`:**
+
+```rust
+pub fn fetch_todos(&self) -> impl Stream<Item = Result<GitLabTodo>> {
+    self.paginate("/api/v4/todos?state=pending")
+}
+```
+
+---
+
+### IMP-3: Sync Pipeline Integration
+
+**Fulfills:** AC-4, AC-5, AC-6, AC-7, AC-8, AC-9
+
+**New file: `src/ingestion/todos.rs`**
+
+**Sync position:** Account-wide step after per-project sync and status enrichment.
+
+```
+Sync order:
+1. Issues (per project)
+2. MRs (per project)
+3. Status enrichment (account-wide GraphQL)
+4. Todos (account-wide REST) ← NEW
+```
+
+**Purge-safe deletion pattern:**
+
+```rust
+pub struct TodoSyncResult {
+    pub fetched: usize,
+    pub upserted: usize,
+    pub deleted: usize,
+    pub generation: i64,
+    pub purge_allowed: bool,
+}
+
+pub fn sync_todos(conn: &Connection, client: &GitLabClient) -> Result<TodoSyncResult> {
+    // 1. Get next generation
+    let generation: i64 = conn.query_row(
+        "SELECT COALESCE(MAX(sync_generation), 0) + 1 FROM todos",
+        [], |r| r.get(0)
+    )?;
+
+    let mut fetched = 0;
+    let mut purge_allowed = true;
+
+    // 2. Fetch and upsert all todos
+    for result in client.fetch_todos()? {
+        match result {
+            Ok(todo) => {
+                upsert_todo_guarded(conn, &todo, generation)?;
+                fetched += 1;
+            }
+            Err(e) => {
+                // Malformed JSON: log warning, skip item, disable purge
+                warn!("Skipping malformed todo: {e}");
+                purge_allowed = false;
+            }
+        }
+    }
+
+    // 3. Two-generation grace purge: delete only if missing for 2+ consecutive syncs
+    // This protects against pagination drift (new todos inserted during traversal)
+    let deleted = if purge_allowed {
+        conn.execute("DELETE FROM todos WHERE sync_generation < ? - 1", [generation])?
+    } else {
+        0
+    };
+
+    Ok(TodoSyncResult { fetched, upserted: fetched, deleted, generation, purge_allowed })
+}
+```
+
+**Concurrent-safe upsert:**
+
+```sql
+INSERT INTO todos (..., sync_generation) VALUES (?, ..., ?)
+ON CONFLICT(gitlab_todo_id) DO UPDATE SET
+    ...,
+    sync_generation = excluded.sync_generation,
+    synced_at = excluded.synced_at
+WHERE excluded.sync_generation >= todos.sync_generation;
+```
+
+**"Success" for purge (all must be true):**
+- Every page fetch completed without error
+- Every todo JSON decoded successfully (any decode failure sets `purge_allowed=false`)
+- Pagination traversal completed (not interrupted)
+- Response was not 401/403
+- Zero todos IS valid for purge when above conditions met
+
+**Two-generation grace purge:**
+Todos are deleted only if missing for 2 consecutive successful syncs (`sync_generation < current - 1`).
+This protects against false deletions from pagination drift (new todos inserted during traversal).
+
+---
+
+### IMP-4: Project Path Extraction
+
+**Fulfills:** AC-3, AC-13
+
+```rust
+use once_cell::sync::Lazy;
+use regex::Regex;
+
+pub fn extract_project_path(url: &str) -> Option<&str> {
+    static RE: Lazy<Regex> = Lazy::new(|| {
+        Regex::new(r"https?://[^/]+/(.+?)/-/(?:issues|merge_requests|epics|commits)/")
+            .expect("valid regex")
+    });
+
+    RE.captures(url)
+        .and_then(|c| c.get(1))
+        .map(|m| m.as_str())
+}
+```
+
+**Usage:** Prefer `project.path_with_namespace` from API when available. Fall back to URL extraction for external projects.
+
+---
+
+### IMP-5: `lore todos` Command
+
+**Fulfills:** AC-10, AC-11, AC-12, AC-13, AC-14, AC-15, AC-16, AC-17
+
+**New file: `src/cli/commands/todos.rs`**
+
+**Args:**
+
+```rust
+#[derive(Parser)]
+#[command(alias = "todo")]
+pub struct TodosArgs {
+    #[arg(short = 'n', long)]
+    pub limit: Option<usize>,
+}
+```
+
+**Autocorrect aliases in `src/cli/mod.rs`:**
+
+```rust
+("td", "todos"),
+("todo", "todos"),
+```
+
+**Action type grouping:**
+
+| Group | Actions |
+|-------|---------|
+| Assignments | `assigned` |
+| Mentions | `mentioned`, `directly_addressed` |
+| Approvals | `approval_required` |
+| Build Issues | `build_failed`, `unmergeable` |
+
+**Robot mode schema:**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "todos": [{
+      "id": 123,
+      "gitlab_todo_id": 456,
+      "action": "mentioned",
+      "target_type": "Issue",
+      "target_iid": 42,
+      "target_title": "Fix login bug",
+      "target_url": "https://...",
+      "project_path": "group/repo",
+      "author_username": "jdoe",
+      "body": "Hey @you, can you look at this?",
+      "created_at_iso": "2026-02-20T10:00:00Z",
+      "is_external": false
+    }],
+    "counts": {
+      "total": 8,
+      "assigned": 2,
+      "mentioned": 5,
+      "approval_required": 1,
+      "build_failed": 0,
+      "unmergeable": 0,
+      "other": 0
+    }
+  },
+  "meta": {"elapsed_ms": 42}
+}
+```
+
+**Minimal fields:** `gitlab_todo_id`, `action`, `target_type`, `target_iid`, `project_path`, `is_external`
+
+---
+
+### IMP-6: `lore me` Integration
+
+**Fulfills:** AC-18, AC-19, AC-20, AC-21, AC-22, AC-23
+
+**Types to add/extend in `src/cli/commands/me/types.rs`:**
+
+```rust
+// EXTEND
+pub struct MeSummary {
+    // ... existing fields ...
+    pub pending_todo_count: usize,  // ADD
+}
+
+// EXTEND
+pub enum ActivityEventType {
+    // ... existing variants ...
+    Todo,  // ADD
+}
+
+// EXTEND
+pub struct MeDashboard {
+    // ... existing fields ...
+    pub todos: Vec<MeTodo>,  // ADD
+}
+
+// NEW
+pub struct MeTodo {
+    pub id: i64,
+    pub gitlab_todo_id: i64,
+    pub action: String,
+    pub target_type: String,
+    pub target_iid: Option<i64>,
+    pub target_title: Option<String>,
+    pub target_url: String,
+    pub project_path: String,
+    pub author_username: Option<String>,
+    pub body: Option<String>,
+    pub created_at: i64,
+    pub is_external: bool,
+}
+```
+
+**Warning for `--project` with `--todos` (AC-22):**
+
+```rust
+if args.todos && args.project.is_some() {
+    eprintln!("Warning: Todos are account-wide; project filter not applied");
+}
+```
+
+---
+
+### IMP-7: Error Handling
+
+**Fulfills:** AC-28, AC-29, AC-30
+
+| Error | Behavior |
+|-------|----------|
+| 403 Forbidden | Log warning, skip todo sync, continue with other entities |
+| 429 Rate Limited | Respect `Retry-After` header using existing retry policy |
+| Malformed JSON | Log warning with todo ID, skip item, set `purge_allowed=false`, continue batch |
+
+**Rationale for purge disable on malformed JSON:** If we can't decode a todo, we don't know its `gitlab_todo_id`. Without that, we might accidentally purge a valid todo that was simply malformed in transit. Disabling purge for that sync is the safe choice.
+
+---
+
+### IMP-8: Test Fixtures
+
+**Fulfills:** AC-34
+
+**Location:** `tests/fixtures/todos/`
+
+**`todos_pending.json`:**
+```json
+[
+  {
+    "id": 102,
+    "project": {"id": 2, "path_with_namespace": "diaspora/client"},
+    "author": {"id": 1, "username": "admin"},
+    "action_name": "mentioned",
+    "target_type": "Issue",
+    "target": {"id": 11, "iid": 4, "title": "Inventory system"},
+    "target_url": "https://gitlab.example.com/diaspora/client/-/issues/4",
+    "body": "@user please review",
+    "state": "pending",
+    "created_at": "2026-02-20T10:00:00.000Z",
+    "updated_at": "2026-02-20T10:00:00.000Z"
+  }
+]
+```
+
+**`todos_empty.json`:** `[]`
+
+**`todos_commit_target.json`:** (target.id is string SHA)
+
+**`todos_niche_actions.json`:** (merge_train_removed, etc.)
+
+---
+
+## Rollout Slices
+
+### Dependency Graph
+
+```
+Slice A ──────► Slice B ──────┬──────► Slice C
+(Schema)        (Sync)        │        (`lore todos`)
+                              │
+                              └──────► Slice D
+                                       (`lore me`)
+
+                 Slice C ───┬───► Slice E
+                 Slice D ───┘    (Polish)
+```
+
+### Slice A: Schema + Client
+
+**ACs:** AC-1, AC-2, AC-3, AC-4, AC-5
+**IMPs:** IMP-1, IMP-2, IMP-4
+**Deliverable:** Migration + client method + deserialization tests pass
+
+### Slice B: Sync Integration
+
+**ACs:** AC-6, AC-7, AC-8, AC-9, AC-28, AC-29, AC-30
+**IMPs:** IMP-3, IMP-7
+**Deliverable:** `lore sync` fetches todos; `--no-todos` works
+
+### Slice C: `lore todos` Command
+
+**ACs:** AC-10, AC-11, AC-12, AC-13, AC-14, AC-15, AC-16, AC-17, AC-24, AC-25
+**IMPs:** IMP-5
+**Deliverable:** `lore todos` and `lore --robot todos` work
+
+### Slice D: `lore me` Integration
+
+**ACs:** AC-18, AC-19, AC-20, AC-21, AC-22, AC-23, AC-26, AC-27
+**IMPs:** IMP-6
+**Deliverable:** `lore me --todos` works; summary shows count
+
+### Slice E: Polish
+
+**ACs:** AC-31, AC-32, AC-33, AC-34
+**IMPs:** IMP-8
+**Deliverable:** Docs updated; all quality gates pass
+
+---
+
+## Design Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Write operations | Read-only | Complexity; glab handles writes |
+| Storage | SQLite | Consistent with existing architecture |
+| Project filter | Account-wide only | GitLab API is user-scoped |
+| Action type display | Core only | Reduce noise; store all for future |
+| Attention state | Separate signal | Todos are notifications, not engagement |
+| History | Pending only | Simplicity; done todos have no value locally |
+| Grouping | By action type | Matches GitLab UI; aids triage |
+| Purge strategy | Two-generation grace | Protects against pagination drift during sync |
+
+---
+
+## Out of Scope
+
+- Write operations (mark as done)
+- Done todo history tracking
+- Filters beyond `--limit`
+- Todo-based attention state boosting
+- Notification settings API
+
+---
+
+## References
+
+- [GitLab To-Do List API](https://docs.gitlab.com/api/todos/)
+- [GitLab User Todos](https://docs.gitlab.com/user/todos/)

plans/init-refresh-flag.md

@@ -0,0 +1,137 @@
+# Plan: `lore init --refresh`
+
+**Created:** 2026-03-02
+**Status:** Complete
+
+## Problem
+
+When new repos are added to the config file, `lore sync` doesn't pick them up because project discovery only happens during `lore init`. Currently, users must use `--force` to overwrite their config, which is awkward.
+
+## Solution
+
+Add `--refresh` flag to `lore init` that reads the existing config and updates the database to match, without overwriting the config file.
+
+---
+
+## Implementation Plan
+
+### 1. CLI Changes (`src/cli/mod.rs`)
+
+Add to init subcommand:
+- `--refresh` flag (conflicts with `--force`)
+- Ensure `--robot` / `-J` propagates to init
+
+### 2. Update `InitOptions` struct
+
+```rust
+pub struct InitOptions {
+    pub config_path: Option<String>,
+    pub force: bool,
+    pub non_interactive: bool,
+    pub refresh: bool,       // NEW
+    pub robot_mode: bool,    // NEW
+}
+```
+
+### 3. New `RefreshResult` struct
+
+```rust
+pub struct RefreshResult {
+    pub user: UserInfo,
+    pub projects_registered: Vec<ProjectInfo>,
+    pub projects_failed: Vec<ProjectFailure>,  // path + error message
+    pub orphans_found: Vec<String>,            // paths in DB but not config
+    pub orphans_deleted: Vec<String>,          // if user said yes
+}
+
+pub struct ProjectFailure {
+    pub path: String,
+    pub error: String,
+}
+```
+
+### 4. Main logic: `run_init_refresh()` (new function)
+
+```
+1. Load config via Config::load()
+2. Resolve token, call get_current_user() → validate auth
+3. For each project in config.projects:
+   - Call client.get_project(path)
+   - On success: collect for DB upsert
+   - On failure: collect in projects_failed
+4. Query DB for all existing projects
+5. Compute orphans = DB projects - config projects
+6. If orphans exist:
+   - Robot mode: include in output, no prompt, no delete
+   - Interactive: prompt "Delete N orphan projects? [y/N]"
+     - Default N → skip deletion
+     - Y → delete from DB
+7. Upsert validated projects into DB
+8. Return RefreshResult
+```
+
+### 5. Improve existing init error message
+
+In `run_init()`, when config exists and neither `--refresh` nor `--force`:
+
+**Current:**
+> Config file exists at ~/.config/lore/config.json. Use --force to overwrite.
+
+**New:**
+> Config already exists at ~/.config/lore/config.json.
+> - Use `--refresh` to register new projects from config
+> - Use `--force` to overwrite the config file
+
+### 6. Robot mode output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "mode": "refresh",
+    "user": { "username": "...", "name": "..." },
+    "projects_registered": [...],
+    "projects_failed": [...],
+    "orphans_found": ["old/project"],
+    "orphans_deleted": []
+  },
+  "meta": { "elapsed_ms": 123 }
+}
+```
+
+### 7. Human output
+
+```
+  ✓ Authenticated as @username (Full Name)
+
+  Projects
+    ✓ group/project-a          registered
+    ✓ group/project-b          registered
+    ✗ group/nonexistent        not found
+
+  Orphans
+    • old/removed-project
+
+  Delete 1 orphan project from database? [y/N]: n
+
+  Registered 2 projects (1 failed, 1 orphan kept)
+```
+
+---
+
+## Files to Touch
+
+1. **`src/cli/mod.rs`** — add `--refresh` and `--robot` to init subcommand args
+2. **`src/cli/commands/init.rs`** — add `RefreshResult`, `run_init_refresh()`, update error message
+3. **`src/main.rs`** (or CLI dispatch) — route `--refresh` to new function
+
+---
+
+## Acceptance Criteria
+
+- [x] `lore init --refresh` reads existing config and registers projects
+- [x] Validates GitLab auth before processing
+- [x] Orphan projects prompt with default N (interactive mode)
+- [x] Robot mode outputs JSON, no prompts, includes orphans in output
+- [x] Existing `lore init` (no flags) suggests `--refresh` when config exists
+- [x] `--refresh` and `--force` are mutually exclusive

plans/lore-service.feedback-1.md

@@ -1,186 +0,0 @@
-1. **Isolate scheduled behavior from manual `sync`**
-Reasoning: Your current plan injects backoff into `handle_sync_cmd`, which affects all `lore sync` calls (including manual recovery runs). Scheduled behavior should be isolated so humans aren’t unexpectedly blocked by service backoff.
-
-```diff
-@@ Context
--`lore sync` runs a 4-stage pipeline (issues, MRs, docs, embeddings) that takes 2-4 minutes.
-+`lore sync` remains the manual/operator command.
-+`lore service run` (hidden/internal) is the scheduled execution entrypoint.
-
-@@ Commands & User Journeys
-+### `lore service run` (hidden/internal)
-+**What it does:** Executes one scheduled sync attempt with service-only policy:
-+- applies service backoff policy
-+- records service run state
-+- invokes sync pipeline with configured profile
-+- updates retry state on success/failure
-+
-+**Invocation:** scheduler always runs:
-+`lore --robot service run --reason timer`
-
-@@ Backoff Integration into `handle_sync_cmd`
--Insert **after** config load but **before** the dry_run check:
-+Do not add backoff checks to `handle_sync_cmd`.
-+Backoff logic lives only in `handle_service_run`.
-```
-
-2. **Use DB as source-of-truth for service state (not a standalone JSON status file)**
-Reasoning: You already have `sync_runs` in SQLite. A separate JSON status file creates split-brain and race/corruption risk. Keep JSON as optional cache/export only.
-
-```diff
-@@ Status File
--Location: `{get_data_dir()}/sync-status.json`
-+Primary state location: SQLite (`service_state` table) + existing `sync_runs`.
-+Optional mirror file: `{get_data_dir()}/sync-status.json` (best-effort export only).
-
-@@ File-by-File Implementation Details
--### `src/core/sync_status.rs` (NEW)
-+### `migrations/015_service_state.sql` (NEW)
-+CREATE TABLE service_state (
-+  id INTEGER PRIMARY KEY CHECK (id = 1),
-+  installed INTEGER NOT NULL DEFAULT 0,
-+  platform TEXT,
-+  interval_seconds INTEGER,
-+  profile TEXT NOT NULL DEFAULT 'balanced',
-+  consecutive_failures INTEGER NOT NULL DEFAULT 0,
-+  next_retry_at_ms INTEGER,
-+  last_error_code TEXT,
-+  last_error_message TEXT,
-+  updated_at_ms INTEGER NOT NULL
-+);
-+
-+### `src/core/service_state.rs` (NEW)
-+- read/write state row
-+- derive backoff/next_retry
-+- join with latest `sync_runs` for status output
-```
-
-3. **Backoff policy should be configurable, jittered, and error-aware**
-Reasoning: Fixed hardcoded backoff (`base=1800`) is wrong when user sets another interval. Also permanent failures (bad token/config) should not burn retries forever; they should enter paused/error state.
-
-```diff
-@@ Backoff Logic
--// Exponential: base * 2^failures, capped at 4 hours
-+// Exponential with jitter: base * 2^(failures-1), capped, ±20% jitter
-+// Applies only to transient errors.
-+// Permanent errors set `paused_reason` and stop retries until user action.
-
-@@ CLI Definition Changes
-+ServiceCommand::Resume,   // clear paused state / failures
-+ServiceCommand::Run,      // hidden
-
-@@ Error Types
-+ServicePaused,            // scheduler paused due to permanent error
-+ServiceCommandFailed,     // OS command failure with stderr context
-```
-
-4. **Add a pipeline-level single-flight lock**
-Reasoning: Current locking is in ingest stages; there’s still overlap risk across full sync pipelines (docs/embed can overlap with another run). Add a top-level lock for scheduled/manual sync pipeline execution.
-
-```diff
-@@ Architecture
-+Add `sync_pipeline` lock at top-level sync execution.
-+Keep existing ingest lock (`sync`) for ingest internals.
-
-@@ Backoff Integration into `handle_sync_cmd`
-+Before starting sync pipeline, acquire `AppLock` with:
-+name = "sync_pipeline"
-+stale_lock_minutes = config.sync.stale_lock_minutes
-+heartbeat_interval_seconds = config.sync.heartbeat_interval_seconds
-```
-
-5. **Don’t embed token in service files by default**
-Reasoning: Embedding PAT into unit/plist is a high-risk secret leak path. Make secure storage explicit and default-safe.
-
-```diff
-@@ `lore service install [--interval 30m]`
-+`lore service install [--interval 30m] [--token-source env-file|embedded]`
-+Default: `env-file` (0600 perms, user-owned)
-+`embedded` allowed only with explicit opt-in and warning
-
-@@ Robot output
--    "token_embedded": true
-+    "token_source": "env_file"
-
-@@ Human output
--  Note: Your GITLAB_TOKEN is embedded in the service file.
-+  Note: Token is stored in a user-private env file (0600).
-```
-
-6. **Introduce a command-runner abstraction with timeout + stderr capture**
-Reasoning: `launchctl/systemctl/schtasks` calls are failure-prone; you need consistent error mapping and deterministic tests.
-
-```diff
-@@ Platform Backends
--exports free functions that dispatch via `#[cfg(target_os)]`
-+exports backend + shared `CommandRunner`:
-+- run(cmd, args, timeout)
-+- capture stdout/stderr/exit code
-+- map failure to `ServiceCommandFailed { cmd, exit_code, stderr }`
-```
-
-7. **Persist install manifest to avoid brittle file parsing**
-Reasoning: Parsing timer/plist for interval/state is fragile and platform-format dependent. Persist a manifest with checksums and expected artifacts.
-
-```diff
-@@ Platform Backends
--Same pattern for ... `get_interval_seconds()`
-+Add manifest: `{data_dir}/service-manifest.json`
-+Stores platform, interval, profile, generated files, and command.
-+`service status` reads manifest first, then verifies platform state.
-
-@@ Acceptance criteria
-+Install is idempotent:
-+- if manifest+files already match, report `no_change: true`
-+- if drift detected, reconcile and rewrite
-```
-
-8. **Make schedule profile explicit (`fast|balanced|full`)**
-Reasoning: This makes the feature more useful and performance-tunable without requiring users to understand internal flags.
-
-```diff
-@@ `lore service install [--interval 30m]`
-+`lore service install [--interval 30m] [--profile fast|balanced|full]`
-+
-+Profiles:
-+- fast: `sync --no-docs --no-embed`
-+- balanced (default): `sync --no-embed`
-+- full: `sync`
-```
-
-9. **Upgrade `service status` to include scheduler health + recent run summary**
-Reasoning: Single last-sync snapshot is too shallow. Include recent attempts and whether scheduler is paused/backing off/running.
-
-```diff
-@@ `lore service status`
--What it does: Shows whether the service is installed, its configuration, last sync result, and next scheduled run.
-+What it does: Shows install state, scheduler state (running/backoff/paused), recent runs, and next run estimate.
-
-@@ Robot output
--    "last_sync": { ... },
--    "backoff": null
-+    "scheduler_state": "running|backoff|paused|idle",
-+    "last_sync": { ... },
-+    "recent_runs": [{"run_id":"...","status":"...","started_at_iso":"..."}],
-+    "backoff": null,
-+    "paused_reason": null
-```
-
-10. **Strengthen tests around determinism and cross-platform generation**
-Reasoning: Time-based backoff and shell quoting are classic flaky points. Add fake clock + fake command runner for deterministic tests.
-
-```diff
-@@ Testing Strategy
-+Add deterministic test seams:
-+- `Clock` trait for backoff/now calculations
-+- `CommandRunner` trait for backend command execution
-+
-+Add tests:
-+- transient vs permanent error classification
-+- backoff schedule with jitter bounds
-+- manifest drift reconciliation
-+- quoting/escaping for paths with spaces and special chars
-+- `service run` does not modify manual `sync` behavior
-```
-
-If you want, I can rewrite your full plan as a single clean revised document with these changes already integrated (instead of patch fragments).

plans/lore-service.feedback-2.md

@@ -1,182 +0,0 @@
-**High-Impact Revisions (ordered by priority)**
-
-1. **Make service identity project-scoped (avoid collisions across repos/users)**
-Analysis: Current fixed names (`com.gitlore.sync`, `LoreSync`, `lore-sync.timer`) will collide when users run multiple gitlore workspaces. This causes silent overwrites and broken uninstall/status behavior.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ Commands & User Journeys / install
-- lore service install [--interval 30m] [--profile balanced] [--token-source env-file]
-+ lore service install [--interval 30m] [--profile balanced] [--token-source auto] [--name <optional>]
-@@ Install Manifest Schema
-+    /// Stable per-install identity (default derived from project root hash)
-+    pub service_id: String,
-@@ Platform Backends
-- Label: com.gitlore.sync
-+ Label: com.gitlore.sync.{service_id}
-- Task name: LoreSync
-+ Task name: LoreSync-{service_id}
-- ~/.config/systemd/user/lore-sync.service
-+ ~/.config/systemd/user/lore-sync-{service_id}.service
-```
-
-2. **Replace token model with secure per-OS defaults**
-Analysis: The current “env-file default” is not actually secure on macOS launchd (token still ends up in plist). On Windows, assumptions about inherited environment are fragile. Use OS-native secure stores by default and keep `embedded` as explicit opt-in only.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ Token storage strategies
--| env-file (default) | ...
-+| auto (default) | macOS: Keychain, Linux: env-file (0600), Windows: Credential Manager |
-+| env-file | Linux/systemd only |
- | embedded | ... explicit warning ...
-@@ macOS launchd section
-- env-file strategy stores canonical token in service-env but embeds token in plist
-+ default strategy is Keychain lookup at runtime; no token persisted in plist
-+ env-file is not offered on macOS
-@@ Windows schtasks section
-- token must be in user's system environment
-+ default strategy stores token in Windows Credential Manager and injects at runtime
-```
-
-3. **Version and atomically persist manifest/status**
-Analysis: `Option<Self>` on read hides corruption, and non-atomic writes risk truncated JSON on crashes. This will create false “not installed” and scheduler confusion.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ Install Manifest Schema
-+    pub schema_version: u32, // start at 1
-+    pub updated_at_iso: String,
-@@ Status File Schema
-+    pub schema_version: u32, // start at 1
-+    pub updated_at_iso: String,
-@@ Read/Write
-- read(path) -> Option<Self>
-+ read(path) -> Result<Option<Self>, LoreError>
-- write(...) -> std::io::Result<()>
-+ write_atomic(...) -> std::io::Result<()> // tmp file + fsync + rename
-```
-
-4. **Persist `next_retry_at_ms` instead of recomputing jitter**
-Analysis: Deterministic jitter from timestamp modulo is predictable and can herd retries. Persisting `next_retry_at_ms` at failure time makes status accurate, stable, and cheap to compute.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ SyncStatusFile
-     pub consecutive_failures: u32,
-+    pub next_retry_at_ms: Option<i64>,
-@@ Backoff Logic
-- compute backoff from last_run.timestamp_ms and deterministic jitter each read
-+ compute backoff once on failure, store next_retry_at_ms, read-only comparison afterward
-+ jitter algorithm: full jitter in [0, cap], injectable RNG for tests
-```
-
-5. **Add circuit breaker for repeated transient failures**
-Analysis: Infinite transient retries can run forever on systemic failures (DB corruption, bad network policy). After N transient failures, pause with actionable reason.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ Scheduler states
-- backoff — transient failures, waiting to retry
-+ backoff — transient failures, waiting to retry
-+ paused — permanent error OR circuit breaker tripped after N transient failures
-@@ Service run flow
-- On transient failure: increment failures, compute backoff
-+ On transient failure: increment failures, compute backoff, if failures >= max_transient_failures -> pause
-```
-
-6. **Stage-aware outcome policy (core freshness over all-or-nothing)**
-Analysis: Failing embeddings/docs should not block issues/MRs freshness. Split stage outcomes and only treat core stages as hard-fail by default. This improves reliability and practical usefulness.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ Context
-- lore sync runs a 4-stage pipeline ... treated as one run result
-+ lore service run records per-stage outcomes (issues, mrs, docs, embeddings)
-@@ Status File Schema
-+    pub stage_results: Vec<StageResult>,
-@@ service run flow
-- Execute sync pipeline with flags derived from profile
-+ Execute stage-by-stage and classify severity:
-+   - critical: issues, mrs
-+   - optional: docs, embeddings
-+ optional stage failures mark run as degraded, not failed
-```
-
-7. **Replace cfg free-function backend with trait-based backend**
-Analysis: Current backend API is hard to test end-to-end without real OS commands. A `SchedulerBackend` trait enables deterministic integration tests and cleaner architecture.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ Platform Backends / Architecture
-- exports free functions dispatched via #[cfg]
-+ define trait SchedulerBackend { install, uninstall, state, file_paths, next_run }
-+ provide LaunchdBackend, SystemdBackend, SchtasksBackend implementations
-+ include FakeBackend for integration tests
-```
-
-8. **Harden platform units and detect scheduler prerequisites**
-Analysis: systemd user timers often fail silently without user manager/linger; launchd context can be wrong in headless sessions. Add explicit diagnostics and unit hardening.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ Linux systemd unit
- [Service]
- Type=oneshot
- ExecStart=...
-+TimeoutStartSec=900
-+NoNewPrivileges=true
-+PrivateTmp=true
-+ProtectSystem=strict
-+ProtectHome=read-only
-@@ Linux install/status
-+ detect user manager availability and linger state; surface warning/action
-@@ macOS install/status
-+ detect non-GUI bootstrap context and return actionable error
-```
-
-9. **Add operational commands: `trigger`, `doctor`, and non-interactive log tail**
-Analysis: `logs` opening an editor is weak for automation and incident response. Operators need a preflight and immediate controlled run.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ ServiceCommand
-+ Trigger, // run one attempt through service policy now
-+ Doctor,  // validate scheduler, token, paths, permissions
-@@ logs
-- opens editor
-+ supports --tail <n> and --follow in human mode
-+ robot mode can return last_n lines optionally
-```
-
-10. **Fix plan inconsistencies and edge-case correctness**
-Analysis: There are internal mismatches that will cause implementation drift.  
-Diff:
-```diff
---- a/plan.md
-+++ b/plan.md
-@@ Interval Parsing
-- supports 's' suffix
-+ remove 's' suffix (acceptance only allows 5m..24h)
-@@ uninstall acceptance
-- removes ALL service files only
-+ explicitly also remove service-manifest and service-env (status/logs retained)
-@@ SyncStatusFile schema
-- pub last_run: SyncRunRecord
-+ pub last_run: Option<SyncRunRecord> // matches idle/no runs state
-```
-
----
-
-**Recommended Architecture Upgrade Summary**
-
-The strongest improvement set is: **(1) project-scoped IDs, (2) secure token defaults, (3) atomic/versioned state, (4) persisted retry schedule + circuit breaker, (5) stage-aware outcomes**. That combination materially improves correctness, multi-repo safety, security, operability, and real-world reliability without changing your core manual-vs-scheduled separation principle.

plans/lore-service.feedback-3.md

@@ -1,174 +0,0 @@
-Below are the highest-impact revisions I’d make, ordered by severity/ROI. These focus on correctness first, then security, then operability and UX.
-
-1. **Fix multi-install ambiguity (`service_id` exists, but commands can’t target one explicitly)**
-Analysis: The plan introduces `service-manifest-{service_id}.json`, but `status/uninstall/resume/logs` have no selector. In a multi-workspace or multi-name install scenario, behavior becomes ambiguous and error-prone. Add explicit targeting plus discovery.
-```diff
-@@ ## Commands & User Journeys
-+### `lore service list`
-+Lists installed services discovered from `{data_dir}/service-manifest-*.json`.
-+Robot output includes `service_id`, `platform`, `interval_seconds`, `profile`, `installed_at_iso`.
-
-@@ ### `lore service uninstall`
--### `lore service uninstall`
-+### `lore service uninstall [--service <service_id|name>] [--all]`
-@@
--2. CLI reads install manifest to find `service_id`
-+2. CLI resolves target service via `--service` or current-project-derived default.
-+3. If multiple candidates and no selector, return actionable error.
-
-@@ ### `lore service status`
--### `lore service status`
-+### `lore service status [--service <service_id|name>]`
-```
-
-2. **Make status state service-scoped (not global)**
-Analysis: A single `sync-status.json` for all services causes cross-service contamination (pause/backoff/outcome from one profile affecting another). Keep lock global, but state per service.
-```diff
-@@ ## Status File
--### Location
--`{get_data_dir()}/sync-status.json`
-+### Location
-+`{get_data_dir()}/sync-status-{service_id}.json`
-
-@@ ## Paths Module Additions
--pub fn get_service_status_path() -> PathBuf {
--    get_data_dir().join("sync-status.json")
-+pub fn get_service_status_path(service_id: &str) -> PathBuf {
-+    get_data_dir().join(format!("sync-status-{service_id}.json"))
-}
-@@
--Note: `sync-status.json` is NOT scoped by `service_id`
-+Note: status is scoped by `service_id`; lock remains global (`sync_pipeline`) to prevent overlapping writes.
-```
-
-3. **Stop classifying permanence via string matching**
-Analysis: Matching `"401 Unauthorized"` in strings is brittle and will misclassify edge cases. Carry machine codes through stage results and classify by `ErrorCode` only.
-```diff
-@@ pub struct StageResult {
--    pub error: Option<String>,
-+    pub error: Option<String>,
-+    pub error_code: Option<String>, // e.g., AUTH_FAILED, NETWORK_ERROR
-}
-@@ Error classification helpers
--fn is_permanent_error_message(msg: Option<&str>) -> bool { ...string contains... }
-+fn is_permanent_error_code(code: Option<&str>) -> bool {
-+    matches!(code, Some("TOKEN_NOT_SET" | "AUTH_FAILED" | "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "MIGRATION_FAILED"))
-+}
-```
-
-4. **Install should be transactional (manifest written last)**
-Analysis: Current order writes manifest before scheduler enable. If enable fails, you persist a false “installed” state. Use two-phase install with rollback.
-```diff
-@@ ### `lore service install` User journey
--9. CLI writes install manifest ...
--10. CLI runs the platform-specific enable command
-+9. CLI runs the platform-specific enable command
-+10. On success, CLI writes install manifest atomically
-+11. On failure, CLI removes generated files and returns `ServiceCommandFailed`
-```
-
-5. **Fix launchd token security gap (env-file currently still embeds token)**
-Analysis: Current “env-file” on macOS still writes token into plist, defeating the main security goal. Generate a private wrapper script that reads env file at runtime and execs `lore`.
-```diff
-@@ ### macOS: launchd
--<key>ProgramArguments</key>
--<array>
--    <string>{binary_path}</string>
--    <string>--robot</string>
--    <string>service</string>
--    <string>run</string>
--</array>
-+<key>ProgramArguments</key>
-+<array>
-+    <string>{data_dir}/service-run-{service_id}.sh</string>
-+</array>
-@@
--`env-file`: ... token value must still appear in plist ...
-+`env-file`: token never appears in plist; wrapper loads `{data_dir}/service-env-{service_id}` at runtime.
-```
-
-6. **Improve backoff math and add half-open circuit recovery**
-Analysis: Current jitter + min clamp makes first retry deterministic and can over-pause. Also circuit-breaker requires manual resume forever. Add cooldown + half-open probe to self-heal.
-```diff
-@@ Backoff Logic
--let backoff_secs = ((base_backoff as f64) * jitter_factor) as u64;
--let backoff_secs = backoff_secs.max(base_interval_seconds);
-+let max_backoff = base_backoff;
-+let min_backoff = base_interval_seconds;
-+let span = max_backoff.saturating_sub(min_backoff);
-+let backoff_secs = min_backoff + ((span as f64) * jitter_factor) as u64;
-
-@@ Scheduler states
--- `paused` — permanent error ... OR circuit breaker tripped ...
-+- `paused` — permanent error requiring intervention
-+- `half_open` — probe state after circuit cooldown; one trial run allowed
-
-@@ Circuit breaker
--... transitions to `paused` ... Run: lore service resume
-+... transitions to `half_open` after cooldown (default 30m). Successful probe closes breaker automatically; failed probe returns to backoff/paused.
-```
-
-7. **Promote backend trait to v1 (not v2) for deterministic integration tests**
-Analysis: This is a reliability-critical feature spanning OS schedulers. A trait abstraction now gives true behavior tests and safer refactors.
-```diff
-@@ ### Platform Backends
--> Future architecture note: A `SchedulerBackend` trait ... for v2.
-+Adopt `SchedulerBackend` trait in v1 with real backends (`launchd/systemd/schtasks`) and `FakeBackend` for tests.
-+This enables deterministic install/uninstall/status/run-path integration tests without touching host scheduler.
-```
-
-8. **Harden `run_cmd` timeout behavior**
-Analysis: If timeout occurs, child process must be killed and reaped. Otherwise you leak processes and can wedge repeated runs.
-```diff
-@@ fn run_cmd(...)
--// Wait with timeout
--let output = wait_with_timeout(output, timeout_secs)?;
-+// Wait with timeout; on timeout kill child and wait to reap
-+let output = wait_with_timeout_kill_and_reap(child, timeout_secs)?;
-```
-
-9. **Add manual control commands (`pause`, `trigger`, `repair`)**
-Analysis: These are high-utility operational controls. `trigger` helps immediate sync without waiting interval. `pause` supports maintenance windows. `repair` avoids manual file deletion for corrupt state.
-```diff
-@@ pub enum ServiceCommand {
-+    /// Pause scheduled execution without uninstalling
-+    Pause { #[arg(long)] reason: Option<String> },
-+    /// Trigger an immediate one-off run using installed profile
-+    Trigger { #[arg(long)] ignore_backoff: bool },
-+    /// Repair corrupt manifest/status by backing up and reinitializing
-+    Repair { #[arg(long)] service: Option<String> },
-}
-```
-
-10. **Make `logs` default non-interactive and add rotation policy**
-Analysis: Opening editor by default is awkward for automation/SSH and slower for normal diagnosis. Defaulting to `tail` is more practical; `--open` can preserve editor behavior.
-```diff
-@@ ### `lore service logs`
--By default, opens in the user's preferred editor.
-+By default, prints last 100 lines to stdout.
-+Use `--open` to open editor.
-@@
-+Log rotation: rotate `service-stdout.log` / `service-stderr.log` at 10 MB, keep 5 files.
-```
-
-11. **Remove destructive/shell-unsafe suggested action**
-Analysis: `actions(): ["rm {path}", ...]` is unsafe (shell injection + destructive guidance). Replace with safe command path.
-```diff
-@@ LoreError::actions()
--Self::ServiceCorruptState { path, .. } => vec![&format!("rm {path}"), "lore service install"],
-+Self::ServiceCorruptState { .. } => vec!["lore service repair", "lore service install"],
-```
-
-12. **Tighten scheduler units for real-world reliability**
-Analysis: Add explicit working directory and success-exit handling to reduce environment drift and edge failures.
-```diff
-@@ systemd service unit
- [Service]
- Type=oneshot
- ExecStart={binary_path} --robot service run
-+WorkingDirectory={data_dir}
-+SuccessExitStatus=0
- TimeoutStartSec=900
-```
-
-If you want, I can produce a single consolidated “v3 plan” markdown with these revisions already merged into your original structure.

plans/lore-service.feedback-4.md

@@ -1,190 +0,0 @@
-No `## Rejected Recommendations` section was present in the plan you shared, so the proposals below are all net-new.
-
-1. **Make scheduled runs explicitly target a single service instance**
-Analysis: right now `service run` has no selector, but the plan supports multiple installed services. That creates ambiguity and incorrect manifest/status selection. This is the most important architectural fix.
-
-```diff
-@@ `lore service install` What it does
-- runs `lore --robot service run` at the specified interval
-+ runs `lore --robot service run --service-id <service_id>` at the specified interval
-
-@@ Robot output (`install`)
-- "sync_command": "/usr/local/bin/lore --robot service run",
-+ "sync_command": "/usr/local/bin/lore --robot service run --service-id a1b2c3d4",
-
-@@ `ServiceCommand` enum
-- #[command(hide = true)]
-- Run,
-+ #[command(hide = true)]
-+ Run {
-+     /// Internal selector injected by scheduler backend
-+     #[arg(long, hide = true)]
-+     service_id: String,
-+ },
-
-@@ `handle_service_run` signature
--pub fn handle_service_run(start: std::time::Instant) -> Result<(), Box<dyn std::error::Error>>
-+pub fn handle_service_run(service_id: &str, start: std::time::Instant) -> Result<(), Box<dyn std::error::Error>>
-
-@@ run flow step 1
-- Read install manifest
-+ Read install manifest for `service_id`
-```
-
-2. **Strengthen `service_id` derivation to avoid cross-workspace collisions**
-Analysis: hashing config path alone can collide when many workspaces share one global config. Identity should represent what is being synced, not only where config lives.
-
-```diff
-@@ Key Design Principles / Project-Scoped Service Identity
-- derive from a stable hash of the config file path
-+ derive from a stable fingerprint of:
-+ - canonical workspace root
-+ - normalized configured GitLab project URLs
-+ - canonical config path
-+ then take first 12 hex chars of SHA-256
-
-@@ `compute_service_id`
-- Returns first 8 hex chars of SHA-256 of the canonical config path.
-+ Returns first 12 hex chars of SHA-256 of a canonical identity tuple
-+ (workspace_root + sorted project URLs + config_path).
-```
-
-3. **Introduce a service-state machine with a dedicated admin lock**
-Analysis: install/uninstall/pause/resume/repair/status can race each other. A lock and explicit transition table prevents invalid states and file races.
-
-```diff
-@@ New section: Service State Model
-+ All state mutations are serialized by `AppLock("service-admin-{service_id}")`.
-+ Legal transitions:
-+ - idle -> running -> success|degraded|backoff|paused
-+ - backoff -> running|paused
-+ - paused -> half_open|running (resume)
-+ - half_open -> running|paused
-+ Any invalid transition is rejected with `ServiceCorruptState`.
-
-@@ `handle_install`, `handle_uninstall`, `handle_pause`, `handle_resume`, `handle_repair`
-+ Acquire `service-admin-{service_id}` before mutating manifest/status/service files.
-```
-
-4. **Unify manual and scheduled sync execution behind one orchestrator**
-Analysis: the plan currently duplicates stage logic and error classification in `service run`, increasing drift risk. A shared orchestrator gives one authoritative pipeline behavior.
-
-```diff
-@@ Key Design Principles
-+ #### 6. Single Sync Orchestrator
-+ Both `lore sync` and `lore service run` call `SyncOrchestrator`.
-+ Service mode adds policy (backoff/circuit-breaker); manual mode bypasses policy.
-
-@@ Service Run Implementation
-- execute_sync_stages(&sync_args)
-+ SyncOrchestrator::run(SyncMode::Service { profile, policy })
-
-@@ manual sync
-- separate pipeline path
-+ SyncOrchestrator::run(SyncMode::Manual { flags })
-```
-
-5. **Add bounded in-run retries for transient core-stage failures**
-Analysis: single-shot failure handling will over-trigger backoff on temporary network blips. One short retry per core stage significantly improves freshness without much extra runtime.
-
-```diff
-@@ Stage-aware execution
-+ Core stages (`issues`, `mrs`) get up to 1 immediate retry on transient errors
-+ (jittered 1-5s). Permanent errors are never retried.
-+ Optional stages keep best-effort semantics.
-
-@@ Acceptance criteria (`service run`)
-+ Retries transient core stage failures once before counting run as failed.
-```
-
-6. **Harden persistence with full crash-safety semantics**
-Analysis: current atomic write description is good but incomplete for power-loss durability. You should fsync parent directory after rename and include lightweight integrity metadata.
-
-```diff
-@@ `write_atomic`
-- tmp file + fsync + rename
-+ tmp file + fsync(file) + rename + fsync(parent_dir)
-
-@@ `ServiceManifest` and `SyncStatusFile`
-+ pub write_seq: u64,
-+ pub content_sha256: String, // optional integrity guard for repair/doctor
-```
-
-7. **Fix token handling to avoid shell/env injection and add secure-store mode**
-Analysis: sourcing env files in shell is brittle if token contains special chars/newlines. Also, secure OS credential stores should be first-class for production reliability/security.
-
-```diff
-@@ Token storage strategies
--| `env-file` (default) ...
-+| `auto` (default) | use secure-store when available, else env-file |
-+| `secure-store` | macOS Keychain / libsecret / Windows Credential Manager |
-+| `env-file` | explicit fallback |
-
-@@ macOS wrapper script
--. "{data_dir}/service-env-{service_id}"
--export {token_env_var}
-+TOKEN_VALUE="$(cat "{data_dir}/service-token-{service_id}" )"
-+export {token_env_var}="$TOKEN_VALUE"
-
-@@ Acceptance criteria
-+ Reject token values containing `\0` or newline for env-file mode.
-+ Never eval/source untrusted token content.
-```
-
-8. **Correct platform/runtime implementation hazards**
-Analysis: there are a few correctness risks that should be fixed in-plan now.
-
-```diff
-@@ macOS install steps
-- Get UID via `unsafe { libc::getuid() }`
-+ Get UID via safe API (`nix::unistd::Uid::current()` or equivalent safe helper)
-
-@@ Command Runner Helper
-- poll try_wait and read stdout/stderr after exit
-+ avoid potential pipe backpressure deadlock:
-+ use wait-with-timeout + concurrent stdout/stderr draining
-
-@@ Linux timer
-- OnUnitActiveSec={interval_seconds}s
-+ OnUnitInactiveSec={interval_seconds}s
-+ AccuracySec=1min
-```
-
-9. **Make logs fully service-scoped**
-Analysis: you already scoped manifest/status by `service_id`; logs are still global in several places. Multi-service installs will overwrite each other’s logs.
-
-```diff
-@@ Paths Module Additions
--pub fn get_service_log_path() -> PathBuf
-+pub fn get_service_log_path(service_id: &str, stream: LogStream) -> PathBuf
-
-@@ log filenames
-- logs/service-stderr.log
-- logs/service-stdout.log
-+ logs/service-{service_id}-stderr.log
-+ logs/service-{service_id}-stdout.log
-
-@@ `service logs`
-- default path: `{data_dir}/logs/service-stderr.log`
-+ default path: `{data_dir}/logs/service-{service_id}-stderr.log`
-```
-
-10. **Resolve internal spec contradictions and rollback gaps**
-Analysis: there are a few contradictory statements and incomplete rollback behavior that will cause implementation churn.
-
-```diff
-@@ `service logs` behavior
-- default (no flags): open in editor (human)
-+ default (no flags): print last 100 lines (human and robot metadata mode)
-+ `--open` is explicit opt-in
-
-@@ install rollback
-- On failure: removes generated service files
-+ On failure: removes generated service files, env file, wrapper script, and temp manifest
-
-@@ `handle_service_run` sample code
-- let manifest_path = get_service_manifest_path();
-+ let manifest_path = get_service_manifest_path(service_id);
-```
-
-If you want, I can take these revisions and produce a single consolidated “Iteration 4” replacement plan block with all sections rewritten coherently so it’s ready to hand to an implementer.

plans/time-decay-expert-scoring.feedback-1.md

@@ -1,114 +0,0 @@
-Your plan is strong directionally, but I’d revise it in 8 key places to avoid regressions and make it significantly more useful in production.
-
-1. **Split reviewer signals into “participated” vs “assigned-only”**
-Reason: today’s inflation problem is often assignment noise. Treating `mr_reviewers` equal to real review activity still over-ranks passive reviewers.
-
-```diff
-@@ Per-signal contributions
--| Reviewer (reviewed MR touching path) | 10 | 90 days |
-+| ReviewerParticipated (left DiffNote on MR/path) | 10 | 90 days |
-+| ReviewerAssignedOnly (in mr_reviewers, no DiffNote by that user on MR/path) | 3 | 45 days |
-```
-
-```diff
-@@ Scoring Formula
--score = reviewer_mr * reviewer_weight + ...
-+score = reviewer_participated * reviewer_weight
-+      + reviewer_assigned_only * reviewer_assignment_weight
-+      + ...
-```
-
-2. **Cap/saturate note intensity per MR**
-Reason: raw per-note addition can still reward “comment storms.” Use diminishing returns.
-
-```diff
-@@ Rust-Side Aggregation
--- Notes: Vec<i64> (timestamps) from diffnote_reviewer
-+-- Notes grouped per (username, mr_id): note_count + max_ts
-+-- Note contribution per MR uses diminishing returns:
-+-- note_score_mr = note_bonus * ln(1 + note_count) * decay(now - ts, note_hl)
-```
-
-3. **Use better event timestamps than `m.updated_at` for file-change signals**
-Reason: `updated_at` is noisy (title edits, metadata touches) and creates false recency.
-
-```diff
-@@ SQL Restructure
-- signal 3/4 seen_at = m.updated_at
-+ signal 3/4 activity_ts = COALESCE(m.merged_at, m.closed_at, m.created_at, m.updated_at)
-```
-
-4. **Don’t stream raw note rows to Rust; pre-aggregate in SQL**
-Reason: current plan removes SQL grouping and can blow up memory/latency on large repos.
-
-```diff
-@@ SQL Restructure
--SELECT username, signal, mr_id, note_id, ts FROM signals
-+WITH raw_signals AS (...),
-+aggregated AS (
-+  -- 1 row per (username, signal_class, mr_id) for MR-level signals
-+  -- 1 row per (username, mr_id) for note_count + max_ts
-+)
-+SELECT username, signal_class, mr_id, qty, ts FROM aggregated
-```
-
-5. **Replace fixed `"24m"` with model-driven cutoff**
-Reason: hardcoded 24m is arbitrary and tied to current weights/half-lives only.
-
-```diff
-@@ Default --since Change
--Expert mode: "6m" -> "24m"
-+Expert mode default window derived from scoring.max_age_days (default 1095 days / 36m).
-+Formula guidance: choose max_age where max possible single-event contribution < epsilon (e.g. 0.25 points).
-+Add `--all-history` to disable cutoff for diagnostics.
-```
-
-6. **Validate scoring config explicitly**
-Reason: silent bad configs (`half_life_days = 0`, negative weights) create undefined behavior.
-
-```diff
-@@ ScoringConfig (config.rs)
- pub struct ScoringConfig {
-   pub author_weight: i64,
-   pub reviewer_weight: i64,
-   pub note_bonus: i64,
-+  pub reviewer_assignment_weight: i64,   // default: 3
-   pub author_half_life_days: u32,
-   pub reviewer_half_life_days: u32,
-   pub note_half_life_days: u32,
-+  pub reviewer_assignment_half_life_days: u32, // default: 45
-+  pub max_age_days: u32, // default: 1095
- }
-@@ Config::load_from_path
-+validate_scoring(&config.scoring)?; // weights >= 0, half_life_days > 0, max_age_days >= 30
-```
-
-7. **Keep raw float score internally; round only for display**
-Reason: rounding before sort causes avoidable ties/rank instability.
-
-```diff
-@@ Rust-Side Aggregation
--Round to i64 for Expert.score field
-+Compute `raw_score: f64`, sort by raw_score DESC.
-+Expose integer `score` for existing UX.
-+Optionally expose `score_raw` and `score_components` in robot JSON when `--explain-score`.
-```
-
-8. **Add confidence + data-completeness metadata**
-Reason: rankings are misleading if `mr_file_changes` coverage is poor.
-
-```diff
-@@ ExpertResult / Output
-+confidence: "high" | "medium" | "low"
-+coverage: { mrs_with_file_changes, total_mrs_in_window, percent }
-+warning when coverage < threshold (e.g. 70%)
-```
-
-```diff
-@@ Verification
- 4. cargo test
-+5. ubs src/cli/commands/who.rs src/core/config.rs
-+6. Benchmark query_expert on representative DB (latency + rows scanned before/after)
-```
-
-If you want, I can rewrite your full plan document into a clean “v2” version that already incorporates these diffs end-to-end.

plans/time-decay-expert-scoring.feedback-2.md

@@ -1,132 +0,0 @@
-The plan is strong, but I’d revise it in 10 places to improve correctness, scalability, and operator trust.
-
-1. **Add rename/old-path awareness (correctness gap)**
-Analysis: right now both existing code and your plan still center on `position_new_path` / `new_path` matches (`src/cli/commands/who.rs:643`, `src/cli/commands/who.rs:681`). That misses expertise on renamed/deleted paths and under-ranks long-time owners after refactors.
-
-```diff
-@@ ## Context
--This produces two compounding problems:
-+This produces three compounding problems:
-@@
- 2. **Reviewer inflation**: ...
-+3. **Path-history blindness**: Renamed/moved files lose historical expertise because matching relies on current-path fields only.
-
-@@ ### 3. SQL Restructure (who.rs)
--AND n.position_new_path {path_op}
-+AND (n.position_new_path {path_op} OR n.position_old_path {path_op})
-
--AND fc.new_path {path_op}
-+AND (fc.new_path {path_op} OR fc.old_path {path_op})
-```
-
-2. **Follow rename chains for queried paths**
-Analysis: matching `old_path` helps, but true continuity needs alias expansion (A→B→C). Without this, expertise before multi-hop renames is fragmented.
-
-```diff
-@@ ### 3. SQL Restructure (who.rs)
-+**Path alias expansion**: Before scoring, resolve a bounded rename alias set (default max depth: 20)
-+from `mr_file_changes(change_type='renamed')`. Query signals against all aliases.
-+Output includes `path_aliases_used` for transparency.
-```
-
-3. **Use hybrid SQL pre-aggregation instead of fully raw rows**
-Analysis: the “raw row” design is simpler but will degrade on large repos with heavy DiffNote volume. Pre-aggregating to `(user, mr)` for MR signals and `(user, mr, note_count)` for note signals keeps memory/latency predictable.
-
-```diff
-@@ ### 3. SQL Restructure (who.rs)
--The SQL CTE ... removes the outer GROUP BY aggregation. Instead, it returns raw signal rows:
--SELECT username, signal, mr_id, note_id, ts FROM signals
-+Use hybrid aggregation:
-+- SQL returns MR-level rows for author/reviewer signals (1 row per user+MR+signal_class)
-+- SQL returns note groups (1 row per user+MR with note_count, max_ts)
-+- Rust applies decay + ln(1+count) + final ranking.
-```
-
-4. **Make timestamp policy state-aware (merged vs opened)**
-Analysis: replacing `updated_at` with only `COALESCE(merged_at, created_at)` over-decays long-running open MRs. Open MRs need recency from active lifecycle; merged MRs should anchor to merge time.
-
-```diff
-@@ ### 3. SQL Restructure (who.rs)
--Replace m.updated_at with COALESCE(m.merged_at, m.created_at)
-+Use state-aware timestamp:
-+activity_ts =
-+  CASE
-+    WHEN m.state = 'merged' THEN COALESCE(m.merged_at, m.updated_at, m.created_at, m.last_seen_at)
-+    WHEN m.state = 'opened' THEN COALESCE(m.updated_at, m.created_at, m.last_seen_at)
-+  END
-```
-
-5. **Replace fixed `24m` with config-driven max age**
-Analysis: `24m` is reasonable now, but brittle after tuning weights/half-lives. Tie cutoff to config so model behavior remains coherent as parameters evolve.
-
-```diff
-@@ ### 1. ScoringConfig (config.rs)
-+pub max_age_days: u32,                  // default: 730 (or 1095)
-
-@@ ### 5. Default --since Change
--Expert mode: "6m" -> "24m"
-+Expert mode default window derives from `scoring.max_age_days`
-+unless user passes `--since` or `--all-history`.
-```
-
-6. **Add reproducible scoring time via `--as-of`**
-Analysis: decayed ranking is time-sensitive; debugging and tests become flaky without a fixed reference clock. This improves reliability and incident triage.
-
-```diff
-@@ ## Files to Modify
--2. src/cli/commands/who.rs
-+2. src/cli/commands/who.rs
-+3. src/cli/mod.rs
-+4. src/main.rs
-
-@@ ### 5. Default --since Change
-+Add `--as-of <RFC3339|YYYY-MM-DD>` to score at a fixed timestamp.
-+`resolved_input` includes `as_of_ms` and `as_of_iso`.
-```
-
-7. **Add explainability output (`--explain-score`)**
-Analysis: decayed multi-signal ranking will be disputed without decomposition. Show components and top evidence MRs to make results actionable and debuggable.
-
-```diff
-@@ ## Rejected Ideas (with rationale)
--- **`--explain-score` flag with component breakdown**: ... deferred
-+**Included in this iteration**: `--explain-score` adds per-user score components
-+(`author`, `review_participated`, `review_assigned`, `notes`) plus top evidence MRs.
-```
-
-8. **Add confidence/coverage metadata**
-Analysis: rankings can look precise while data is incomplete (`mr_file_changes` gaps, sparse DiffNotes). Confidence fields prevent false certainty.
-
-```diff
-@@ ### 4. Rust-Side Aggregation (who.rs)
-+Compute and emit:
-+- `coverage`: {mrs_considered, mrs_with_file_changes, mrs_with_diffnotes, percent}
-+- `confidence`: high|medium|low (threshold-based)
-```
-
-9. **Add index migration for new query shapes**
-Analysis: your new `EXISTS/NOT EXISTS` reviewer split and path dual-matching will need better indexes; current `who` indexes are not enough for author+path+time combinations.
-
-```diff
-@@ ## Files to Modify
-+3. **`migrations/021_who_decay_indexes.sql`** — indexes for decay query patterns:
-+   - notes(diffnote path + author + created_at + discussion_id) partial
-+   - notes(old_path variant) partial
-+   - mr_file_changes(project_id, new_path, merge_request_id)
-+   - mr_file_changes(project_id, old_path, merge_request_id) partial
-+   - merge_requests(state, merged_at, updated_at, created_at)
-```
-
-10. **Expand tests to invariants and determinism**
-Analysis: example-based tests are good, but ranking systems need invariant tests to avoid subtle regressions.
-
-```diff
-@@ ### 7. New Tests (TDD)
-+**`test_score_monotonicity_by_age`**: same signal, older timestamp never scores higher
-+**`test_row_order_independence`**: shuffled SQL row order yields identical ranking
-+**`test_as_of_reproducibility`**: same data + same `--as-of` => identical output
-+**`test_rename_alias_chain_scoring`**: expertise carries across A->B->C rename chain
-+**`test_overlap_participated_vs_assigned_counts`**: overlap reflects split reviewer semantics
-```
-
-If you want, I can produce a full consolidated `v2` plan doc patch (single unified diff against `plans/time-decay-expert-scoring.md`) rather than per-change snippets.

plans/time-decay-expert-scoring.feedback-3.md

@@ -1,167 +0,0 @@
-**Critical Plan Findings First**
-1. The proposed index `idx_notes_mr_path_author ON notes(noteable_id, ...)` will fail: `notes.noteable_id` does not exist in schema (`migrations/002_issues.sql:74`).
-2. Rename awareness is only applied in scoring queries, not in path resolution probes; today `build_path_query()` and `suffix_probe()` only inspect `position_new_path`/`new_path` (`src/cli/commands/who.rs:465`, `src/cli/commands/who.rs:591`), so old-path queries can still miss.
-3. A fixed `"24m"` default window is brittle once half-lives become configurable; it can silently truncate meaningful history for larger half-lives.
-
-Below are the revisions I’d make to your plan.
-
-1. **Fix migration/index architecture (blocking correctness + perf)**
-Rationale: prevents migration failure and aligns indexes to actual query shapes.
-```diff
-diff --git a/plan.md b/plan.md
-@@ ### 6. Index Migration (db.rs)
-- -- Support EXISTS subquery for reviewer participation check
-- CREATE INDEX IF NOT EXISTS idx_notes_mr_path_author
--   ON notes(noteable_id, position_new_path, author_username)
--   WHERE note_type = 'DiffNote' AND is_system = 0;
-+ -- Support reviewer participation joins (notes -> discussions -> MR)
-+ CREATE INDEX IF NOT EXISTS idx_notes_diffnote_discussion_author_created
-+   ON notes(discussion_id, author_username, created_at)
-+   WHERE note_type = 'DiffNote' AND is_system = 0;
-+
-+ -- Path-first indexes for global and project-scoped path lookups
-+ CREATE INDEX IF NOT EXISTS idx_mfc_new_path_project_mr
-+   ON mr_file_changes(new_path, project_id, merge_request_id);
-+ CREATE INDEX IF NOT EXISTS idx_mfc_old_path_project_mr
-+   ON mr_file_changes(old_path, project_id, merge_request_id)
-+   WHERE old_path IS NOT NULL;
-@@
-- -- Support state-aware timestamp selection
-- CREATE INDEX IF NOT EXISTS idx_mr_state_timestamps
--   ON merge_requests(state, merged_at, closed_at, updated_at, created_at);
-+ -- Removed: low-selectivity timestamp composite index; joins are MR-id driven.
-```
-
-2. **Restructure SQL around `matched_mrs` CTE instead of repeating OR path clauses**
-Rationale: better index use, less duplicated logic, cleaner maintenance.
-```diff
-diff --git a/plan.md b/plan.md
-@@ ### 3. SQL Restructure (who.rs)
-- WITH raw AS (
--   -- 5 UNION ALL subqueries (signals 1, 2, 3, 4a, 4b)
-- ),
-+ WITH matched_notes AS (
-+   -- DiffNotes matching new_path
-+   ...
-+   UNION ALL
-+   -- DiffNotes matching old_path
-+   ...
-+ ),
-+ matched_file_changes AS (
-+   -- file changes matching new_path
-+   ...
-+   UNION ALL
-+   -- file changes matching old_path
-+   ...
-+ ),
-+ matched_mrs AS (
-+   SELECT DISTINCT mr_id, project_id FROM matched_notes
-+   UNION
-+   SELECT DISTINCT mr_id, project_id FROM matched_file_changes
-+ ),
-+ raw AS (
-+   -- signals sourced from matched_mrs + matched_notes
-+ ),
-```
-
-3. **Replace correlated `EXISTS/NOT EXISTS` reviewer split with one precomputed participation set**
-Rationale: same semantics, lower query cost, easier reasoning.
-```diff
-diff --git a/plan.md b/plan.md
-@@ Signal 4 splits into two
-- Signal 4a uses an EXISTS subquery ...
-- Signal 4b uses NOT EXISTS ...
-+ Build `reviewer_participation(mr_id, username)` once from matched DiffNotes.
-+ Then classify `mr_reviewers` rows via LEFT JOIN:
-+ - participated: `rp.username IS NOT NULL`
-+ - assigned-only: `rp.username IS NULL`
-+ This avoids correlated EXISTS scans per reviewer row.
-```
-
-4. **Make default `--since` derived from half-life + decay floor, not hardcoded 24m**
-Rationale: remains mathematically consistent when config changes.
-```diff
-diff --git a/plan.md b/plan.md
-@@ ### 1. ScoringConfig (config.rs)
-+ pub decay_floor: f64, // default: 0.05
-@@ ### 5. Default --since Change
-- Expert mode: "6m" -> "24m"
-+ Expert mode default window is computed:
-+ default_since_days = ceil(max_half_life_days * log2(1.0 / decay_floor))
-+ With defaults (max_half_life=180, floor=0.05), this is ~26 months.
-+ CLI `--since` still overrides; `--all-history` still disables windowing.
-```
-
-5. **Use `log2(1+count)` for notes instead of `ln(1+count)`**
-Rationale: keeps 1 note ~= 1 unit (with `note_bonus=1`) while preserving diminishing returns.
-```diff
-diff --git a/plan.md b/plan.md
-@@ Scoring Formula
-- note_contribution(mr) = note_bonus * ln(1 + note_count_in_mr) * 2^(-days_elapsed / note_half_life)
-+ note_contribution(mr) = note_bonus * log2(1 + note_count_in_mr) * 2^(-days_elapsed / note_half_life)
-```
-
-6. **Guarantee deterministic float aggregation and expose `score_raw`**
-Rationale: avoids hash-order drift and explainability mismatch vs rounded integer score.
-```diff
-diff --git a/plan.md b/plan.md
-@@ ### 4. Rust-Side Aggregation (who.rs)
-- HashMap<i64, ...>
-+ BTreeMap<i64, ...> (or sort keys before accumulation) for deterministic summation order
-+ Use compensated summation (Kahan/Neumaier) for stable f64 totals
-@@
-- Sort on raw `f64` score ... round only for display
-+ Keep `score_raw` internally and expose when `--explain-score` is active.
-+ `score` remains integer for backward compatibility.
-```
-
-7. **Extend rename awareness to query resolution (not only scoring)**
-Rationale: fixes user-facing misses for old path input and suffix lookup.
-```diff
-diff --git a/plan.md b/plan.md
-@@ Path rename awareness
-- All signal subqueries match both old and new path columns
-+ Also update `build_path_query()` probes and suffix probe:
-+ - exact_exists: new_path OR old_path (notes + mr_file_changes)
-+ - prefix_exists: new_path LIKE OR old_path LIKE
-+ - suffix_probe: union of notes.position_new_path, notes.position_old_path,
-+   mr_file_changes.new_path, mr_file_changes.old_path
-```
-
-8. **Tighten CLI/output contracts for new flags**
-Rationale: avoids payload bloat/ambiguity and keeps robot clients stable.
-```diff
-diff --git a/plan.md b/plan.md
-@@ ### 5b. Score Explainability via `--explain-score`
-+ `--explain-score` conflicts with `--detail` (mutually exclusive)
-+ `resolved_input` includes `as_of_ms`, `as_of_iso`, `scoring_model_version`
-+ robot output includes `score_raw` and `components` only when explain is enabled
-```
-
-9. **Add confidence metadata (promote from rejected to accepted)**
-Rationale: makes ranking more actionable and trustworthy with sparse evidence.
-```diff
-diff --git a/plan.md b/plan.md
-@@ Rejected Ideas (with rationale)
-- Confidence/coverage metadata: ... Deferred to avoid scope creep
-+ Confidence/coverage metadata: ACCEPTED (minimal v1)
-+ Add per-user `confidence: low|medium|high` based on evidence breadth + recency.
-+ Keep implementation lightweight (no extra SQL pass).
-```
-
-10. **Upgrade test and verification scope to include query-plan and clock semantics**
-Rationale: catches regressions your current tests won’t.
-```diff
-diff --git a/plan.md b/plan.md
-@@ 8. New Tests (TDD)
-+ test_old_path_probe_exact_and_prefix
-+ test_suffix_probe_uses_old_path_sources
-+ test_since_relative_to_as_of_clock
-+ test_explain_and_detail_are_mutually_exclusive
-+ test_null_timestamp_fallback_to_created_at
-+ test_query_plan_uses_path_indexes (EXPLAIN QUERY PLAN)
-@@ Verification
-+ 7. EXPLAIN QUERY PLAN snapshots for expert query (exact + prefix) confirm index usage
-```
-
-If you want, I can produce a single consolidated “revision 3” plan document that fully merges all of the above into your original structure.

plans/time-decay-expert-scoring.feedback-4.md

@@ -1,133 +0,0 @@
-Your plan is already strong. The biggest remaining gaps are temporal correctness, indexability at scale, and ranking reliability under sparse/noisy evidence. These are the revisions I’d make.
-
-1. **Fix temporal correctness for `--as-of` (critical)**
-Analysis: Right now the plan describes `--as-of`, but the SQL only enforces lower bounds (`>= since`). If `as_of` is in the past, “future” events can still enter and get full weight (because elapsed is clamped). This breaks reproducibility.
-```diff
-@@ 3. SQL Restructure
-- AND n.created_at >= ?2
-+ AND n.created_at BETWEEN ?2 AND ?4
-@@ Signal 3/4a/4b
-- AND {state_aware_ts} >= ?2
-+ AND {state_aware_ts} BETWEEN ?2 AND ?4
-
-@@ 5a. Reproducible Scoring via --as-of
-- All decay computations use as_of_ms instead of SystemTime::now()
-+ All event selection and decay computations are bounded by as_of_ms.
-+ Query window is [since_ms, as_of_ms], never [since_ms, now_ms].
-+ Add test: test_as_of_excludes_future_events.
-```
-
-2. **Resolve `closed`-state inconsistency**
-Analysis: The CASE handles `closed`, but all signal queries filter to `('opened','merged')`, making the `closed_at` branch dead code. Either include closed MRs intentionally or remove that logic. I’d include closed with a reduced multiplier.
-```diff
-@@ ScoringConfig (config.rs)
-+ pub closed_mr_multiplier: f64, // default: 0.5
-
-@@ 3. SQL Restructure
-- AND m.state IN ('opened','merged')
-+ AND m.state IN ('opened','merged','closed')
-
-@@ 4. Rust-Side Aggregation
-+ if state == "closed" { contribution *= closed_mr_multiplier; }
-```
-
-3. **Replace `OR` path predicates with index-friendly `UNION ALL` branches**
-Analysis: `(new_path ... OR old_path ...)` often degrades index usage in SQLite. Split into two indexed branches and dedupe once. This improves planner stability and latency on large datasets.
-```diff
-@@ 3. SQL Restructure
--WITH matched_notes AS (
--  ... AND (n.position_new_path {path_op} OR n.position_old_path {path_op})
--),
-+WITH matched_notes AS (
-+  SELECT ... FROM notes n WHERE ... AND n.position_new_path {path_op}
-+  UNION ALL
-+  SELECT ... FROM notes n WHERE ... AND n.position_old_path {path_op}
-+),
-+matched_notes_dedup AS (
-+  SELECT DISTINCT id, discussion_id, author_username, created_at, project_id
-+  FROM matched_notes
-+),
-@@
-- JOIN matched_notes mn ...
-+ JOIN matched_notes_dedup mn ...
-```
-
-4. **Add canonical path identity (rename-chain support)**
-Analysis: Direct `old_path/new_path` matching only handles one-hop rename scenarios. A small alias graph/table built at ingest time gives robust expertise continuity across A→B→C chains and avoids repeated SQL complexity.
-```diff
-@@ Files to Modify
-- 3. src/core/db.rs — Add migration for indexes...
-+ 3. src/core/db.rs — Add migration for indexes + path_identity table
-+ 4. src/core/ingest/*.rs — populate path_identity on rename events
-+ 5. src/cli/commands/who.rs — resolve query path to canonical path_id first
-
-@@ Context
-- The fix has three parts:
-+ The fix has four parts:
-+ - Introduce canonical path identity so multi-hop renames preserve expertise
-```
-
-5. **Split scoring engine into a versioned core module**
-Analysis: `who.rs` is becoming a mixed CLI/query/math/output surface. Move scoring math and event normalization into `src/core/scoring/` with explicit model versions. This reduces regression risk and enables future model experiments.
-```diff
-@@ Files to Modify
-+ 4. src/core/scoring/mod.rs — model interface + shared types
-+ 5. src/core/scoring/model_v2_decay.rs — current implementation
-+ 6. src/cli/commands/who.rs — orchestration only
-
-@@ 5b. Score Explainability
-+ resolved_input includes scoring_model_version and scoring_model_name
-```
-
-6. **Add evidence confidence to reduce sparse-data rank spikes**
-Analysis: One recent MR can outrank broader, steadier expertise. Add a confidence factor derived from number of distinct evidence MRs and expose both `score_raw` and `score_adjusted`.
-```diff
-@@ Scoring Formula
-+ confidence(user) = 1 - exp(-evidence_mr_count / 6.0)
-+ score_adjusted = score_raw * confidence
-
-@@ 4. Rust-Side Aggregation
-+ compute evidence_mr_count from unique MR ids across all signals
-+ sort by score_adjusted DESC, then score_raw DESC, then last_seen DESC
-
-@@ 5b. --explain-score
-+ include confidence and evidence_mr_count
-```
-
-7. **Add first-class bot/service-account filtering**
-Analysis: Reviewer inflation is not just assignment; bots and automation users can still pollute rankings. Make exclusion explicit and configurable.
-```diff
-@@ ScoringConfig (config.rs)
-+ pub excluded_username_patterns: Vec<String>, // defaults include "*bot*", "renovate", "dependabot"
-
-@@ 3. SQL Restructure
-+ AND username NOT MATCHES excluded patterns (applied in Rust post-query or SQL where feasible)
-
-@@ CLI
-+ --include-bots (override exclusions)
-```
-
-8. **Tighten reviewer “participated” with substantive-note threshold**
-Analysis: A single “LGTM” note shouldn’t classify someone as engaged reviewer equivalent to real inline review. Use a minimum substantive threshold.
-```diff
-@@ ScoringConfig (config.rs)
-+ pub reviewer_min_note_chars: u32, // default: 20
-
-@@ reviewer_participation CTE
-- SELECT DISTINCT ... FROM matched_notes
-+ SELECT DISTINCT ... FROM matched_notes
-+ WHERE LENGTH(TRIM(body)) >= ?reviewer_min_note_chars
-```
-
-9. **Add rollout safety: model compare mode + rank-delta diagnostics**
-Analysis: This is a scoring-model migration. You need safe rollout mechanics, not just tests. Add a compare mode so you can inspect rank deltas before forcing v2.
-```diff
-@@ CLI (who)
-+ --scoring-model v1|v2|compare   (default: v2)
-+ --max-rank-delta-report N       (compare mode diagnostics)
-
-@@ Robot output
-+ include v1_score, v2_score, rank_delta when --scoring-model compare
-```
-
-If you want, I can produce a single consolidated “plan v4” document that applies all nine diffs cleanly into your original markdown.

plans/tui-prd-v2-frankentui.feedback-1.md

@@ -1,209 +0,0 @@
-No `## Rejected Recommendations` section was present, so these are all net-new improvements.
-
-1. Keep core `lore` stable; isolate nightly to a TUI crate  
-Rationale: the current plan says “whole project nightly” but later assumes TUI is feature-gated. Isolating nightly removes unnecessary risk from non-TUI users, CI, and release cadence.
-
-```diff
-@@ 3.2 Nightly Rust Strategy
--- The entire gitlore project moves to pinned nightly, not just the TUI feature.
-+- Keep core `lore` on stable Rust.
-+- Add workspace member `lore-tui` pinned to nightly for FrankenTUI.
-+- Ship `lore tui` only when `--features tui` (or separate `lore-tui` binary) is enabled.
-
-@@ 10.1 New Files
-+- crates/lore-tui/Cargo.toml
-+- crates/lore-tui/src/main.rs
-
-@@ 11. Assumptions
--17. TUI module is feature-gated.
-+17. TUI is isolated in a workspace crate and feature-gated in root CLI integration.
-```
-
-2. Add a framework adapter boundary from day 1  
-Rationale: the “3-day ratatui escape hatch” is optimistic without a strict interface. A tiny `UiRuntime` + screen renderer trait makes fallback real, not aspirational.
-
-```diff
-@@ 4. Architecture
-+### 4.9 UI Runtime Abstraction
-+Introduce `UiRuntime` trait (`run`, `send`, `subscribe`) and `ScreenRenderer` trait.
-+FrankenTUI implementation is default; ratatui adapter can be dropped in with no state/action rewrite.
-
-@@ 3.5 Escape Hatch
--- The migration cost to ratatui is ~3 days
-+- Migration cost target is ~3-5 days, validated by one ratatui spike screen in Phase 1.
-```
-
-3. Stop using CLI command modules as the TUI query API  
-Rationale: coupling TUI to CLI output-era structs creates long-term friction and accidental regressions. Create a shared domain query layer used by both CLI and TUI.
-
-```diff
-@@ 10.20 Refactor: Extract Query Functions
--- extract query_* from cli/commands/*
-+- introduce `src/domain/query/*` as the canonical read model API.
-+- CLI and TUI both depend on domain query layer.
-+- CLI modules retain formatting/output only.
-
-@@ 10.2 Modified Files
-+- src/domain/query/mod.rs
-+- src/domain/query/issues.rs
-+- src/domain/query/mrs.rs
-+- src/domain/query/search.rs
-+- src/domain/query/who.rs
-```
-
-4. Replace single `Arc<Mutex<Connection>>` with connection manager  
-Rationale: one locked connection serializes everything and hurts responsiveness, especially during sync. Use separate read pool + writer connection with WAL and busy timeout.
-
-```diff
-@@ 4.4 App — Implementing the Model Trait
-- pub db: Arc<Mutex<Connection>>,
-+ pub db: Arc<DbManager>, // read pool + single writer coordination
-
-@@ 4.5 Async Action System
-- Each Cmd::task closure locks the mutex, runs the query, and returns a Msg
-+ Reads use pooled read-only connections.
-+ Sync/write path uses dedicated writer connection.
-+ Enforce WAL, busy_timeout, and retry policy for SQLITE_BUSY.
-```
-
-5. Make debouncing/cancellation explicit and correct  
-Rationale: “runtime coalesces rapid keypresses” is not a safe correctness guarantee. Add request IDs and stale-response dropping to prevent flicker and wrong data.
-
-```diff
-@@ 4.3 Core Types (Msg)
-+ SearchRequestStarted { request_id: u64, query: String }
-- SearchExecuted(SearchResults),
-+ SearchExecuted { request_id: u64, results: SearchResults },
-
-@@ 4.4 maybe_debounced_query()
-- runtime coalesces rapid keypresses
-+ use explicit 200ms debounce timer + monotonic request_id
-+ ignore results whose request_id != current_search_request_id
-```
-
-6. Implement true streaming sync, not batch-at-end pseudo-streaming  
-Rationale: the plan promises real-time logs/progress but code currently returns one completion message. This gap will disappoint users and complicate cancellation.
-
-```diff
-@@ 4.4 start_sync_task()
-- Pragmatic approach: run sync synchronously, collect all progress events, return summary.
-+ Use event channel subscription for `SyncProgress`/`SyncLogLine` streaming.
-+ Keep `SyncCompleted` only as terminal event.
-+ Add cooperative cancel token mapped to `Esc` while running.
-
-@@ 5.9 Sync
-+ Add "Resume from checkpoint" option for interrupted syncs.
-```
-
-7. Fix entity identity ambiguity across projects  
-Rationale: using `iid` alone is unsafe in multi-project datasets. Navigation and cross-refs should key by `(project_id, iid)` or global ID.
-
-```diff
-@@ 4.3 Core Types
-- IssueDetail(i64)
-- MrDetail(i64)
-+ IssueDetail(EntityKey)
-+ MrDetail(EntityKey)
-
-+ pub struct EntityKey { pub project_id: i64, pub iid: i64, pub kind: EntityKind }
-
-@@ 10.12.4 Cross-Reference Widget
-- parse "group/project#123" -> iid only
-+ parse into `{project_path, iid, kind}` then resolve to `project_id` before navigation
-```
-
-8. Resolve keybinding conflicts and formalize keymap precedence  
-Rationale: current spec conflicts (`Tab` sort vs focus filter; `gg` vs go-prefix). A deterministic keymap contract prevents UX bugs.
-
-```diff
-@@ 8.2 List Screens
-- Tab | Cycle sort column
-- f   | Focus filter bar
-+ Tab | Focus filter bar
-+ S   | Cycle sort column
-+ /   | Focus filter bar (alias)
-
-@@ 4.4 interpret_key()
-+ Add explicit precedence table:
-+ 1) modal/palette
-+ 2) focused input
-+ 3) global
-+ 4) screen-local
-+ Add configurable go-prefix timeout (default 500ms) with cancel feedback.
-```
-
-9. Add performance SLOs and DB/index plan  
-Rationale: “fast enough” is vague. Add measurable budgets, required indexes, and query-plan gates in CI for predictable performance.
-
-```diff
-@@ 3.1 Risk Matrix
-+ Add risk: "Query latency regressions on large datasets"
-
-@@ 9.3 Phase 0 — Toolchain Gate
-+7. p95 list query latency < 75ms on 100k issues synthetic fixture
-+8. p95 search latency < 200ms on 1M docs (lexical mode)
-
-@@ 11. Assumptions
--5. SQLite queries are fast enough for interactive use (<50ms for filtered results).
-+5. Performance budgets are enforced by benchmark fixtures and query-plan checks.
-+6. Required indexes documented and migration-backed before TUI GA.
-```
-
-10. Add reliability/observability model (error classes, retries, tracing)  
-Rationale: one string toast is not enough for production debugging. Add typed errors, retry policy, and an in-TUI diagnostics pane.
-
-```diff
-@@ 4.3 Core Types (Msg)
-- Error(String),
-+ Error(AppError),
-
-+ pub enum AppError {
-+   DbBusy, DbCorruption, NetworkRateLimited, NetworkUnavailable,
-+   AuthFailed, ParseError, Internal(String)
-+ }
-
-@@ 5.11 Doctor / Stats
-+ Add "Diagnostics" tab:
-+ - last 100 errors
-+ - retry counts
-+ - current sync/backoff state
-+ - DB contention metrics
-```
-
-11. Add “Saved Views + Watchlist” as high-value product features  
-Rationale: this makes the TUI compelling daily, not just navigable. Users can persist filters and monitor critical slices (e.g., “P1 auth issues updated in last 24h”).
-
-```diff
-@@ 1. Executive Summary
-+ - Saved Views (named filters and layouts)
-+ - Watchlist panel (tracked queries with delta badges)
-
-@@ 5. Screen Taxonomy
-+### 5.12 Saved Views / Watchlist
-+Persistent named filters for Issues/MRs/Search.
-+Dashboard shows per-watchlist deltas since last session.
-
-@@ 6. User Flows
-+### 6.9 Flow: "Run morning watchlist triage"
-+Dashboard -> Watchlist -> filtered IssueList/MRList -> detail drilldown
-```
-
-12. Strengthen testing plan with deterministic behavior and chaos cases  
-Rationale: snapshot tests alone won’t catch race/staleness/cancellation issues. Add concurrency, cancellation, and flaky terminal behavior tests.
-
-```diff
-@@ 9.2 Phases
-+Phase 5.5 Reliability Test Pack (2d)
-+ - stale response drop tests
-+ - sync cancel/resume tests
-+ - SQLITE_BUSY retry tests
-+ - resize storm and rapid key-chord tests
-
-@@ 10.9 Snapshot Test Example
-+ Add non-snapshot tests:
-+ - property tests for navigation invariants
-+ - integration tests for request ordering correctness
-+ - benchmark tests for query budgets
-```
-
-If you want, I can produce a consolidated “PRD v2.1 patch” with all of the above merged into one coherent updated document structure.

plans/tui-prd-v2-frankentui.feedback-2.md

@@ -1,203 +0,0 @@
-I excluded the two items in your `## Rejected Recommendations` and focused on net-new improvements.  
-These are the highest-impact revisions I’d make.
-
-### 1. Fix the package graph now (avoid a hard Cargo cycle)
-Your current plan has `root -> optional lore-tui` and `lore-tui -> lore (root)`, which creates a cyclic dependency risk. Split shared logic into a dedicated core crate so CLI and TUI both depend downward.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ ## 9.1 Dependency Changes
--[workspace]
--members = [".", "crates/lore-tui"]
-+[workspace]
-+members = [".", "crates/lore-core", "crates/lore-tui"]
-
-@@
--[dependencies]
--lore-tui = { path = "crates/lore-tui", optional = true }
-+[dependencies]
-+lore-core = { path = "crates/lore-core" }
-+lore-tui = { path = "crates/lore-tui", optional = true }
-
-@@ # crates/lore-tui/Cargo.toml
--lore = { path = "../.." }  # Core lore library
-+lore-core = { path = "../lore-core" }  # Shared domain/query crate (acyclic graph)
-```
-
-### 2. Stop coupling TUI to `cli/commands/*` internals
-Calling CLI command modules from TUI is brittle and will drift. Introduce a shared query/service layer with DTOs owned by core.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ ## 4.1 Module Structure
--    action.rs                     # Async action runners (DB queries, GitLab calls)
-+    action.rs                     # Task dispatch only
-+    service/
-+      mod.rs
-+      query.rs                    # Shared read services (CLI + TUI)
-+      sync.rs                     # Shared sync orchestration facade
-+      dto.rs                      # UI-agnostic data contracts
-
-@@ ## 10.2 Modified Files
--src/cli/commands/list.rs               # Extract query_issues(), query_mrs() as pub fns
--src/cli/commands/show.rs               # Extract query_issue_detail(), query_mr_detail() as pub fns
--src/cli/commands/who.rs                # Extract query_experts(), etc. as pub fns
--src/cli/commands/search.rs             # Extract run_search_query() as pub fn
-+crates/lore-core/src/query/issues.rs   # Canonical issue queries
-+crates/lore-core/src/query/mrs.rs      # Canonical MR queries
-+crates/lore-core/src/query/show.rs     # Canonical detail queries
-+crates/lore-core/src/query/who.rs      # Canonical people queries
-+crates/lore-core/src/query/search.rs   # Canonical search queries
-+src/cli/commands/*.rs                  # Consume lore-core query services
-+crates/lore-tui/src/action.rs          # Consume lore-core query services
-```
-
-### 3. Add a real task supervisor (dedupe + cancellation + priority)
-Right now tasks are ad hoc and can overrun each other. Add a scheduler keyed by screen+intent.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ ## 4.5 Async Action System
--The `Cmd::task(|| { ... })` pattern runs a blocking closure on a background thread pool.
-+The TUI uses a `TaskSupervisor`:
-+- Keyed tasks (`TaskKey`) to dedupe redundant requests
-+- Priority lanes (`Input`, `Navigation`, `Background`)
-+- Cooperative cancellation tokens per task
-+- Late-result drop via generation IDs (not just search)
-
-@@ ## 4.3 Core Types
-+pub enum TaskKey {
-+    LoadScreen(Screen),
-+    Search { generation: u64 },
-+    SyncStream,
-+}
-```
-
-### 4. Correct sync streaming architecture (current sketch loses streamed events)
-The sample creates `tx/rx` then drops `rx`; events never reach update loop. Define an explicit stream subscription with bounded queue and backpressure policy.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ ## 4.4 App — Implementing the Model Trait
--        let (tx, _rx) = std::sync::mpsc::channel::<Msg>();
-+        let (tx, rx) = std::sync::mpsc::sync_channel::<Msg>(1024);
-+        // rx is registered via Subscription::from_receiver("sync-stream", rx)
-
-@@
--            let result = crate::ingestion::orchestrator::run_sync(
-+            let result = crate::ingestion::orchestrator::run_sync(
-                 &config,
-                 &conn,
-                 |event| {
-@@
--                    let _ = tx.send(Msg::SyncProgress(event.clone()));
--                    let _ = tx.send(Msg::SyncLogLine(format!("{event:?}")));
-+                    if tx.try_send(Msg::SyncProgress(event.clone())).is_err() {
-+                        let _ = tx.try_send(Msg::SyncBackpressureDrop);
-+                    }
-+                    let _ = tx.try_send(Msg::SyncLogLine(format!("{event:?}")));
-                 },
-             );
-```
-
-### 5. Upgrade data-plane performance plan (keyset pagination + index contracts)
-Virtualized list without keyset paging still forces expensive scans. Add explicit keyset pagination and query-plan CI checks.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ ## 9.3 Phase 0 — Toolchain Gate
--7. p95 list query latency < 75ms on synthetic fixture (10k issues, 5k MRs)
-+7. p95 list page fetch latency < 75ms using keyset pagination (10k issues, 5k MRs)
-+8. EXPLAIN QUERY PLAN must show index usage for top 10 TUI queries
-+9. No full table scan on issues/MRs/discussions under default filters
-
-@@
--8. p95 search latency < 200ms on synthetic fixture (50k documents, lexical mode)
-+10. p95 search latency < 200ms on synthetic fixture (50k documents, lexical mode)
-
-+## 9.4 Required Indexes (GA blocker)
-+- `issues(project_id, state, updated_at DESC, iid DESC)`
-+- `merge_requests(project_id, state, updated_at DESC, iid DESC)`
-+- `discussions(project_id, entity_type, entity_iid, created_at DESC)`
-+- `notes(discussion_id, created_at ASC)`
-```
-
-### 6. Enforce `EntityKey` everywhere (remove bare IID paths)
-You correctly identified multi-project IID collisions, but many message/state signatures still use `i64`. Make `EntityKey` mandatory in all navigation and detail loaders.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ ## 4.3 Core Types
--    IssueSelected(i64),
-+    IssueSelected(EntityKey),
-@@
--    MrSelected(i64),
-+    MrSelected(EntityKey),
-@@
--    IssueDetailLoaded(IssueDetail),
-+    IssueDetailLoaded { key: EntityKey, detail: IssueDetail },
-@@
--    MrDetailLoaded(MrDetail),
-+    MrDetailLoaded { key: EntityKey, detail: MrDetail },
-
-@@ ## 10.10 State Module — Complete
--                Cmd::msg(Msg::NavigateTo(Screen::IssueDetail(iid)))
-+                Cmd::msg(Msg::NavigateTo(Screen::IssueDetail(entity_key)))
-```
-
-### 7. Harden filter/search semantics (strict parser + inline diagnostics + explain scores)
-Current filter parser silently ignores unknown fields; that causes hidden mistakes. Add strict parse diagnostics and search score explainability.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ ## 10.12.1 Filter Bar Widget
--                _ => {} // Unknown fields silently ignored
-+                _ => self.errors.push(format!("Unknown filter field: {}", token.field))
-
-+    pub errors: Vec<String>,   // inline parse/validation errors
-+    pub warnings: Vec<String>, // non-fatal coercions
-
-@@ ## 5.6 Search
--- **Live preview:** Selected result shows snippet + metadata in right pane
-+- **Live preview:** Selected result shows snippet + metadata in right pane
-+- **Explain score:** Optional breakdown (lexical, semantic, recency, boosts) for trust/debug
-```
-
-### 8. Add operational resilience: safe mode + panic report + startup fallback
-TUI failures should degrade gracefully, not block usage.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ ## 3.1 Risk Matrix
-+| Runtime panic leaves user blocked | High | Medium | Panic hook writes crash report, restores terminal, offers fallback CLI command |
-
-@@ ## 10.3 Entry Point
-+pub fn launch_tui(config: Config, db_path: &Path) -> Result<(), LoreError> {
-+    install_panic_hook_for_tui(); // terminal restore + crash dump path
-+    ...
-+}
-
-@@ ## 8.1 Global (Available Everywhere)
-+| `:` | Show fallback equivalent CLI command for current screen/action |
-```
-
-### 9. Add a “jump list” (forward/back navigation, not only stack pop)
-Current model has only push/pop and reset. Add browser-like history for investigation workflows.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ ## 4.7 Navigation Stack Implementation
- pub struct NavigationStack {
--    stack: Vec<Screen>,
-+    back_stack: Vec<Screen>,
-+    current: Screen,
-+    forward_stack: Vec<Screen>,
-+    jump_list: Vec<Screen>, // recent entity/detail hops
- }
-
-@@ ## 8.1 Global (Available Everywhere)
-+| `Ctrl+o` | Jump backward in jump list |
-+| `Ctrl+i` | Jump forward in jump list |
-```
-
-If you want, I can produce a single consolidated “PRD v2.1” patch that applies all nine revisions coherently section-by-section.

plans/tui-prd-v2-frankentui.feedback-3.md

@@ -1,163 +0,0 @@
-I excluded everything already listed in `## Rejected Recommendations`.  
-These are the highest-impact net-new revisions I’d make.
-
-1. **Enforce Entity Identity Consistency End-to-End (P0)**
-Analysis: The PRD defines `EntityKey`, but many code paths still pass bare `iid` (`IssueSelected(item.iid)`, timeline refs, search refs). In multi-project datasets this will cause wrong-entity navigation and subtle data corruption in cached state. Make `EntityKey` mandatory in every navigation message and add compile-time constructors.
-```diff
-@@ 4.3 Core Types
- pub struct EntityKey {
-     pub project_id: i64,
-     pub iid: i64,
-     pub kind: EntityKind,
- }
-+impl EntityKey {
-+    pub fn issue(project_id: i64, iid: i64) -> Self { Self { project_id, iid, kind: EntityKind::Issue } }
-+    pub fn mr(project_id: i64, iid: i64) -> Self { Self { project_id, iid, kind: EntityKind::MergeRequest } }
-+}
-
-@@ 10.10 state/issue_list.rs
-- .map(|item| Msg::IssueSelected(item.iid))
-+ .map(|item| Msg::IssueSelected(EntityKey::issue(item.project_id, item.iid)))
-
-@@ 10.10 state/mr_list.rs
-- .map(|item| Msg::MrSelected(item.iid))
-+ .map(|item| Msg::MrSelected(EntityKey::mr(item.project_id, item.iid)))
-```
-
-2. **Make TaskSupervisor Mandatory for All Background Work (P0)**
-Analysis: The plan introduces `TaskSupervisor` but still dispatches many direct `Cmd::task` calls. That will reintroduce stale updates, duplicate queries, and priority inversion under rapid input. Centralize all background task creation through one spawn path that enforces dedupe, cancellation tokening, and generation checks.
-```diff
-@@ 4.5.1 Task Supervisor (Dedup + Cancellation + Priority)
--The supervisor is owned by `LoreApp` and consulted before dispatching any `Cmd::task`.
-+The supervisor is owned by `LoreApp` and is the ONLY allowed path for background work.
-+All task launches use `LoreApp::spawn_task(TaskKey, TaskPriority, closure)`.
-
-@@ 4.4 App — Implementing the Model Trait
-- Cmd::task(move || { ... })
-+ self.spawn_task(TaskKey::LoadScreen(screen.clone()), TaskPriority::Navigation, move |token| { ... })
-```
-
-3. **Remove the Sync Streaming TODO and Make Real-Time Streaming a GA Gate (P0)**
-Analysis: Current text admits sync progress is buffered with a TODO. That undercuts one of the main value props. Make streaming progress/log delivery non-optional, with bounded buffers and dropped-line accounting.
-```diff
-@@ 4.4 start_sync_task()
-- // TODO: Register rx as subscription when FrankenTUI supports it.
-- // For now, the task returns the final Msg and progress is buffered.
-+ // Register rx as a live subscription (`Subscription::from_receiver` adapter).
-+ // Progress and logs must render in real time (no batch-at-end fallback).
-+ // Keep a bounded ring buffer (N=5000) and surface `dropped_log_lines` in UI.
-
-@@ 9.3 Phase 0 — Toolchain Gate
-+11. Real-time sync stream verified: progress updates visible during run, not only at completion.
-```
-
-4. **Upgrade List/Search Data Strategy to Windowed Keyset + Prefetch (P0)**
-Analysis: “Virtualized list” alone does not solve query/transfer cost if full result sets are loaded. Move to fixed-size keyset windows with next-window prefetch and fast first paint; this keeps latency predictable on 100k+ records.
-```diff
-@@ 5.2 Issue List
-- Pagination: Virtual scrolling for large result sets
-+ Pagination: Windowed keyset pagination (window=200 rows) with background prefetch of next window.
-+ First paint uses current window only; no full-result materialization.
-
-@@ 5.4 MR List
-+ Same windowed keyset pagination strategy as Issue List.
-
-@@ 9.3 Success criteria
-- 7. p95 list page fetch latency < 75ms using keyset pagination on synthetic fixture (10k issues, 5k MRs)
-+ 7. p95 first-paint latency < 50ms and p95 next-window fetch < 75ms on synthetic fixture (100k issues, 50k MRs)
-```
-
-5. **Add Resumable Sync Checkpoints + Per-Project Fault Isolation (P1)**
-Analysis: If sync is interrupted or one project fails, current design mostly falls back to cancel/fail. Add checkpoints so long runs can resume, and isolate failures to project/resource scope while continuing others.
-```diff
-@@ 3.1 Risk Matrix
-+| Interrupted sync loses progress | High | Medium | Persist phase checkpoints and offer resume |
-
-@@ 5.9 Sync
-+Running mode: failed project/resource lanes are marked degraded while other lanes continue.
-+Summary mode: offer `[R]esume interrupted sync` from last checkpoint.
-
-@@ 11 Assumptions
--16. No new SQLite tables needed (but required indexes must be verified — see Performance SLOs).
-+16. Add minimal internal tables for reliability: `sync_runs` and `sync_checkpoints` (append-only metadata).
-```
-
-6. **Add Capability-Adaptive Rendering Modes (P1)**
-Analysis: Terminal compatibility is currently test-focused, but runtime adaptation is under-specified. Add explicit degradations for no-truecolor, no-unicode, slow SSH/tmux paths to reduce rendering artifacts and support incidents.
-```diff
-@@ 3.4 Terminal Compatibility Testing
-+Add capability matrix validation: truecolor/256/16 color, unicode/ascii glyphs, alt-screen on/off.
-
-@@ 10.19 CLI Integration
-+Tui {
-+  #[arg(long, default_value="auto")] render_mode: String, // auto|full|minimal
-+  #[arg(long)] ascii: bool,
-+  #[arg(long)] no_alt_screen: bool,
-+}
-```
-
-7. **Harden Browser/Open and Log Privacy (P1)**
-Analysis: `open_current_in_browser` currently trusts stored URLs; sync logs may expose tokens/emails from upstream messages. Add host allowlisting and redaction pipeline by default.
-```diff
-@@ 4.4 open_current_in_browser()
-- if let Some(url) = url { ... open ... }
-+ if let Some(url) = url {
-+   if !self.state.security.is_allowed_gitlab_url(&url) {
-+     self.state.set_error("Blocked non-GitLab URL".into());
-+     return;
-+   }
-+   ... open ...
-+ }
-
-@@ 5.9 Sync
-+Log stream passes through redaction (tokens, auth headers, email local-parts) before render/storage.
-```
-
-8. **Add “My Workbench” Screen for Daily Pull (P1, new feature)**
-Analysis: The PRD is strong on exploration, weaker on “what should I do now?”. Add a focused operator screen aggregating assigned issues, requested reviews, unresolved threads mentioning me, and stale approvals. This makes the TUI habit-forming.
-```diff
-@@ 5. Screen Taxonomy
-+### 5.12 My Workbench
-+Single-screen triage cockpit:
-+- Assigned-to-me open issues/MRs
-+- Review requests awaiting action
-+- Threads mentioning me and unresolved
-+- Recently stale approvals / blocked MRs
-
-@@ 8.1 Global
-+| `gb` | Go to My Workbench |
-
-@@ 9.2 Phases
-+section Phase 3.5 — Daily Workflow
-+My Workbench screen + queries :p35a, after p3d, 2d
-```
-
-9. **Add Rollout, SLO Telemetry, and Kill-Switch Plan (P0)**
-Analysis: You have implementation phases but no production rollout control. Add explicit experiment flags, health telemetry, and rollback criteria so risk is operationally bounded.
-```diff
-@@ Table of Contents
--11. [Assumptions](#11-assumptions)
-+11. [Assumptions](#11-assumptions)
-+12. [Rollout & Telemetry](#12-rollout--telemetry)
-
-@@ NEW SECTION 12
-+## 12. Rollout & Telemetry
-+- Feature flags: `tui_experimental`, `tui_sync_streaming`, `tui_workbench`
-+- Metrics: startup_ms, frame_render_p95_ms, db_busy_rate, panic_free_sessions, sync_drop_events
-+- Kill-switch: disable `tui` feature path at runtime if panic rate > 0.5% sessions over 24h
-+- Canary rollout: internal only -> opt-in beta -> default-on
-```
-
-10. **Strengthen Reliability Pack with Event-Fuzz + Soak Tests (P0)**
-Analysis: Current tests are good but still light on prolonged event pressure. Add deterministic fuzzed key/resize/paste streams and a long soak to catch rare deadlocks/leaks and state corruption.
-```diff
-@@ 9.2 Phase 5.5 — Reliability Test Pack
-+Event fuzz tests (key/resize/paste interleavings) :p55g, after p55e, 1d
-+30-minute soak test (no panic, bounded memory)    :p55h, after p55g, 1d
-
-@@ 9.3 Success criteria
-+12. Event-fuzz suite passes with zero invariant violations across 10k randomized traces.
-+13. 30-minute soak: no panic, no deadlock, memory growth < 5%.
-```
-
-If you want, I can produce a single consolidated unified diff of the full PRD text next (all edits merged, ready to apply as v3).

plans/tui-prd-v2-frankentui.feedback-4.md

@@ -1,157 +0,0 @@
-Below are my strongest revisions, focused on correctness, reliability, and long-term maintainability, while avoiding all items in your `## Rejected Recommendations`.
-
-1. **Fix the Cargo/toolchain architecture (current plan has a real dependency-cycle risk and shaky per-member toolchain behavior).**  
-Analysis: The current plan has `lore -> lore-tui (optional)` and `lore-tui -> lore`, which creates a package cycle when `tui` is enabled. Also, per-member `rust-toolchain.toml` in a workspace is easy to misapply in CI/dev workflows. The cleanest robust shape is: `lore-tui` is a separate binary crate (nightly), `lore` remains stable and delegates at runtime (`lore tui` shells out to `lore-tui`).  
-```diff
---- a/Gitlore_TUI_PRD_v2.md
-+++ b/Gitlore_TUI_PRD_v2.md
-@@ 3.2 Nightly Rust Strategy
--- The `lore` binary integrates TUI via `lore tui` subcommand. The `lore-tui` crate is a library dependency feature-gated in the root.
-+- `lore-tui` is a separate binary crate built on pinned nightly.
-+- `lore` (stable) does not compile-link `lore-tui`; `lore tui` delegates by spawning `lore-tui`.
-+- This removes Cargo dependency-cycle risk and keeps stable builds nightly-free.
-@@ 9.1 Dependency Changes
--[features]
--tui = ["dep:lore-tui"]
--[dependencies]
--lore-tui = { path = "crates/lore-tui", optional = true }
-+[dependencies]
-+# no compile-time dependency on lore-tui from lore
-+# runtime delegation keeps toolchains isolated
-@@ 10.19 CLI Integration
--Add Tui match arm that directly calls crate::tui::launch_tui(...)
-+Add Tui match arm that resolves and spawns `lore-tui` with passthrough args.
-+If missing, print actionable install/build command.
-```
-
-2. **Make `TaskSupervisor` the *actual* single async path (remove contradictory direct `Cmd::task` usage in state handlers).**  
-Analysis: You declare “direct `Cmd::task` is prohibited outside supervisor,” but later `handle_screen_msg` still launches tasks directly. That contradiction will reintroduce stale-result bugs and race conditions. Make state handlers pure (intent-only); all async launch/cancel/dedup goes through one supervised API.  
-```diff
---- a/Gitlore_TUI_PRD_v2.md
-+++ b/Gitlore_TUI_PRD_v2.md
-@@ 4.5.1 Task Supervisor
--The supervisor is the ONLY allowed path for background work.
-+The supervisor is the ONLY allowed path for background work, enforced by architecture:
-+`AppState` emits intents only; `LoreApp::update` launches tasks via `spawn_task(...)`.
-@@ 10.10 State Module — Complete
--pub fn handle_screen_msg(..., db: &Arc<Mutex<Connection>>) -> Cmd<Msg>
-+pub fn handle_screen_msg(...) -> ScreenIntent
-+// no DB access, no Cmd::task in state layer
-```
-
-3. **Enforce `EntityKey` everywhere (remove raw IID navigation paths).**  
-Analysis: Multi-project identity is one of your strongest ideas, but multiple snippets still navigate by bare IID (`document_id`, `EntityRef::Issue(i64)`). That can misroute across projects and create silent correctness bugs. Make all navigation-bearing results carry `EntityKey` end-to-end.  
-```diff
---- a/Gitlore_TUI_PRD_v2.md
-+++ b/Gitlore_TUI_PRD_v2.md
-@@ 4.3 Core Types
--pub enum EntityRef { Issue(i64), MergeRequest(i64) }
-+pub enum EntityRef { Issue(EntityKey), MergeRequest(EntityKey) }
-@@ 10.10 state/search.rs
--Some(Msg::NavigateTo(Screen::IssueDetail(r.document_id)))
-+Some(Msg::NavigateTo(Screen::IssueDetail(r.entity_key.clone())))
-@@ 10.11 action.rs
--pub fn fetch_issue_detail(conn: &Connection, iid: i64) -> Result<IssueDetail, LoreError>
-+pub fn fetch_issue_detail(conn: &Connection, key: &EntityKey) -> Result<IssueDetail, LoreError>
-```
-
-4. **Introduce a shared query boundary inside the existing crate (not a new crate) to decouple TUI from CLI presentation structs.**  
-Analysis: Reusing CLI command modules directly is fast initially, but it ties TUI to output-layer types and command concerns. A minimal internal `core::query::*` module gives a stable data contract used by both CLI and TUI without the overhead of a new crate split.  
-```diff
---- a/Gitlore_TUI_PRD_v2.md
-+++ b/Gitlore_TUI_PRD_v2.md
-@@ 10.2 Modified Files
--src/cli/commands/list.rs   # extract query_issues/query_mrs as pub
--src/cli/commands/show.rs   # extract query_issue_detail/query_mr_detail as pub
-+src/core/query/mod.rs
-+src/core/query/issues.rs
-+src/core/query/mrs.rs
-+src/core/query/detail.rs
-+src/core/query/search.rs
-+src/core/query/who.rs
-+src/cli/commands/* now call core::query::* + format output
-+TUI action.rs calls core::query::* directly
-```
-
-5. **Add terminal-safety sanitization for untrusted text (ANSI/OSC injection hardening).**  
-Analysis: Issue/MR bodies, notes, and logs are untrusted text in a terminal context. Without sanitization, terminal escape/control sequences can spoof UI or trigger unintended behavior. Add explicit sanitization and a strict URL policy before rendering/opening.  
-```diff
---- a/Gitlore_TUI_PRD_v2.md
-+++ b/Gitlore_TUI_PRD_v2.md
-@@ 3.1 Risk Matrix
-+| Terminal escape/control-sequence injection via issue/note text | High | Medium | Strip ANSI/OSC/control chars before render; escape markdown output; allowlist URL scheme+host |
-@@ 4.1 Module Structure
-+    safety.rs                      # sanitize_for_terminal(), safe_url_policy()
-@@ 10.5/10.8/10.14/10.16
-+All user-sourced text passes through `sanitize_for_terminal()` before widget rendering.
-+Disable markdown raw HTML and clickable links unless URL policy passes.
-```
-
-6. **Move resumable sync checkpoints into v1 (lightweight version).**  
-Analysis: You already identify interruption risk as real. Deferring resumability to post-v1 leaves a major reliability gap in exactly the heaviest workflow. A lightweight checkpoint table (resource cursor + updated-at watermark) gives large reliability gain with modest complexity.  
-```diff
---- a/Gitlore_TUI_PRD_v2.md
-+++ b/Gitlore_TUI_PRD_v2.md
-@@ 3.1 Risk Matrix
--- Resumable checkpoints planned for post-v1
-+Resumable checkpoints included in v1 (lightweight cursors per project/resource lane)
-@@ 9.3 Success Criteria
-+14. Interrupt-and-resume test: sync resumes from checkpoint and reaches completion without full restart.
-@@ 9.3.1 Required Indexes (GA Blocker)
-+CREATE TABLE IF NOT EXISTS sync_checkpoints (
-+  project_id INTEGER NOT NULL,
-+  lane TEXT NOT NULL,
-+  cursor TEXT,
-+  updated_at_ms INTEGER NOT NULL,
-+  PRIMARY KEY (project_id, lane)
-+);
-```
-
-7. **Strengthen performance gates with tiered fixtures and memory ceilings.**  
-Analysis: Current thresholds are good, but fixture sizes are too close to mid-scale only. Add S/M/L fixtures and memory budget checks so regressions appear before real-world datasets hit them. This gives much more confidence in long-term scalability.  
-```diff
---- a/Gitlore_TUI_PRD_v2.md
-+++ b/Gitlore_TUI_PRD_v2.md
-@@ 9.3 Phase 0 — Toolchain Gate
--7. p95 first-paint latency < 50ms ... (100k issues, 50k MRs)
--10. p95 search latency < 200ms ... (50k documents)
-+7. Tiered fixtures:
-+   S: 10k issues / 5k MRs / 50k notes
-+   M: 100k issues / 50k MRs / 500k notes
-+   L: 250k issues / 100k MRs / 1M notes
-+   Enforce p95 targets per tier and memory ceiling (<250MB RSS in M tier).
-+10. Search SLO validated in S and M tiers, lexical and hybrid modes.
-```
-
-8. **Add session restore (last screen + filters + selection), with explicit `--fresh` opt-out.**  
-Analysis: This is high-value daily UX with low complexity, and it makes the TUI feel materially more “compelling/useful” without feature bloat. It also reduces friction when recovering from crash/restart.  
-```diff
---- a/Gitlore_TUI_PRD_v2.md
-+++ b/Gitlore_TUI_PRD_v2.md
-@@ 1. Executive Summary
-+- **Session restore** — resume last screen, filters, and selection on startup.
-@@ 4.1 Module Structure
-+    session.rs                    # persisted UI session state
-@@ 8.1 Global
-+| `Ctrl+R` | Reset session state for current screen |
-@@ 10.19 CLI Integration
-+`lore tui --fresh` starts without restoring prior session state.
-@@ 11. Assumptions
--12. No TUI-specific configuration initially.
-+12. Minimal TUI state file is allowed for session restore only.
-```
-
-9. **Add parity tests between TUI data panels and `--robot` outputs.**  
-Analysis: You already have `ShowCliEquivalent`; parity tests make that claim trustworthy and prevent drift between interfaces. This is a strong reliability multiplier and helps future refactors.  
-```diff
---- a/Gitlore_TUI_PRD_v2.md
-+++ b/Gitlore_TUI_PRD_v2.md
-@@ 9.2 Phases / 9.3 Success Criteria
-+Phase 5.6 — CLI/TUI Parity Pack
-+  - Dashboard count parity vs `lore --robot count/status`
-+  - List/detail parity for issues/MRs on sampled entities
-+  - Search result identity parity (top-N ids) for lexical mode
-+Success criterion: parity suite passes on CI fixtures.
-```
-
-If you want, I can produce a single consolidated patch of the PRD text (one unified diff) so you can drop it directly into the next iteration.

plans/tui-prd-v2-frankentui.feedback-5.md

@@ -1,200 +0,0 @@
-1. **Fix the structural inconsistency between `src/tui` and `crates/lore-tui/src`**
-Analysis: The PRD currently defines two different code layouts for the same system. That will cause implementation drift, wrong imports, and duplicated modules. Locking to one canonical layout early prevents execution churn and makes every snippet/action item unambiguous.
-
-```diff
-@@ 4.1 Module Structure @@
--src/
--  tui/
-+crates/lore-tui/src/
-     mod.rs
-     app.rs
-     message.rs
-@@
--### 10.5 Dashboard View (FrankenTUI Native)
--// src/tui/view/dashboard.rs
-+### 10.5 Dashboard View (FrankenTUI Native)
-+// crates/lore-tui/src/view/dashboard.rs
-@@
--### 10.6 Sync View
--// src/tui/view/sync.rs
-+### 10.6 Sync View
-+// crates/lore-tui/src/view/sync.rs
-```
-
-2. **Add a small `ui_adapter` seam to contain FrankenTUI API churn**
-Analysis: You already identified high likelihood of upstream breakage. Pinning a commit helps, but if every screen imports raw `ftui_*` types directly, churn ripples through dozens of files. A thin adapter layer reduces upgrade cost without introducing the rejected “full portability abstraction”.
-
-```diff
-@@ 3.1 Risk Matrix @@
- | API breaking changes | High | High (v0.x) | Pin exact git commit; vendor source if needed |
-+| API breakage blast radius across app code | High | High | Constrain ftui usage behind `ui_adapter/*` wrappers |
-
-@@ 4.1 Module Structure @@
-+    ui_adapter/
-+      mod.rs                    # Re-export stable local UI primitives
-+      runtime.rs                # App launch/options wrappers
-+      widgets.rs                # Table/List/Modal wrapper constructors
-+      input.rs                  # Text input + focus helpers
-
-@@ 9.3 Phase 0 — Toolchain Gate @@
-+14. `ui_adapter` compile-check: no screen module imports `ftui_*` directly (lint-enforced)
-```
-
-3. **Correct search mode behavior and replace sleep-based debounce with cancelable scheduling**
-Analysis: Current plan hardcodes `"hybrid"` in `execute_search`, so mode switching is UI-only and incorrect. Also, spawning sleeping tasks per keypress is wasteful under fast typing. Make mode a first-class query parameter and debounce via one cancelable scheduled event per input domain.
-
-```diff
-@@ 4.4 maybe_debounced_query @@
--std::thread::sleep(std::time::Duration::from_millis(200));
--match crate::tui::action::execute_search(&conn, &query, &filters) {
-+// no thread sleep; schedule SearchRequestStarted after 200ms via debounce scheduler
-+match crate::tui::action::execute_search(&conn, &query, &filters, mode) {
-
-@@ 10.11 Action Module — Query Bridge @@
--pub fn execute_search(conn: &Connection, query: &str, filters: &SearchCliFilters) -> Result<SearchResponse, LoreError> {
--    let mode_str = "hybrid"; // default; TUI mode selector overrides
-+pub fn execute_search(
-+    conn: &Connection,
-+    query: &str,
-+    filters: &SearchCliFilters,
-+    mode: SearchMode,
-+) -> Result<SearchResponse, LoreError> {
-+    let mode_str = match mode {
-+        SearchMode::Hybrid => "hybrid",
-+        SearchMode::Lexical => "lexical",
-+        SearchMode::Semantic => "semantic",
-+    };
-
-@@ 9.3 Phase 0 — Toolchain Gate @@
-+15. Search mode parity: lexical/hybrid/semantic each return mode-consistent top-N IDs on fixture
-```
-
-4. **Guarantee consistent multi-query reads and add query interruption for responsiveness**
-Analysis: Detail screens combine multiple queries that can observe mixed states during sync writes. Wrap each detail fetch in a single read transaction for snapshot consistency. Add cancellation/interrupt checks for long-running queries so UI remains responsive under heavy datasets.
-
-```diff
-@@ 4.5 Async Action System @@
-+All detail fetches (`issue_detail`, `mr_detail`, timeline expansion) run inside one read transaction
-+to guarantee snapshot consistency across subqueries.
-
-@@ 10.11 Action Module — Query Bridge @@
-+pub fn with_read_snapshot<T>(
-+    conn: &Connection,
-+    f: impl FnOnce(&rusqlite::Transaction<'_>) -> Result<T, LoreError>,
-+) -> Result<T, LoreError> { ... }
-
-+// Long queries register interrupt checks tied to CancelToken
-+// to avoid >1s uninterruptible stalls during rapid navigation/filtering.
-```
-
-5. **Formalize sync event streaming contract to prevent “stuck” states**
-Analysis: Dropping events on backpressure is acceptable, but completion must never be dropped and event ordering must be explicit. Add a typed `SyncUiEvent` stream with guaranteed terminal sentinel and progress coalescing to reduce load while preserving correctness.
-
-```diff
-@@ 4.4 start_sync_task @@
--let (tx, rx) = std::sync::mpsc::sync_channel::<Msg>(1024);
-+let (tx, rx) = std::sync::mpsc::sync_channel::<SyncUiEvent>(2048);
-
--// drop this progress update rather than blocking the sync thread
-+// coalesce progress to max 30Hz per lane; never drop terminal events
-+// always emit SyncUiEvent::StreamClosed { outcome }
-
-@@ 5.9 Sync @@
--- Log viewer with streaming output
-+- Log viewer with streaming output and explicit stream-finalization state
-+- UI shows dropped/coalesced event counters for transparency
-```
-
-6. **Version and validate session restore payloads**
-Analysis: A raw JSON session file without schema/version checks is fragile across releases and DB switches. Add schema version, DB fingerprint, and safe fallback rules so session restore never blocks startup or applies stale state incorrectly.
-
-```diff
-@@ 11. Assumptions @@
--12. Minimal TUI state file allowed for session restore only ...
-+12. Versioned TUI state file allowed for session restore only:
-+    fields include `schema_version`, `app_version`, `db_fingerprint`, `saved_at`, `state`.
-
-@@ 10.1 New Files @@
- crates/lore-tui/src/session.rs         # Lightweight session state persistence
-+                                        # + versioning, validation, corruption quarantine
-
-@@ 4.1 Module Structure @@
-     session.rs                    # Lightweight session state persistence
-+                                  # corrupted file -> `.bad-<timestamp>` and fresh start
-```
-
-7. **Harden terminal safety beyond ANSI stripping**
-Analysis: ANSI stripping is necessary but not sufficient. Bidi controls and invisible Unicode controls can still spoof displayed content. URL checks should normalize host/port and disallow deceptive variants. This closes realistic terminal spoofing vectors.
-
-```diff
-@@ 3.1 Risk Matrix @@
- | Terminal escape/control-sequence injection via issue/note text | High | Medium | Strip ANSI/OSC/control chars via sanitize_for_terminal() ... |
-+| Bidi/invisible Unicode spoofing in rendered text | High | Medium | Strip bidi overrides + zero-width controls in untrusted text |
-
-@@ 10.4.1 Terminal Safety — Untrusted Text Sanitization @@
--Strip ANSI escape sequences, OSC commands, and control characters
-+Strip ANSI/OSC/control chars, bidi overrides (RLO/LRO/PDF/RLI/LRI/FSI/PDI),
-+and zero-width/invisible controls from untrusted text
-
--pub fn is_safe_url(url: &str, allowed_hosts: &[String]) -> bool {
-+pub fn is_safe_url(url: &str, allowed_origins: &[Origin]) -> bool {
-+    // normalize host (IDNA), enforce scheme+host+port match
-```
-
-8. **Use progressive hydration for detail screens**
-Analysis: Issue/MR detail first-paint can become slow when discussions are large. Split fetch into phases: metadata first, then discussions/file changes, then deep thread content on expand. This improves perceived performance and keeps navigation snappy on large repos.
-
-```diff
-@@ 5.3 Issue Detail @@
--Data source: `lore issues <iid>` + discussions + cross-references
-+Data source (progressive):
-+1) metadata/header (first paint)
-+2) discussions summary + cross-refs
-+3) full thread bodies loaded on demand when expanded
-
-@@ 5.5 MR Detail @@
--Unique features: File changes list, Diff discussions ...
-+Unique features (progressive hydration):
-+- file change summary in first paint
-+- diff discussion bodies loaded lazily per expanded thread
-
-@@ 9.3 Phase 0 — Toolchain Gate @@
-+16. Detail first-paint p95 < 75ms on M-tier fixtures (metadata-only phase)
-```
-
-9. **Make reliability tests reproducible with deterministic clocks/seeds**
-Analysis: Relative-time rendering and fuzz tests are currently tied to wall clock/randomness, which makes CI flakes hard to diagnose. Introduce a `Clock` abstraction and deterministic fuzz seeds with failure replay output.
-
-```diff
-@@ 10.9.1 Non-Snapshot Tests @@
-+/// All time-based rendering uses injected `Clock` in tests.
-+/// Fuzz failures print deterministic seed for replay.
-
-@@ 9.2 Phase 5.5 — Reliability Test Pack @@
--Event fuzz tests (key/resize/paste):p55g
-+Event fuzz tests (key/resize/paste, deterministic seed replay):p55g
-+Deterministic clock/render tests:p55i
-```
-
-10. **Add an “Actionable Insights” dashboard panel for stronger day-to-day utility**
-Analysis: Current dashboard is informative, but not prioritizing. Adding ranked insights (stale P1s, blocked MRs, discussion hotspots) turns it into a decision surface, not just a metrics screen. This makes the TUI materially more compelling for triage workflows.
-
-```diff
-@@ 1. Executive Summary @@
- - Dashboard — sync status, project health, counts at a glance
-+- Dashboard — sync status, project health, counts, and ranked actionable insights
-
-@@ 5.1 Dashboard (Home Screen) @@
--│  Recent Activity                  │
-+│  Recent Activity                  │
-+│  Actionable Insights              │
-+│  1) 7 opened P1 issues >14d       │
-+│  2) 3 MRs blocked by unresolved   │
-+│  3) auth/ has +42% note velocity  │
-
-@@ 6. User Flows @@
-+### 6.9 Flow: "Risk-first morning sweep"
-+Dashboard -> select insight -> jump to pre-filtered list/detail
-```
-
-These 10 changes stay clear of your `Rejected Recommendations` list and materially improve correctness, operability, and product value without adding speculative architecture.

plans/tui-prd-v2-frankentui.feedback-6.md

@@ -1,150 +0,0 @@
-Your plan is strong and unusually detailed. The biggest upgrades I’d make are around build isolation, async correctness, terminal correctness, and turning existing data into sharper triage workflows.
-
-## 1) Fix toolchain isolation so stable builds cannot accidentally pull nightly
-Rationale: a `rust-toolchain.toml` inside `crates/lore-tui` is not a complete guard when running workspace commands from repo root. You should structurally prevent stable workflows from touching nightly-only code.
-
-```diff
-@@ 3.2 Nightly Rust Strategy
--[workspace]
--members = [".", "crates/lore-tui"]
-+[workspace]
-+members = ["."]
-+exclude = ["crates/lore-tui"]
-
-+`crates/lore-tui` is built as an isolated workspace/package with explicit toolchain invocation:
-+  cargo +nightly-2026-02-08 check --manifest-path crates/lore-tui/Cargo.toml
-+Core repo remains:
-+  cargo +stable check --workspace
-```
-
-## 2) Add an explicit `lore` <-> `lore-tui` compatibility contract
-Rationale: runtime delegation is correct, but version drift between binaries will become the #1 support failure mode. Add a handshake before launch.
-
-```diff
-@@ 10.19 CLI Integration — Adding `lore tui`
-+Before spawning `lore-tui`, `lore` runs:
-+  lore-tui --print-contract-json
-+and validates:
-+  - minimum_core_version
-+  - supported_db_schema_range
-+  - contract_version
-+On mismatch, print actionable remediation:
-+  cargo install --path crates/lore-tui
-```
-
-## 3) Make TaskSupervisor truly authoritative (remove split async paths)
-Rationale: the document says supervisor is the only path, but examples still use direct `Cmd::task` and `search_request_id`. Close that contradiction now to avoid stale-data races.
-
-```diff
-@@ 4.4 App — Implementing the Model Trait
--    search_request_id: u64,
-+    task_supervisor: TaskSupervisor,
-
-@@ 4.5.1 Task Supervisor
--The `search_request_id` field in `LoreApp` is superseded...
-+`search_request_id` is removed. All async work uses TaskSupervisor generations.
-+No direct `Cmd::task` from screen handlers or ad-hoc helpers.
-```
-
-## 4) Resolve keybinding conflicts and implement real go-prefix timeout
-Rationale: `Ctrl+I` collides with `Tab` in terminals. Also your 500ms go-prefix timeout is described but not enforced in code.
-
-```diff
-@@ 8.1 Global (Available Everywhere)
--| `Ctrl+I` | Jump forward in jump list (entity hops) |
-+| `Alt+o` | Jump forward in jump list (entity hops) |
-
-@@ 8.2 Keybinding precedence
-+Go-prefix timeout is enforced by timestamped state + tick check.
-+Backspace global-back behavior is implemented (currently documented but not wired).
-```
-
-## 5) Add a shared display-width text utility (Unicode-safe truncation and alignment)
-Rationale: current `truncate()` implementations use byte/char length and will misalign CJK/emoji/full-width text in tables and trees.
-
-```diff
-@@ 10.1 New Files
-+crates/lore-tui/src/text_width.rs      # grapheme-safe truncation + display width helpers
-
-@@ 10.5 Dashboard View / 10.13 Issue List / 10.16 Who View
--fn truncate(s: &str, max: usize) -> String { ... }
-+use crate::text_width::truncate_display_width;
-+// all column fitting/truncation uses terminal display width, not bytes/chars
-```
-
-## 6) Upgrade sync streaming to a QoS event bus with sequence IDs
-Rationale: today progress/log events can be dropped under load with weak observability. Keep UI responsive while guaranteeing completion semantics and visible gap accounting.
-
-```diff
-@@ 4.4 start_sync_task()
--let (tx, rx) = std::sync::mpsc::sync_channel::<SyncUiEvent>(2048);
-+let (ctrl_tx, ctrl_rx) = std::sync::mpsc::sync_channel::<SyncCtrlEvent>(256);   // never-drop
-+let (data_tx, data_rx) = std::sync::mpsc::sync_channel::<SyncDataEvent>(4096);   // coalescible
-
-+Every streamed event carries seq_no.
-+UI detects gaps and renders: "Dropped N log/progress events due to backpressure."
-+Terminal events (started/completed/failed/cancelled) remain lossless.
-```
-
-## 7) Make list pagination truly keyset-driven in state, not just in prose
-Rationale: plan text promises windowed keyset paging, but state examples still keep a single list without cursor model. Encode pagination state explicitly.
-
-```diff
-@@ 10.10 state/issue_list.rs
--pub items: Vec<IssueListRow>,
-+pub window: Vec<IssueListRow>,
-+pub next_cursor: Option<IssueCursor>,
-+pub prev_cursor: Option<IssueCursor>,
-+pub prefetch: Option<Vec<IssueListRow>>,
-+pub window_size: usize, // default 200
-
-@@ 5.2 Issue List
--Pagination: Windowed keyset pagination...
-+Pagination: Keyset cursor model is first-class state with forward/back cursors and prefetch buffer.
-```
-
-## 8) Harden session restore with atomic persistence + integrity checksum
-Rationale: versioning/quarantine is good, but you still need crash-safe write semantics and tamper/corruption detection to avoid random boot failures.
-
-```diff
-@@ 10.1 New Files
--crates/lore-tui/src/session.rs         # Versioned session state persistence + validation + corruption quarantine
-+crates/lore-tui/src/session.rs         # + atomic write (tmp->fsync->rename), checksum, max-size guard
-
-@@ 11. Assumptions
-+Session writes are atomic and checksummed.
-+Invalid checksum or oversized file triggers quarantine and fresh boot.
-```
-
-## 9) Evolve Doctor from read-only text into actionable remediation
-Rationale: your CLI already returns machine-actionable `actions`. TUI should surface those as one-key fixes; this materially increases usefulness.
-
-```diff
-@@ 5.11 Doctor / Stats (Info Screens)
--Simple read-only views rendering the output...
-+Doctor is interactive:
-+  - shows health checks + severity
-+  - exposes suggested `actions` from robot-mode errors
-+  - Enter runs selected action command (with confirmation modal)
-+Stats remains read-only.
-```
-
-## 10) Add a Dependency Lens to Issue/MR detail (high-value triage feature)
-Rationale: you already have cross-refs + discussions + timeline. A compact dependency panel (blocked-by / blocks / unresolved threads) makes this data operational for prioritization.
-
-```diff
-@@ 5.3 Issue Detail
--│ ┌─ Cross-References ─────────────────────────────────────────┐ │
-+│ ┌─ Dependency Lens ──────────────────────────────────────────┐ │
-+│ │ Blocked by: #1198 (open, stale 9d)                        │ │
-+│ │ Blocks: !458 (opened, 2 unresolved threads)               │ │
-+│ │ Risk: High (P1 + stale blocker + open MR discussion)      │ │
-+│ └────────────────────────────────────────────────────────────┘ │
-
-@@ 9.2 Phases
-+Dependency Lens (issue/mr detail, computed risk score) :p3e, after p2e, 1d
-```
-
----
-
-If you want, I can next produce a consolidated **“v2.1 patch”** of the PRD with all these edits merged into one coherent updated document structure.

plans/tui-prd-v2-frankentui.feedback-7.md

@@ -1,264 +0,0 @@
-1. **Fix a critical contradiction in workspace/toolchain isolation**
-Rationale: Section `3.2` says `crates/lore-tui` is excluded from the root workspace, but Section `9.1` currently adds it as a member. That inconsistency will cause broken CI/tooling behavior and confusion about whether stable-only workflows remain safe.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 9.1 Dependency Changes
--# Root Cargo.toml changes
--[workspace]
--members = [".", "crates/lore-tui"]
-+# Root Cargo.toml changes
-+[workspace]
-+members = ["."]
-+exclude = ["crates/lore-tui"]
-@@
--# Add workspace member (no lore-tui dep, no tui feature)
-+# Keep lore-tui EXCLUDED from root workspace (nightly isolation boundary)
-@@ 9.3 Phase 0 — Toolchain Gate
--1. `cargo check --all-targets` passes on pinned nightly (TUI crate) and stable (core)
-+1. `cargo +stable check --workspace --all-targets` passes for root workspace
-+2. `cargo +nightly-2026-02-08 check --manifest-path crates/lore-tui/Cargo.toml --all-targets` passes
-```
-
-2. **Replace global loading spinner with per-screen stale-while-revalidate**
-Rationale: A single `is_loading` flag causes full-screen flicker and blocked context during quick refreshes. Per-screen load states keep existing data visible while background refresh runs, improving perceived performance and usability.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 10.10 State Module — Complete
--    pub is_loading: bool,
-+    pub load_state: ScreenLoadStateMap,
-@@
--    pub fn set_loading(&mut self, loading: bool) {
--        self.is_loading = loading;
--    }
-+    pub fn set_loading(&mut self, screen: ScreenId, state: LoadState) {
-+        self.load_state.insert(screen, state);
-+    }
-+
-+pub enum LoadState {
-+    Idle,
-+    LoadingInitial,
-+    Refreshing,      // stale data remains visible
-+    Error(String),
-+}
-@@ 4.4 App — Implementing the Model Trait
--        // Loading spinner overlay (while async data is fetching)
--        if self.state.is_loading {
--            crate::tui::view::common::render_loading(frame, body);
--        } else {
--            match self.navigation.current() { ... }
--        }
-+        // Always render screen; show lightweight refresh indicator when needed.
-+        match self.navigation.current() { ... }
-+        crate::tui::view::common::render_refresh_indicator_if_needed(
-+            self.navigation.current(), &self.state.load_state, frame, body
-+        );
-```
-
-3. **Make `TaskSupervisor` a real scheduler (not just token registry)**
-Rationale: Current design declares priority lanes but still dispatches directly with `Cmd::task`, and debounce uses `thread::sleep` per keystroke (wastes worker threads). A bounded scheduler with queued tasks and timer-driven debounce will reduce contention and tail latency.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 4.5.1 Task Supervisor (Dedup + Cancellation + Priority)
--pub struct TaskSupervisor {
--    active: HashMap<TaskKey, Arc<CancelToken>>,
--    generation: AtomicU64,
--}
-+pub struct TaskSupervisor {
-+    active: HashMap<TaskKey, Arc<CancelToken>>,
-+    generation: AtomicU64,
-+    queue: BinaryHeap<ScheduledTask>,
-+    inflight: HashMap<TaskPriority, usize>,
-+    limits: TaskLaneLimits, // e.g. Input=4, Navigation=2, Background=1
-+}
-@@
--// 200ms debounce via cancelable scheduled event (not thread::sleep).
--Cmd::task(move || {
--    std::thread::sleep(std::time::Duration::from_millis(200));
--    ...
--})
-+// Debounce via runtime timer message; no sleeping worker thread.
-+self.state.search.debounce_deadline = Some(now + 200ms);
-+Cmd::none()
-@@ 4.4 update()
-+Msg::Tick => {
-+    if self.state.search.debounce_expired(now) {
-+        return self.dispatch_supervised(TaskKey::Search, TaskPriority::Input, ...);
-+    }
-+    self.task_supervisor.dispatch_ready(now)
-+}
-```
-
-4. **Add a sync run ledger for exact “new since sync” navigation**
-Rationale: “Since last sync” based on timestamps is ambiguous with partial failures, retries, and clock drift. A lightweight `sync_runs` + `sync_deltas` ledger makes summary-mode drill-down exact and auditable without implementing full resumable checkpoints.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 5.9 Sync
--- `i` navigates to Issue List pre-filtered to "since last sync"
--- `m` navigates to MR List pre-filtered to "since last sync"
-+- `i` navigates to Issue List pre-filtered to `sync_run_id=<last_run>`
-+- `m` navigates to MR List pre-filtered to `sync_run_id=<last_run>`
-+- Filters are driven by persisted `sync_deltas` rows (exact entity keys changed in run)
-@@ 10.1 New Files
-+src/core/migrations/00xx_add_sync_run_ledger.sql
-@@ New migration (appendix)
-+CREATE TABLE sync_runs (
-+  id INTEGER PRIMARY KEY,
-+  started_at_ms INTEGER NOT NULL,
-+  completed_at_ms INTEGER,
-+  status TEXT NOT NULL
-+);
-+CREATE TABLE sync_deltas (
-+  sync_run_id INTEGER NOT NULL,
-+  entity_kind TEXT NOT NULL,
-+  project_id INTEGER NOT NULL,
-+  iid INTEGER NOT NULL,
-+  change_kind TEXT NOT NULL
-+);
-+CREATE INDEX idx_sync_deltas_run_kind ON sync_deltas(sync_run_id, entity_kind);
-@@ 11 Assumptions
--16. No new SQLite tables needed for v1
-+16. Two small v1 tables are added: `sync_runs` and `sync_deltas` for deterministic post-sync UX.
-```
-
-5. **Expand the GA index set to match actual filter surface**
-Rationale: Current required indexes only cover default sort paths; they do not match common filters like `author`, `assignee`, `reviewer`, `target_branch`, label-based filtering. This will likely miss p95 SLOs at M tier.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 9.3.1 Required Indexes (GA Blocker)
- CREATE INDEX IF NOT EXISTS idx_issues_list_default
-     ON issues(project_id, state, updated_at DESC, iid DESC);
-+CREATE INDEX IF NOT EXISTS idx_issues_author_updated
-+    ON issues(project_id, state, author_username, updated_at DESC, iid DESC);
-+CREATE INDEX IF NOT EXISTS idx_issues_assignee_updated
-+    ON issues(project_id, state, assignee_username, updated_at DESC, iid DESC);
-@@
- CREATE INDEX IF NOT EXISTS idx_mrs_list_default
-     ON merge_requests(project_id, state, updated_at DESC, iid DESC);
-+CREATE INDEX IF NOT EXISTS idx_mrs_reviewer_updated
-+    ON merge_requests(project_id, state, reviewer_username, updated_at DESC, iid DESC);
-+CREATE INDEX IF NOT EXISTS idx_mrs_target_updated
-+    ON merge_requests(project_id, state, target_branch, updated_at DESC, iid DESC);
-+CREATE INDEX IF NOT EXISTS idx_mrs_source_updated
-+    ON merge_requests(project_id, state, source_branch, updated_at DESC, iid DESC);
-@@
-+-- If labels are normalized through join table:
-+CREATE INDEX IF NOT EXISTS idx_issue_labels_label_issue ON issue_labels(label, issue_id);
-+CREATE INDEX IF NOT EXISTS idx_mr_labels_label_mr ON mr_labels(label, mr_id);
-@@ CI enforcement
--asserts that none show `SCAN TABLE` for the primary entity tables
-+asserts that none show full scans for primary tables under default filters AND top 8 user-facing filter combinations
-```
-
-6. **Add DB schema compatibility preflight (separate from binary compat)**
-Rationale: Binary compat (`--compat-version`) does not protect against schema mismatches. Add explicit schema version checks before booting the TUI to avoid runtime SQL errors deep in navigation paths.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 3.2 Nightly Rust Strategy
--- **Compatibility contract:** Before spawning `lore-tui`, the `lore tui` subcommand runs `lore-tui --compat-version` ...
-+- **Compatibility contract:** Before spawning `lore-tui`, `lore tui` validates:
-+  1) binary compat version (`lore-tui --compat-version`)
-+  2) DB schema range (`lore-tui --check-schema <db-path>`)
-+If schema is out-of-range, print remediation: `lore migrate`.
-@@ 9.3 Phase 0 — Toolchain Gate
-+17. Schema preflight test: incompatible DB schema yields actionable error and non-zero exit before entering TUI loop.
-```
-
-7. **Refine terminal sanitization to preserve legitimate Unicode while blocking control attacks**
-Rationale: Current sanitizer strips zero-width joiners and similar characters, which breaks emoji/grapheme rendering and undermines your own `text_width` goals. Keep benign Unicode, remove only dangerous controls/bidi spoof vectors, and sanitize markdown link targets too.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 10.4.1 Terminal Safety — Untrusted Text Sanitization
--- Strip bidi overrides ... and zero-width/invisible controls ...
-+- Strip ANSI/OSC/control chars and bidi spoof controls.
-+- Preserve legitimate grapheme-joining characters (ZWJ/ZWNJ/combining marks) for correct Unicode rendering.
-+- Sanitize markdown link targets with strict URL allowlist before rendering clickable links.
-@@ safety.rs
--            // Strip zero-width and invisible controls
--            '\u{200B}' | '\u{200C}' | '\u{200D}' | '\u{FEFF}' | '\u{00AD}' => {}
-+            // Preserve grapheme/emoji join behavior; remove only harmful controls.
-+            // (ZWJ/ZWNJ/combining marks are retained)
-@@ Enforcement rule
- - Search result snippets
- - Author names and labels
-+- Markdown link destinations (scheme + origin validation before render/open)
-```
-
-8. **Add key normalization layer for terminal portability**
-Rationale: Collision notes are good, but you still need a canonicalization layer because terminals emit different sequences for Alt/Meta/Backspace/Enter variants. This reduces “works in iTerm, broken in tmux/SSH” bugs.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 8.2 List Screens
- **Terminal keybinding safety notes:**
-@@
- - `Ctrl+M` is NOT used — it collides with `Enter` ...
-+
-+**Key normalization layer (new):**
-+- Introduce `KeyNormalizer` before `interpret_key()`:
-+  - normalize Backspace variants (`^H`, `DEL`)
-+  - normalize Alt/Meta prefixes
-+  - normalize Shift+Tab vs Tab where terminal supports it
-+  - normalize kitty/CSI-u enhanced key protocols when present
-@@ 9.2 Phases
-+    Key normalization integration tests   :p5d, after p5c, 1d
-+    Terminal profile replay tests         :p5e, after p5d, 1d
-```
-
-9. **Add deterministic event-trace capture for crash reproduction**
-Rationale: Panic logs without recent event context are often insufficient for TUI race bugs. Persist last-N normalized events + active screen + task state snapshot on panic for one-command repro.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 3.1 Risk Matrix
- | Runtime panic leaves user blocked | High | Medium | Panic hook writes crash report, restores terminal, offers fallback CLI command |
-+| Hard-to-reproduce input race bugs | Medium | Medium | Persist last 2k normalized events + state hash on panic for deterministic replay |
-@@ 10.3 Entry Point / panic hook
--        // 2. Write crash dump
-+        // 2. Write crash dump + event trace snapshot
-+        // Includes: last 2000 normalized events, current screen, in-flight task keys/generations
-@@ 10.9.1 Non-Snapshot Tests
-+/// Replay captured event trace from panic artifact and assert no panic.
-+#[test]
-+fn replay_trace_artifact_is_stable() { ... }
-```
-
-10. **Do a plan-wide consistency pass on pseudocode contracts**
-Rationale: There are internal mismatches that will create implementation churn (`search_request_id` still referenced after replacement, `items` vs `window`, keybinding mismatch `Ctrl+I` vs `Alt+o`). Tightening these now saves real engineering time later.
-
-```diff
---- a/PRD.md
-+++ b/PRD.md
-@@ 4.4 LoreApp::new
--            search_request_id: 0,
-+            // dedup generation handled by TaskSupervisor
-@@ 8.1 Global
--| `Ctrl+O` | Jump backward in jump list (entity hops) |
--| `Alt+o` | Jump forward in jump list (entity hops) |
-+| `Ctrl+O` | Jump backward in jump list (entity hops) |
-+| `Alt+o`  | Jump forward in jump list (entity hops) |
-@@ 10.10 IssueListState
--    pub fn selected_item(&self) -> Option<&IssueListRow> {
--        self.items.get(self.selected_index)
--    }
-+    pub fn selected_item(&self) -> Option<&IssueListRow> {
-+        self.window.get(self.selected_index)
-+    }
-```
-
-If you want, I can now produce a single consolidated unified diff patch of the full PRD with these revisions merged end-to-end.

plans/tui-prd-v2-frankentui.feedback-8.md

@@ -1,211 +0,0 @@
-Below are the strongest revisions I’d make. I intentionally avoided anything in your `## Rejected Recommendations`.
-
-1. **Unify commands/keybindings/help/palette into one registry**
-Rationale: your plan currently duplicates action definitions across `execute_palette_action`, `ShowCliEquivalent`, help overlay text, and status hints. That will drift quickly and create correctness bugs. A single `CommandRegistry` makes behavior consistent and testable.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 4.1 Module Structure
-+    commands.rs                   # Single source of truth for actions, keybindings, CLI equivalents
-
-@@ 4.4 App — Implementing the Model Trait
--    fn execute_palette_action(&self, action_id: &str) -> Cmd<Msg> { ... big match ... }
-+    fn execute_palette_action(&self, action_id: &str) -> Cmd<Msg> {
-+        if let Some(spec) = self.commands.get(action_id) {
-+            return self.update(spec.to_msg(self.navigation.current()));
-+        }
-+        Cmd::none()
-+    }
-
-@@ 8. Keybinding Reference
-+All keybinding/help/status/palette definitions are generated from `commands.rs`.
-+No hardcoded duplicate maps in view/state modules.
-```
-
-2. **Replace ad-hoc key flags with explicit input state machine**
-Rationale: `pending_go` + `go_prefix_instant` is fragile and already inconsistent with documented behavior. A typed `InputMode` removes edge-case bugs and makes prefix timeout deterministic.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 4.4 LoreApp struct
--    pending_go: bool,
--    go_prefix_instant: Option<std::time::Instant>,
-+    input_mode: InputMode, // Normal | Text | Palette | GoPrefix { started_at }
-
-@@ 8.2 List Screens
--| `g` `g` | Jump to top |
-+| `g` `g` | Jump to top (current list screen) |
-
-@@ 4.4 interpret_key
-- KeyCode::Char('g') => Msg::IssueListScrollToTop
-+ KeyCode::Char('g') => Msg::ScrollToTopCurrentScreen
-```
-
-3. **Fix TaskSupervisor contract and message schema drift**
-Rationale: the plan mixes `request_id` and `generation`, and `TaskKey::Search { generation }` defeats dedup by making every key unique. This can silently reintroduce stale-result races.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 4.3 Core Types (Msg)
--    SearchRequestStarted { request_id: u64, query: String },
--    SearchExecuted { request_id: u64, results: SearchResults },
-+    SearchRequestStarted { generation: u64, query: String },
-+    SearchExecuted { generation: u64, results: SearchResults },
-
-@@ 4.5.1 Task Supervisor
--    Search { generation: u64 },
-+    Search,
-+    struct TaskStamp { key: TaskKey, generation: u64 }
-
-@@ 10.9.1 Non-Snapshot Tests
--    Msg::SearchExecuted { request_id: 3, ... }
-+    Msg::SearchExecuted { generation: 3, ... }
-```
-
-4. **Add a `Clock` boundary everywhere time is computed**
-Rationale: you call `SystemTime::now()` in many query/render paths, causing inconsistent relative-time labels inside one frame and flaky tests. Injected clock gives deterministic rendering and lower per-frame overhead.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 4.1 Module Structure
-+    clock.rs                      # Clock trait: SystemClock/FakeClock
-
-@@ 4.4 LoreApp struct
-+    clock: Arc<dyn Clock>,
-
-@@ 10.11 action.rs
-- let now_ms = std::time::SystemTime::now()...
-+ let now_ms = clock.now_ms();
-
-@@ 9.3 Phase 0 success criteria
-+19. Relative-time rendering deterministic under FakeClock across snapshot runs.
-```
-
-5. **Upgrade text truncation to grapheme-safe width handling**
-Rationale: `unicode-width` alone is not enough for safe truncation; it can split grapheme clusters (emoji ZWJ sequences, skin tones, flags). You need width + grapheme segmentation together.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 10.1 New Files
--crates/lore-tui/src/text_width.rs      # ... using unicode-width crate
-+crates/lore-tui/src/text_width.rs      # Grapheme-safe width/truncation using unicode-width + unicode-segmentation
-
-@@ 10.1 New Files
-+Cargo.toml (lore-tui): unicode-segmentation = "1"
-
-@@ 9.3 Phase 0 success criteria
-+20. Unicode rendering tests pass for CJK, emoji ZWJ, combining marks, RTL text.
-```
-
-6. **Redact sensitive values in logs and crash dumps**
-Rationale: current crash/log strategy risks storing tokens/credentials in plain text. This is a serious operational/security gap for local tooling too.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 4.1 Module Structure
-     safety.rs                     # sanitize_for_terminal(), safe_url_policy()
-+    redact.rs                     # redact_sensitive() for logs/crash reports
-
-@@ 10.3 install_panic_hook_for_tui
-- let _ = std::fs::write(&crash_path, format!("{panic_info:#?}"));
-+ let report = redact_sensitive(format!("{panic_info:#?}"));
-+ let _ = std::fs::write(&crash_path, report);
-
-@@ 9.3 Phase 0 success criteria
-+21. Redaction tests confirm tokens/Authorization headers never appear in persisted crash/log artifacts.
-```
-
-7. **Add search capability detection and mode fallback UX**
-Rationale: semantic/hybrid mode should not silently degrade when embeddings are absent/stale. Explicit capability state increases trust and avoids “why are results weird?” confusion.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 5.6 Search
-+Capability-aware modes:
-+- If embeddings unavailable/stale, semantic mode is disabled with inline reason.
-+- Hybrid mode auto-falls back to lexical and shows badge: "semantic unavailable".
-
-@@ 4.3 Core Types
-+    SearchCapabilitiesLoaded(SearchCapabilities)
-
-@@ 9.3 Phase 0 success criteria
-+22. Mode availability checks validated: lexical/hybrid/semantic correctly enabled/disabled by fixture capabilities.
-```
-
-8. **Define sync cancel latency SLO and enforce fine-grained checks**
-Rationale: “check cancel between phases” is too coarse on big projects. Users need fast cancel acknowledgment and bounded stop time.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 5.9 Sync
--CANCELLATION: checked between sync phases
-+CANCELLATION: checked at page boundaries, batch upsert boundaries, and before each network request.
-+UX target: cancel acknowledged <250ms, sync stop p95 <2s after Esc.
-
-@@ 9.3 Phase 0 success criteria
-+23. Cancel latency test passes: p95 stop time <2s under M-tier fixtures.
-```
-
-9. **Add a “Hotspots” screen for risk/churn triage**
-Rationale: this is high-value and uses existing data (events, unresolved discussions, stale items). It makes the TUI more compelling without needing new sync tables or rejected features.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 1. Executive Summary
-+- **Hotspots** — file/path risk ranking by churn × unresolved discussion pressure × staleness
-
-@@ 5. Screen Taxonomy
-+### 5.12 Hotspots
-+Shows top risky paths with drill-down to related issues/MRs/timeline.
-
-@@ 8.1 Global
-+| `gx` | Go to Hotspots |
-
-@@ 10.1 New Files
-+crates/lore-tui/src/state/hotspots.rs
-+crates/lore-tui/src/view/hotspots.rs
-```
-
-10. **Add degraded startup mode when compat/schema checks fail**
-Rationale: hard-exit on mismatch blocks users. A degraded mode that shells to `lore --robot` for read-only summary/doctor keeps the product usable and gives guided recovery.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 3.2 Nightly Rust Strategy
-- On mismatch: actionable error and exit
-+ On mismatch: actionable error with `--degraded` option.
-+ `--degraded` launches limited TUI (Dashboard/Doctor/Stats via `lore --robot` subprocess calls).
-
-@@ 10.3 TuiCli
-+    /// Allow limited mode when schema/compat checks fail
-+    #[arg(long)]
-+    degraded: bool,
-```
-
-11. **Harden query-plan CI checks (don’t rely on `SCAN TABLE` string matching)**
-Rationale: SQLite planner text varies by version. Parse opcode structure and assert index usage semantically; otherwise CI will be flaky or miss regressions.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 9.3.1 Required Indexes (CI enforcement)
-- asserts that none show `SCAN TABLE`
-+ parses EXPLAIN QUERY PLAN rows and asserts:
-+ - top-level loop uses expected index families
-+ - no full scan on primary entity tables under default and top filter combos
-+ - join order remains bounded (no accidental cartesian expansions)
-```
-
-12. **Enforce single-instance lock for session/state safety**
-Rationale: assumption says no concurrent TUI sessions, but accidental double-launch will still happen. Locking prevents state corruption and confusing interleaved sync actions.
-
-```diff
-diff --git a/PRD.md b/PRD.md
-@@ 10.1 New Files
-+crates/lore-tui/src/instance_lock.rs   # lock file with stale-lock recovery
-
-@@ 11. Assumptions
--21. No concurrent TUI sessions.
-+21. Concurrent sessions unsupported and actively prevented by instance lock (with clear error message).
-```
-
-If you want, I can turn this into a consolidated patched PRD (single unified diff) next.

plans/tui-prd-v2-frankentui.feedback-9.md

@@ -1,198 +0,0 @@
-I reviewed the full PRD end-to-end and avoided all items already listed in `## Rejected Recommendations`.  
-These are the highest-impact revisions I’d make.
-
-1. **Fix keybinding/state-machine correctness gaps (critical)**
-The plan currently has an internal conflict: the doc says jump-forward is `Alt+o`, but code sample uses `Ctrl+i` (which collides with `Tab` in many terminals). Also, `g`-prefix timeout depends on `Tick`, but `Tick` isn’t guaranteed when idle, so prefix mode can get “stuck.” This is a correctness bug, not polish.
-
-```diff
-@@ 8.1 Global (Available Everywhere)
--| `Ctrl+O` | Jump backward in jump list (entity hops) |
--| `Alt+o` | Jump forward in jump list (entity hops) |
-+| `Ctrl+O` | Jump backward in jump list (entity hops) |
-+| `Alt+o` | Jump forward in jump list (entity hops) |
-+| `Backspace` | Go back (when no text input is focused) |
-
-@@ 4.4 LoreApp::interpret_key
-- (KeyCode::Char('i'), m) if m.contains(Modifiers::CTRL) => {
--     return Some(Msg::JumpForward);
-- }
-+ (KeyCode::Char('o'), m) if m.contains(Modifiers::ALT) => {
-+     return Some(Msg::JumpForward);
-+ }
-+ (KeyCode::Backspace, Modifiers::NONE) => {
-+     return Some(Msg::GoBack);
-+ }
-
-@@ 4.4 Model::subscriptions
-+ // Go-prefix timeout enforcement must tick even when nothing is loading.
-+ if matches!(self.input_mode, InputMode::GoPrefix { .. }) {
-+     subs.push(Box::new(
-+         Every::with_id(2, Duration::from_millis(50), || Msg::Tick)
-+     ));
-+ }
-```
-
-2. **Make `TaskSupervisor` API internally consistent and enforceable**
-The plan uses `submit()`/`is_current()` in one place and `register()`/`next_generation()` in another. That inconsistency will cause implementation drift and stale-result bugs. Use one coherent API with a returned handle containing `{key, generation, cancel_token}`.
-
-```diff
-@@ 4.5.1 Task Supervisor (Dedup + Cancellation + Priority)
--pub struct TaskSupervisor {
--    active: HashMap<TaskKey, Arc<CancelToken>>,
--    generation: AtomicU64,
--}
-+pub struct TaskSupervisor {
-+    active: HashMap<TaskKey, TaskHandle>,
-+}
-+
-+pub struct TaskHandle {
-+    pub key: TaskKey,
-+    pub generation: u64,
-+    pub cancel: Arc<CancelToken>,
-+}
-
-- pub fn register(&mut self, key: TaskKey) -> Arc<CancelToken>
-- pub fn next_generation(&self) -> u64
-+ pub fn submit(&mut self, key: TaskKey) -> TaskHandle
-+ pub fn is_current(&self, key: &TaskKey, generation: u64) -> bool
-+ pub fn complete(&mut self, key: &TaskKey, generation: u64)
-```
-
-3. **Replace thread-sleep debounce with runtime timer messages**
-`std::thread::sleep(200ms)` inside task closures wastes pool threads under fast typing and reduces responsiveness under contention. Use timer-driven debounce messages and only fire the latest generation. This improves latency stability on large datasets.
-
-```diff
-@@ 4.3 Core Types (Msg enum)
-+ SearchDebounceArmed { generation: u64, query: String },
-+ SearchDebounceFired { generation: u64 },
-
-@@ 4.4 maybe_debounced_query
-- Cmd::task(move || {
--     std::thread::sleep(std::time::Duration::from_millis(200));
--     ...
-- })
-+ // Arm debounce only; runtime timer emits SearchDebounceFired.
-+ Cmd::msg(Msg::SearchDebounceArmed { generation, query })
-
-@@ 4.4 subscriptions()
-+ if self.state.search.debounce_pending() {
-+     subs.push(Box::new(
-+         Every::with_id(3, Duration::from_millis(200), || Msg::SearchDebounceFired { generation: ... })
-+     ));
-+ }
-```
-
-4. **Harden `DbManager` API to avoid lock-poison panics and accidental long-held guards**
-Returning raw `MutexGuard<Connection>` invites accidental lock scope expansion and `expect("lock poisoned")` panics. Move to closure-based access (`with_reader`, `with_writer`) returning `Result`, and use cached statements. This reduces deadlock risk and tail latency.
-
-```diff
-@@ 4.4 DbManager
-- pub fn reader(&self) -> MutexGuard<'_, Connection> { ...expect("reader lock poisoned") }
-- pub fn writer(&self) -> MutexGuard<'_, Connection> { ...expect("writer lock poisoned") }
-+ pub fn with_reader<T>(&self, f: impl FnOnce(&Connection) -> Result<T, LoreError>) -> Result<T, LoreError>
-+ pub fn with_writer<T>(&self, f: impl FnOnce(&Connection) -> Result<T, LoreError>) -> Result<T, LoreError>
-
-@@ 10.11 action.rs
-- let conn = db.reader();
-- match fetch_issues(&conn, &filter) { ... }
-+ match db.with_reader(|conn| fetch_issues(conn, &filter)) { ... }
-
-+ // Query hot paths use prepare_cached() to reduce parse overhead.
-```
-
-5. **Add read-path entity cache (LRU) for repeated drill-in/out workflows**
-Your core daily flow is Enter/Esc bouncing between list/detail. Without caching, identical detail payloads are re-queried repeatedly. A bounded LRU by `EntityKey` with invalidation on sync completion gives near-instant reopen behavior and reduces DB pressure.
-
-```diff
-@@ 4.1 Module Structure
-+    entity_cache.rs               # Bounded LRU cache for detail payloads
-
-@@ app.rs LoreApp fields
-+    entity_cache: EntityCache,
-
-@@ load_screen(Screen::IssueDetail / MrDetail)
-+    if let Some(cached) = self.entity_cache.get_issue(&key) {
-+        return Cmd::msg(Msg::IssueDetailLoaded { key, detail: cached.clone() });
-+    }
-
-@@ Msg::IssueDetailLoaded / Msg::MrDetailLoaded handlers
-+    self.entity_cache.put_issue(key.clone(), detail.clone());
-
-@@ Msg::SyncCompleted
-+    self.entity_cache.invalidate_all();
-```
-
-6. **Tighten sync-stream observability and drop semantics without adding heavy architecture**
-You already handle backpressure, but operators need visibility when it happens. Track dropped-progress count and max queue depth in state and surface it in running/summary views. This keeps the current simple design while making reliability measurable.
-
-```diff
-@@ 4.3 Msg
-+ SyncStreamStats { dropped_progress: u64, max_queue_depth: usize },
-
-@@ 5.9 Sync (Running mode footer)
--| Esc cancel  f full sync  e embed after  d dry-run  l log level|
-+| Esc cancel  f full sync  e embed after  d dry-run  l log level  stats:drop=12 qmax=1847 |
-
-@@ 9.3 Success criteria
-+24. Sync stream stats are emitted and rendered; terminal events (completed/failed/cancelled) delivery is 100% under induced backpressure.
-```
-
-7. **Make crash reporting match the promised diagnostic value**
-The PRD promises event replay context, but sample hook writes only panic text. Add explicit crash context capture (`last events`, `current screen`, `task handles`, `build id`, `db fingerprint`) and retention policy. This materially improves post-mortem debugging.
-
-```diff
-@@ 4.1 Module Structure
-+    crash_context.rs              # ring buffer of normalized events + task/screen snapshot
-
-@@ 10.3 install_panic_hook_for_tui()
-- let report = crate::redact::redact_sensitive(&format!("{panic_info:#?}"));
-+ let ctx = crate::crash_context::snapshot();
-+ let report = crate::redact::redact_sensitive(&format!("{panic_info:#?}\n{ctx:#?}"));
-
-+ // Retention: keep latest 20 crash files, delete oldest metadata entries only.
-```
-
-8. **Add Search Facets panel for faster triage (high-value feature, low risk)**
-Search is central, but right now filtering requires manual field edits. Add facet counts (`issues`, `MRs`, `discussions`, top labels/projects/authors) with one-key apply. This makes search more compelling and actionable without introducing schema changes.
-
-```diff
-@@ 5.6 Search
--- Layout: Split pane — results list (left) + preview (right)
-+- Layout: Three-pane on wide terminals — results (left) + preview (center) + facets (right)
-
-+**Facets panel:**
-+- Entity type counts (issue/MR/discussion)
-+- Top labels/projects/authors for current query
-+- `1/2/3` quick-apply type facet; `l` cycles top label facet
-
-@@ 8.2 List/Search keybindings
-+| `1` `2` `3` | Apply facet: Issue / MR / Discussion |
-+| `l` | Apply next top-label facet |
-```
-
-9. **Strengthen text sanitization for terminal edge cases**
-Current sanitizer is strong, but still misses some control-space edge cases (C1 controls, directional marks beyond the listed bidi set). Add those and test them. This closes spoofing/render confusion gaps with minimal complexity.
-
-```diff
-@@ 10.4.1 sanitize_for_terminal()
-+ // Strip C1 control block (U+0080..U+009F) and additional directional marks
-+ c if ('\u{0080}'..='\u{009F}').contains(&c) => {}
-+ '\u{200E}' | '\u{200F}' | '\u{061C}' => {} // LRM, RLM, ALM
-
-@@ tests
-+ #[test] fn strips_c1_controls() { ... }
-+ #[test] fn strips_lrm_rlm_alm() { ... }
-```
-
-10. **Add an explicit vertical-slice gate before broad screen expansion**
-The plan is comprehensive, but risk is still front-loaded on framework + runtime behavior. Insert a strict vertical slice gate (`Dashboard + IssueList + IssueDetail + Sync running`) with perf and stability thresholds before Phase 3 features. This reduces rework if foundational assumptions break.
-
-```diff
-@@ 9.2 Phases
-+section Phase 2.5 — Vertical Slice Gate
-+Dashboard + IssueList + IssueDetail + Sync (running) integrated :p25a, after p2c, 3d
-+Gate: p95 nav latency < 75ms on M tier; zero stuck-input-state bugs; cancel p95 < 2s :p25b, after p25a, 1d
-+Only then proceed to Search/Timeline/Who/Palette expansion.
-```
-
-If you want, I can produce a full consolidated `diff` block against the entire PRD text (single patch), but the above is the set I’d prioritize first.

plans/work-item-status-graphql.md

@@ -107,12 +107,12 @@ Each criterion is independently testable. Implementation is complete when ALL pa
 
 ### AC-7: Show Issue Display (E2E)
 
-**Human (`lore show issue 123`):**
+**Human (`lore issues 123`):**
 - [ ] New line after "State": `Status:   In progress` (colored by `status_color` hex → nearest terminal color)
 - [ ] Status line only shown when `status_name IS NOT NULL`
 - [ ] Category shown in parens when available, lowercased: `Status:   In progress (in_progress)`
 
-**Robot (`lore --robot show issue 123`):**
+**Robot (`lore --robot issues 123`):**
 - [ ] JSON includes `status_name`, `status_category`, `status_color`, `status_icon_name`, `status_synced_at` fields
 - [ ] Fields are `null` (not absent) when status not available
 - [ ] `status_synced_at` is integer (ms epoch UTC) or `null` — enables freshness checks by consumers

rust-toolchain.toml

@@ -0,0 +1,2 @@
+[toolchain]
+channel = "nightly-2026-03-01"

specs/SPEC_discussion_analysis.md

@@ -0,0 +1,729 @@
+# Spec: Discussion Analysis — LLM-Powered Discourse Enrichment
+
+**Parent:** SPEC_explain.md (replaces key_decisions heuristic, line 270)
+**Created:** 2026-03-11
+**Status:** DRAFT — iterating with user
+
+## Spec Status
+| Section | Status | Notes |
+|---------|--------|-------|
+| Objective | draft | Core vision defined, success metrics TBD |
+| Tech Stack | draft | Bedrock + Anthropic API dual-backend |
+| Architecture | draft | Pre-computed enrichment pipeline |
+| Schema | draft | `discussion_analysis` table with staleness detection |
+| CLI Command | draft | `lore enrich discussions` |
+| LLM Provider | draft | Configurable backend abstraction |
+| Explain Integration | draft | Replaces heuristic with DB lookup |
+| Prompt Design | draft | Thread-level discourse classification |
+| Testing Strategy | draft | Includes mock LLM for deterministic tests |
+| Boundaries | draft | |
+| Tasks | not started | Blocked on spec approval |
+
+**Definition of Complete:** All sections `complete`, Open Questions empty,
+every user journey has tasks, every task has TDD workflow and acceptance criteria.
+
+---
+
+## Open Questions (Resolve Before Implementation)
+
+1. **Bedrock model ID**: Which exact Bedrock model will be used? (Assuming `anthropic.claude-3-haiku-*` — need the org-approved ARN or model ID.)
+2. **Auth mechanism**: Does the Bedrock setup use IAM role assumption, SSO profile, or explicit access keys? This affects the SDK configuration.
+3. **Rate limiting**: What's the org's Bedrock rate limit? This determines batch concurrency.
+4. **Cost ceiling**: Should there be a per-run token budget or discussion count cap? (e.g., `--max-threads 200`)
+5. **Confidence thresholds**: Below what confidence should we discard an analysis vs. store it with low confidence?
+6. **explain integration field name**: Replace `key_decisions` entirely, or add a new `discourse_analysis` section alongside it? (Recommendation: replace `key_decisions` — the heuristic is acknowledged as inadequate.)
+
+---
+
+## Objective
+
+**Goal:** Pre-compute structured discourse analysis for discussion threads using an LLM (Claude Haiku via Bedrock or Anthropic API), storing results locally so that `lore explain` and future commands can surface meaningful decisions, answered questions, and consensus without runtime LLM calls.
+
+**Problem:** The current `key_decisions` heuristic in `explain` correlates state-change events with notes by the same actor within 60 minutes. This produces mostly empty results because real decisions happen in discussion threads, not at the moment of state changes. The heuristic cannot understand conversational semantics — whether a comment confirms a proposal, answers a question, or represents consensus.
+
+**What this enables:**
+- `lore explain issues 42` shows *actual* decisions extracted from discussion threads, not event-note temporal coincidences
+- Reusable across commands — any command can query `discussion_analysis` for pre-computed insights
+- Fully offline at query time — LLM enrichment is a batch pre-computation step
+- Incremental — only re-analyzes threads whose notes have changed (staleness via `notes_hash`)
+
+**Success metrics:**
+- `lore enrich discussions` processes 100 threads in <60s with Haiku
+- `lore explain` key_decisions section populated from enrichment data in <500ms (no LLM calls)
+- Staleness detection: re-running enrichment skips unchanged threads
+- Zero impact on users without LLM configuration — graceful degradation to empty key_decisions
+
+---
+
+## Tech Stack & Constraints
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Language | Rust | nightly-2026-03-01 |
+| LLM (primary) | Claude Haiku via AWS Bedrock | Org-approved, security-compliant |
+| LLM (fallback) | Claude Haiku via Anthropic API | For personal/non-org use |
+| HTTP | asupersync `HttpClient` | Existing wrapper in `src/http.rs` |
+| Database | SQLite via rusqlite | New migration for `discussion_analysis` table |
+| Config | `~/.config/lore/config.json` | New `enrichment` section |
+
+**Constraints:**
+- Bedrock is the primary backend (org security requirement for Taylor's work context)
+- Anthropic API is an alternative for non-org users
+- `lore explain` must NEVER make runtime LLM calls — all enrichment is pre-computed
+- `lore explain` performance budget unchanged: <500ms
+- Enrichment is an explicit opt-in step (`lore enrich`), never runs during `sync`
+- Must work when no LLM is configured — `key_decisions` degrades to empty array (or falls back to heuristic as transitional behavior)
+
+---
+
+## Architecture
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────┐
+│                  lore enrich                     │
+│  (explicit user/agent command, batch operation)  │
+└──────────────────────┬──────────────────────────┘
+                       │
+         ┌─────────────▼─────────────┐
+         │    Enrichment Pipeline     │
+         │  1. Select stale threads   │
+         │  2. Build LLM prompts      │
+         │  3. Call LLM (batched)     │
+         │  4. Parse responses        │
+         │  5. Store in DB            │
+         └─────────────┬─────────────┘
+                       │
+         ┌─────────────▼─────────────┐
+         │   discussion_analysis     │
+         │   (SQLite table)          │
+         └─────────────┬─────────────┘
+                       │
+         ┌─────────────▼─────────────┐
+         │   lore explain / other    │
+         │   (simple SELECT query)   │
+         └───────────────────────────┘
+```
+
+### Data Flow
+
+1. **Staleness detection**: For each discussion, compute `SHA-256(sorted note IDs + note bodies)`. Compare against stored `notes_hash`. Skip if unchanged.
+2. **Prompt construction**: Extract the last N notes (configurable, default 5) from the thread. Build a structured prompt asking for discourse classification.
+3. **LLM call**: Send to configured backend (Bedrock or Anthropic API). Parse structured JSON response.
+4. **Storage**: Upsert into `discussion_analysis` with analysis results, model ID, timestamp, and notes_hash.
+
+### Pre-computation vs Runtime Trade-offs
+
+| Concern | Pre-computed (chosen) | Runtime |
+|---------|----------------------|---------|
+| explain latency | <500ms (DB query) | 2-5s per thread (LLM call) |
+| Offline capability | Full | None |
+| Bedrock compliance | Clean separation | Leaks into explain path |
+| Reusability | Any command can query | Tied to explain |
+| Freshness | Stale until re-enriched | Always current |
+| Cost | Batch (predictable) | Per-query (unbounded) |
+
+---
+
+## Schema
+
+### New Migration (next available version)
+
+```sql
+CREATE TABLE discussion_analysis (
+    id INTEGER PRIMARY KEY,
+    discussion_id INTEGER NOT NULL REFERENCES discussions(id),
+    analysis_type TEXT NOT NULL,  -- 'decision', 'question_answered', 'consensus', 'open_debate', 'informational'
+    confidence REAL NOT NULL,     -- 0.0 to 1.0
+    summary TEXT NOT NULL,        -- LLM-generated 1-2 sentence summary
+    evidence_note_ids TEXT,       -- JSON array of note IDs that support this analysis
+    model_id TEXT NOT NULL,       -- e.g. 'anthropic.claude-3-haiku-20240307-v1:0'
+    analyzed_at INTEGER NOT NULL, -- ms epoch
+    notes_hash TEXT NOT NULL,     -- SHA-256 of thread content for staleness detection
+
+    UNIQUE(discussion_id, analysis_type)
+);
+
+CREATE INDEX idx_discussion_analysis_discussion
+    ON discussion_analysis(discussion_id);
+
+CREATE INDEX idx_discussion_analysis_type
+    ON discussion_analysis(analysis_type);
+```
+
+**Design decisions:**
+- `UNIQUE(discussion_id, analysis_type)`: A thread can have at most one analysis per type. Re-enrichment upserts.
+- `evidence_note_ids` is a JSON array (not a junction table) because it's read-only metadata, never queried by note ID.
+- `notes_hash` enables O(1) staleness checks without re-reading all notes.
+- `confidence` allows filtering in queries (e.g., only show decisions with confidence > 0.7).
+- `analysis_type` uses lowercase snake_case strings, not an enum constraint, for forward compatibility.
+
+### Analysis Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `decision` | A concrete decision was made or confirmed | "Team agreed to use Redis for caching" |
+| `question_answered` | A question was asked and definitively answered | "Confirmed: the API supports pagination via cursor" |
+| `consensus` | Multiple participants converged on an approach | "All reviewers approved the retry-with-backoff strategy" |
+| `open_debate` | Active disagreement or unresolved discussion | "Disagreement on whether to use gRPC vs REST" |
+| `informational` | Thread is purely informational, no actionable discourse | "Status update on deployment progress" |
+
+### Notes Hash Computation
+
+```
+notes_hash = SHA-256(
+    note_1_id + ":" + note_1_body + "\n" +
+    note_2_id + ":" + note_2_body + "\n" +
+    ...
+)
+```
+
+Notes sorted by `id` (insertion order) before hashing. This means:
+- New note added → hash changes → re-enrich
+- Note edited (body changes) → hash changes → re-enrich
+- No changes → hash matches → skip
+
+---
+
+## CLI Command
+
+### `lore enrich discussions`
+
+```bash
+# Enrich all stale discussions across all projects
+lore enrich discussions
+
+# Scope to a project
+lore enrich discussions -p group/repo
+
+# Scope to a single entity's discussions
+lore enrich discussions --issue 42 -p group/repo
+lore enrich discussions --mr 99 -p group/repo
+
+# Force re-enrichment (ignore staleness)
+lore enrich discussions --force
+
+# Dry run (show what would be enriched, don't call LLM)
+lore enrich discussions --dry-run
+
+# Limit batch size
+lore enrich discussions --max-threads 50
+
+# Robot mode
+lore -J enrich discussions
+```
+
+### Robot Mode Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "total_discussions": 1200,
+    "stale": 45,
+    "enriched": 45,
+    "skipped_unchanged": 1155,
+    "errors": 0,
+    "tokens_used": {
+      "input": 23400,
+      "output": 4500
+    }
+  },
+  "meta": { "elapsed_ms": 32000 }
+}
+```
+
+### Human Mode Output
+
+```
+Enriching discussions...
+
+  Project: vs/typescript-code
+    Discussions: 1,200 total, 45 stale
+    Enriching: ████████████████████ 45/45
+    Results: 12 decisions, 8 questions answered, 5 consensus, 3 debates, 17 informational
+    Tokens: 23.4K input, 4.5K output
+
+  Done in 32s
+```
+
+### Command Registration
+
+```rust
+/// Pre-compute discourse analysis for discussion threads using LLM
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore enrich discussions                      # Enrich all stale discussions
+  lore enrich discussions -p group/repo        # Scope to project
+  lore enrich discussions --issue 42           # Single issue's discussions
+  lore -J enrich discussions --dry-run         # Preview what would be enriched")]
+Enrich {
+    /// What to enrich: "discussions"
+    #[arg(value_parser = ["discussions"])]
+    target: String,
+
+    /// Scope to project (fuzzy match)
+    #[arg(short, long)]
+    project: Option<String>,
+
+    /// Scope to a specific issue's discussions
+    #[arg(long, conflicts_with = "mr")]
+    issue: Option<i64>,
+
+    /// Scope to a specific MR's discussions
+    #[arg(long, conflicts_with = "issue")]
+    mr: Option<i64>,
+
+    /// Re-enrich all threads regardless of staleness
+    #[arg(long)]
+    force: bool,
+
+    /// Show what would be enriched without calling LLM
+    #[arg(long)]
+    dry_run: bool,
+
+    /// Maximum threads to enrich in one run
+    #[arg(long, default_value = "500")]
+    max_threads: usize,
+},
+```
+
+---
+
+## LLM Provider Abstraction
+
+### Config Schema
+
+New `enrichment` section in `~/.config/lore/config.json`:
+
+```json
+{
+  "enrichment": {
+    "provider": "bedrock",
+    "bedrock": {
+      "region": "us-east-1",
+      "modelId": "anthropic.claude-3-haiku-20240307-v1:0",
+      "profile": "default"
+    },
+    "anthropicApi": {
+      "modelId": "claude-3-haiku-20240307"
+    },
+    "concurrency": 4,
+    "maxNotesPerThread": 5,
+    "minConfidence": 0.6
+  }
+}
+```
+
+**Provider selection:**
+- `"bedrock"` — AWS Bedrock (uses AWS SDK credential chain: env vars → profile → IAM role)
+- `"anthropic"` — Anthropic API (uses `ANTHROPIC_API_KEY` env var)
+- `null` or absent — enrichment disabled, `lore enrich` exits with informative message
+
+### Rust Abstraction
+
+```rust
+/// Trait for LLM backends. Implementations handle auth, serialization, and API specifics.
+#[async_trait]
+pub trait LlmProvider: Send + Sync {
+    /// Send a prompt and get a structured response.
+    async fn complete(&self, prompt: &str, max_tokens: u32) -> Result<LlmResponse>;
+
+    /// Provider name for logging/storage (e.g., "bedrock", "anthropic")
+    fn provider_name(&self) -> &str;
+
+    /// Model identifier for storage (e.g., "anthropic.claude-3-haiku-20240307-v1:0")
+    fn model_id(&self) -> &str;
+}
+
+pub struct LlmResponse {
+    pub content: String,
+    pub input_tokens: u32,
+    pub output_tokens: u32,
+    pub stop_reason: String,
+}
+```
+
+### Bedrock Implementation Notes
+
+- Uses AWS SDK `InvokeModel` API (not Converse) for Anthropic models on Bedrock
+- Request body follows Anthropic Messages API format, wrapped in Bedrock's envelope
+- Auth: AWS credential chain (env → profile → IMDS)
+- Region from config or `AWS_REGION` env var
+- Content type: `application/json`, accept: `application/json`
+
+### Anthropic API Implementation Notes
+
+- Standard Messages API (`POST /v1/messages`)
+- Auth: `x-api-key` header from `ANTHROPIC_API_KEY` env var
+- Model ID from config `enrichment.anthropicApi.modelId`
+
+---
+
+## Prompt Design
+
+### Thread-Level Analysis Prompt
+
+The prompt receives the last N notes from a discussion thread and classifies the discourse.
+
+```
+You are analyzing a discussion thread from a software project's issue tracker.
+
+Thread context:
+- Entity: {entity_type} #{iid} "{title}"
+- Thread started: {first_note_at}
+- Total notes in thread: {note_count}
+
+Notes (most recent {N} shown):
+
+[Note by @{author} at {timestamp}]
+{body}
+
+[Note by @{author} at {timestamp}]
+{body}
+
+...
+
+Classify this thread's discourse. Respond with JSON only:
+
+{
+  "analysis_type": "decision" | "question_answered" | "consensus" | "open_debate" | "informational",
+  "confidence": 0.0-1.0,
+  "summary": "1-2 sentence summary of what was decided/answered/debated",
+  "evidence_note_indices": [0, 2]  // indices of notes that most support this classification
+}
+
+Classification guide:
+- "decision": A concrete choice was made. Look for: "let's go with", "agreed", "approved", explicit confirmation of an approach.
+- "question_answered": A question was asked and definitively answered. Look for: question mark followed by a clear factual response.
+- "consensus": Multiple people converged. Look for: multiple approvals, "+1", "LGTM", agreement from different authors.
+- "open_debate": Active disagreement or unresolved alternatives. Look for: "but", "alternatively", "I disagree", competing proposals without resolution.
+- "informational": Status updates, FYI notes, no actionable discourse.
+
+If the thread is ambiguous, prefer "informational" with lower confidence over guessing.
+```
+
+### Prompt Design Principles
+
+1. **Structured JSON output** — Haiku is reliable at JSON generation with clear schema
+2. **Evidence-backed** — `evidence_note_indices` ties the classification to specific notes, enabling the UI to show "why"
+3. **Conservative default** — "informational" is the fallback, preventing false-positive decisions
+4. **Limited context window** — Last 5 notes (configurable) keeps token usage low per thread
+5. **No system prompt tricks** — Straightforward classification task within Haiku's strengths
+
+### Token Budget Estimation
+
+| Component | Tokens (approx) |
+|-----------|-----------------|
+| System/instruction prompt | ~300 |
+| Thread metadata | ~50 |
+| 5 notes (avg 100 words each) | ~750 |
+| Response | ~100 |
+| **Total per thread** | **~1,200** |
+
+At Haiku pricing (~$0.25/1M input, ~$1.25/1M output):
+- 100 threads ≈ $0.03 input + $0.01 output = **~$0.04**
+- 1,000 threads ≈ **~$0.40**
+
+---
+
+## Explain Integration
+
+### Current Behavior (to be replaced)
+
+`explain.rs:650` — `extract_key_decisions()` uses the 60-minute same-actor heuristic.
+
+### New Behavior
+
+When `discussion_analysis` table has data for the entity's discussions:
+
+```rust
+fn fetch_key_decisions_from_enrichment(
+    conn: &Connection,
+    entity_type: &str,
+    entity_id: i64,
+    max_decisions: usize,
+) -> Result<Vec<KeyDecision>> {
+    let id_col = id_column_for(entity_type);
+    let sql = format!(
+        "SELECT da.analysis_type, da.confidence, da.summary, da.evidence_note_ids,
+                da.analyzed_at, d.gitlab_discussion_id
+         FROM discussion_analysis da
+         JOIN discussions d ON da.discussion_id = d.id
+         WHERE d.{id_col} = ?1
+           AND da.analysis_type IN ('decision', 'question_answered', 'consensus')
+           AND da.confidence >= ?2
+         ORDER BY da.confidence DESC, da.analyzed_at DESC
+         LIMIT ?3"
+    );
+    // ... map to KeyDecision structs
+}
+```
+
+### Fallback Strategy
+
+```
+if discussion_analysis table has rows for this entity:
+    use enrichment data → key_decisions
+else if enrichment is not configured:
+    fall back to heuristic (existing behavior)
+else:
+    return empty key_decisions with a hint: "Run 'lore enrich discussions' to populate"
+```
+
+This preserves backwards compatibility during rollout. The heuristic can be removed entirely once enrichment is the established workflow.
+
+### KeyDecision Struct Changes
+
+```rust
+#[derive(Debug, Serialize)]
+pub struct KeyDecision {
+    pub timestamp: String,           // ISO 8601 (analyzed_at or note timestamp)
+    pub actor: Option<String>,       // May not be single-actor for consensus
+    pub action: String,              // analysis_type: "decision", "question_answered", "consensus"
+    pub summary: String,             // LLM-generated summary (replaces context_note)
+    pub confidence: f64,             // 0.0-1.0
+    pub discussion_id: Option<String>, // gitlab_discussion_id for linking
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source: Option<String>,      // "enrichment" or "heuristic" (transitional)
+}
+```
+
+---
+
+## Testing Strategy
+
+### Unit Tests (Mock LLM)
+
+The LLM provider trait enables deterministic testing with a mock:
+
+```rust
+struct MockLlmProvider {
+    responses: Vec<String>,  // pre-canned JSON responses
+    call_count: AtomicUsize,
+}
+
+impl LlmProvider for MockLlmProvider {
+    async fn complete(&self, _prompt: &str, _max_tokens: u32) -> Result<LlmResponse> {
+        let idx = self.call_count.fetch_add(1, Ordering::SeqCst);
+        Ok(LlmResponse {
+            content: self.responses[idx].clone(),
+            input_tokens: 100,
+            output_tokens: 50,
+            stop_reason: "end_turn".to_string(),
+        })
+    }
+}
+```
+
+### Test Cases
+
+| Test | What it validates |
+|------|-------------------|
+| `test_staleness_hash_changes_on_new_note` | notes_hash differs when note added |
+| `test_staleness_hash_stable_no_changes` | notes_hash identical on re-computation |
+| `test_enrichment_skips_unchanged_threads` | Threads with matching hash are not re-enriched |
+| `test_enrichment_force_ignores_hash` | `--force` re-enriches all threads |
+| `test_enrichment_stores_analysis` | Results persisted to `discussion_analysis` table |
+| `test_enrichment_upserts_on_rereun` | Re-enrichment updates existing rows |
+| `test_enrichment_dry_run_no_writes` | `--dry-run` produces count but writes nothing |
+| `test_enrichment_respects_max_threads` | Caps at `--max-threads` value |
+| `test_enrichment_scopes_to_project` | `-p` limits to project's discussions |
+| `test_enrichment_scopes_to_entity` | `--issue 42` limits to that issue's discussions |
+| `test_explain_uses_enrichment_data` | explain returns enrichment-sourced key_decisions |
+| `test_explain_falls_back_to_heuristic` | No enrichment data → heuristic results |
+| `test_explain_empty_when_no_data` | No enrichment, no heuristic matches → empty array |
+| `test_prompt_construction` | Prompt includes correct notes, metadata, and instruction |
+| `test_response_parsing_valid_json` | Well-formed LLM response parsed correctly |
+| `test_response_parsing_malformed` | Malformed response logged, thread skipped (not crash) |
+| `test_confidence_filter` | Only analysis above `minConfidence` shown in explain |
+| `test_provider_config_bedrock` | Bedrock config parsed and provider instantiated |
+| `test_provider_config_anthropic` | Anthropic API config parsed correctly |
+| `test_no_enrichment_config_graceful` | Missing enrichment config → informative message, exit 0 |
+
+### Integration Tests
+
+- **Real Bedrock call** (gated behind `#[ignore]` + env var `LORE_TEST_BEDROCK=1`): Sends one real prompt to Bedrock, asserts valid JSON response with expected schema.
+- **Full pipeline**: In-memory DB → insert discussions + notes → enrich with mock → verify `discussion_analysis` populated → run explain → verify key_decisions sourced from enrichment.
+
+---
+
+## Boundaries
+
+### Always (autonomous)
+- Run `cargo test` and `cargo clippy` after every code change
+- Use `MockLlmProvider` in all non-integration tests
+- Respect `--dry-run` flag — never call LLM in dry-run mode
+- Log token usage for every enrichment run
+- Graceful degradation when no enrichment config exists
+
+### Ask First (needs approval)
+- Adding AWS SDK or HTTP dependencies to Cargo.toml
+- Choosing between `aws-sdk-bedrockruntime` crate vs raw HTTP to Bedrock
+- Modifying the `Config` struct (new `enrichment` field)
+- Changing `KeyDecision` struct shape (affects robot mode API contract)
+
+### Never (hard stops)
+- No LLM calls in `lore explain` path — enrichment is pre-computed only
+- No storing API keys in config file — use env vars / credential chain
+- No automatic enrichment during `lore sync` — enrichment is always explicit
+- No sending discussion content to any service other than the configured LLM provider
+
+---
+
+## Non-Goals
+
+- **No real-time streaming** — Enrichment is batch, not streaming
+- **No multi-model ensemble** — Single model per run, configurable per config
+- **No custom fine-tuning** — Uses Haiku as-is with prompt engineering
+- **No enrichment of individual notes** — Thread-level only (the unit of discourse)
+- **No automatic re-enrichment on sync** — User/agent must explicitly run `lore enrich`
+- **No modification of discussion/notes tables** — Enrichment data lives in its own table
+- **No embedding-based approach** — This is classification, not similarity search
+
+---
+
+## User Journeys
+
+### P1 — Critical
+- **UJ-1: Agent enriches discussions before explain**
+  - Actor: AI agent (via robot mode)
+  - Flow: `lore -J enrich discussions -p group/repo` → JSON summary of enrichment run → `lore -J explain issues 42` → key_decisions populated from enrichment
+  - Error paths: No enrichment config (exit with suggestion), Bedrock auth failure (exit 5), rate limited (exit 7)
+  - Implemented by: Tasks 1-5
+
+### P2 — Important
+- **UJ-2: Human runs enrichment and checks results**
+  - Actor: Developer at terminal
+  - Flow: `lore enrich discussions` → progress bar → summary → `lore explain issues 42` → sees decisions in narrative
+  - Error paths: Same as UJ-1 but with human-readable messages
+  - Implemented by: Tasks 1-5
+
+- **UJ-3: Incremental enrichment after sync**
+  - Actor: AI agent or human
+  - Flow: `lore sync` → new notes ingested → `lore enrich discussions` → only stale threads re-enriched → fast completion
+  - Implemented by: Task 2 (staleness detection)
+
+### P3 — Nice to Have
+- **UJ-4: Dry-run to estimate cost**
+  - Actor: Cost-conscious user
+  - Flow: `lore enrich discussions --dry-run` → see thread count and estimated tokens → decide whether to proceed
+  - Implemented by: Task 4
+
+---
+
+## Tasks
+
+### Phase 1: Schema & Provider Abstraction
+
+- [ ] **Task 1:** Database migration + LLM provider trait
+  - **Implements:** Infrastructure (all UJs)
+  - **Files:** `src/core/db.rs` (migration), NEW `src/enrichment/mod.rs`, NEW `src/enrichment/provider.rs`
+  - **Depends on:** Nothing
+  - **Test-first:**
+    1. Write `test_migration_creates_discussion_analysis_table`: run migrations, verify table exists with correct columns
+    2. Write `test_provider_config_bedrock`: parse config JSON with bedrock enrichment section
+    3. Write `test_provider_config_anthropic`: parse config JSON with anthropic enrichment section
+    4. Write `test_no_enrichment_config_graceful`: parse config without enrichment section, verify `None`
+    5. Run tests — all FAIL (red)
+    6. Implement migration + `LlmProvider` trait + `EnrichmentConfig` struct + config parsing
+    7. Run tests — all PASS (green)
+  - **Acceptance:** Migration creates table. Config parses both provider variants. Missing config returns `None`.
+
+### Phase 2: Staleness & Prompt Pipeline
+
+- [ ] **Task 2:** Notes hash computation + staleness detection
+  - **Implements:** UJ-3 (incremental enrichment)
+  - **Files:** `src/enrichment/staleness.rs`
+  - **Depends on:** Task 1
+  - **Test-first:**
+    1. Write `test_staleness_hash_changes_on_new_note`
+    2. Write `test_staleness_hash_stable_no_changes`
+    3. Write `test_enrichment_skips_unchanged_threads`
+    4. Run tests — all FAIL (red)
+    5. Implement `compute_notes_hash()` + `find_stale_discussions()` query
+    6. Run tests — all PASS (green)
+  - **Acceptance:** Hash deterministic. Stale detection correct. Unchanged threads skipped.
+
+- [ ] **Task 3:** Prompt construction + response parsing
+  - **Implements:** Core enrichment logic
+  - **Files:** `src/enrichment/prompt.rs`, `src/enrichment/parser.rs`
+  - **Depends on:** Task 1
+  - **Test-first:**
+    1. Write `test_prompt_construction`: verify prompt includes notes, metadata, instruction
+    2. Write `test_response_parsing_valid_json`: well-formed response parsed
+    3. Write `test_response_parsing_malformed`: malformed response returns error (not panic)
+    4. Run tests — all FAIL (red)
+    5. Implement `build_prompt()` + `parse_analysis_response()`
+    6. Run tests — all PASS (green)
+  - **Acceptance:** Prompt is well-formed. Parser handles valid and invalid responses gracefully.
+
+### Phase 3: CLI Command & Pipeline
+
+- [ ] **Task 4:** `lore enrich discussions` command + enrichment pipeline
+  - **Implements:** UJ-1, UJ-2, UJ-4
+  - **Files:** NEW `src/cli/commands/enrich.rs`, `src/cli/mod.rs`, `src/main.rs`
+  - **Depends on:** Tasks 1, 2, 3
+  - **Test-first:**
+    1. Write `test_enrichment_stores_analysis`: mock LLM → verify rows in `discussion_analysis`
+    2. Write `test_enrichment_upserts_on_rerun`: enrich → re-enrich → verify single row updated
+    3. Write `test_enrichment_dry_run_no_writes`: dry-run → verify zero rows written
+    4. Write `test_enrichment_respects_max_threads`: 10 stale, max=3 → only 3 enriched
+    5. Write `test_enrichment_scopes_to_project`: verify project filter
+    6. Write `test_enrichment_scopes_to_entity`: verify --issue/--mr filter
+    7. Run tests — all FAIL (red)
+    8. Implement: command registration, pipeline orchestration, mock-based tests
+    9. Run tests — all PASS (green)
+  - **Acceptance:** Full pipeline works with mock. Dry-run safe. Scoping correct. Robot JSON matches schema.
+
+### Phase 4: LLM Backend Implementations
+
+- [ ] **Task 5:** Bedrock + Anthropic API provider implementations
+  - **Implements:** UJ-1, UJ-2 (actual LLM connectivity)
+  - **Files:** `src/enrichment/bedrock.rs`, `src/enrichment/anthropic.rs`
+  - **Depends on:** Task 4
+  - **Test-first:**
+    1. Write `test_bedrock_request_format`: verify request body matches Bedrock InvokeModel schema
+    2. Write `test_anthropic_request_format`: verify request body matches Messages API schema
+    3. Write integration test (gated `#[ignore]`): real Bedrock call, assert valid response
+    4. Run tests — unit FAIL (red), integration skipped
+    5. Implement both providers
+    6. Run tests — all PASS (green)
+  - **Acceptance:** Both providers construct valid requests. Auth works via standard credential chains. Integration test passes when enabled.
+
+### Phase 5: Explain Integration
+
+- [ ] **Task 6:** Replace heuristic with enrichment data in explain
+  - **Implements:** UJ-1, UJ-2 (the payoff)
+  - **Files:** `src/cli/commands/explain.rs`
+  - **Depends on:** Task 4
+  - **Test-first:**
+    1. Write `test_explain_uses_enrichment_data`: insert mock enrichment rows → explain returns them as key_decisions
+    2. Write `test_explain_falls_back_to_heuristic`: no enrichment rows → returns heuristic results
+    3. Write `test_confidence_filter`: insert rows with varying confidence → only high-confidence shown
+    4. Run tests — all FAIL (red)
+    5. Implement `fetch_key_decisions_from_enrichment()` + fallback logic
+    6. Run tests — all PASS (green)
+  - **Acceptance:** Explain uses enrichment when available. Falls back gracefully. Confidence threshold respected.
+
+---
+
+## Dependencies (New Crates — Needs Discussion)
+
+| Crate | Purpose | Alternative |
+|-------|---------|-------------|
+| `aws-sdk-bedrockruntime` | Bedrock InvokeModel API | Raw HTTP via existing `HttpClient` |
+| `sha2` | SHA-256 for notes_hash | Already in dependency tree? Check. |
+
+**Decision needed:** Use AWS SDK crate (heavier but handles auth/signing) vs. raw HTTP with SigV4 signing (lighter but more implementation work)?
+
+---
+
+## Session Log
+
+### Session 1 — 2026-03-11
+- Identified key_decisions heuristic as fundamentally inadequate (60-min same-actor window)
+- User vision: LLM-powered discourse analysis, pre-computed for offline explain
+- Key constraint: Bedrock required for org security compliance
+- Designed pre-computed enrichment architecture
+- Wrote initial spec draft for iteration

specs/SPEC_explain.md

@@ -0,0 +1,701 @@
+# Spec: lore explain — Auto-Generated Issue/MR Narratives
+
+**Bead:** bd-9lbr
+**Created:** 2026-03-10
+
+## Spec Status
+| Section | Status | Notes |
+|---------|--------|-------|
+| Objective | complete | |
+| Tech Stack | complete | |
+| Project Structure | complete | |
+| Commands | complete | |
+| Code Style | complete | UX-audited: after_help, --sections, --since, --no-timeline, --max-decisions, singular types |
+| Boundaries | complete | |
+| Testing Strategy | complete | 13 test cases (7 original + 5 UX flags + 1 singular type) |
+| Git Workflow | complete | jj-first |
+| User Journeys | complete | 3 journeys covering agent, human, pipeline use |
+| Architecture | complete | ExplainParams + section filtering + time scoping |
+| Success Criteria | complete | 15 criteria (10 original + 5 UX flags) |
+| Non-Goals | complete | |
+| Tasks | complete | 5 tasks across 3 phases, all updated for UX flags |
+
+**Definition of Complete:** All sections `complete`, Open Questions empty,
+every user journey has tasks, every task has TDD workflow and acceptance criteria.
+
+---
+
+## Quick Reference
+- [Entity Detail] (Architecture): reuse show/ query patterns (private — copy, don't import)
+- [Timeline] (Architecture): import `crate::timeline::seed::seed_timeline_direct` + `collect_events`
+- [Events] (Architecture): new inline queries against resource_state_events/resource_label_events
+- [References] (Architecture): new query against entity_references table
+- [Discussions] (Architecture): adapted from show/ patterns, add resolved/resolvable filter
+
+---
+
+## Open Questions (Resolve Before Implementation)
+<!-- All resolved -->
+
+---
+
+## Objective
+
+**Goal:** Add `lore explain issues N` / `lore explain mrs N` to auto-generate structured narratives of what happened on an issue or MR.
+
+**Problem:** Understanding the full story of an issue/MR requires reading dozens of notes, cross-referencing state changes, checking related entities, and piecing together a timeline. This is time-consuming for humans and nearly impossible for AI agents without custom orchestration.
+
+**Success metrics:**
+- Produces a complete narrative in <500ms for an issue with 50 notes
+- All 7 sections populated (entity, description_excerpt, key_decisions, activity, open_threads, related, timeline_excerpt)
+- Works fully offline (no API calls, no LLM)
+- Deterministic and reproducible (same input = same output)
+
+---
+
+## Tech Stack & Constraints
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| Language | Rust | nightly-2026-03-01 (rust-toolchain.toml) |
+| Framework | clap (derive) | As in Cargo.toml |
+| Database | SQLite via rusqlite | Bundled |
+| Testing | cargo test | Inline #[cfg(test)] |
+| Async | asupersync | 0.2 |
+
+**Constraints:**
+- No LLM dependency — template-based, deterministic
+- No network calls — all data from local SQLite
+- Performance: <500ms for 50-note entity
+- Unsafe code forbidden (`#![forbid(unsafe_code)]`)
+
+---
+
+## Project Structure
+
+```
+src/cli/commands/
+  explain.rs            # NEW: command module (queries, heuristic, result types)
+src/cli/
+  mod.rs                # EDIT: add Explain variant to Commands enum
+src/app/
+  handlers.rs           # EDIT: add handle_explain dispatch
+  robot_docs.rs         # EDIT: register explain in robot-docs manifest
+src/main.rs             # EDIT: add Explain match arm
+```
+
+---
+
+## Commands
+
+```bash
+# Build
+cargo check --all-targets
+
+# Test
+cargo test explain
+
+# Lint
+cargo clippy --all-targets -- -D warnings
+
+# Format
+cargo fmt --check
+```
+
+---
+
+## Code Style
+
+**Command registration (from cli/mod.rs):**
+```rust
+/// Auto-generate a structured narrative of an issue or MR
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore explain issues 42                  # Narrative for issue #42
+  lore explain mrs 99 -p group/repo       # Narrative for MR !99 in specific project
+  lore -J explain issues 42               # JSON output for automation
+  lore explain issues 42 --sections key_decisions,open_threads  # Specific sections only
+  lore explain issues 42 --since 30d      # Narrative scoped to last 30 days
+  lore explain issues 42 --no-timeline    # Skip timeline (faster)")]
+Explain {
+    /// Entity type: "issues" or "mrs" (singular forms also accepted)
+    #[arg(value_parser = ["issues", "mrs", "issue", "mr"])]
+    entity_type: String,
+
+    /// Entity IID
+    iid: i64,
+
+    /// Scope to project (fuzzy match)
+    #[arg(short, long)]
+    project: Option<String>,
+
+    /// Select specific sections (comma-separated)
+    /// Valid: entity, description, key_decisions, activity, open_threads, related, timeline
+    #[arg(long, value_delimiter = ',', help_heading = "Output")]
+    sections: Option<Vec<String>>,
+
+    /// Skip timeline excerpt (faster execution)
+    #[arg(long, help_heading = "Output")]
+    no_timeline: bool,
+
+    /// Maximum key decisions to include
+    #[arg(long, default_value = "10", help_heading = "Output")]
+    max_decisions: usize,
+
+    /// Time scope for events/notes (e.g. 7d, 2w, 1m, or YYYY-MM-DD)
+    #[arg(long, help_heading = "Filters")]
+    since: Option<String>,
+},
+```
+
+**Entity type normalization:** The handler must normalize singular forms: `"issue"` -> `"issues"`, `"mr"` -> `"mrs"`. This prevents common typos from causing errors.
+
+**Query pattern (from show/issue.rs):**
+```rust
+fn find_issue(conn: &Connection, iid: i64, project_filter: Option<&str>) -> Result<IssueRow> {
+    let project_id = resolve_project(conn, project_filter)?;
+    let mut stmt = conn.prepare_cached("SELECT ... FROM issues WHERE iid = ?1 AND project_id = ?2")?;
+    // ...
+}
+```
+
+**Robot mode output (from cli/robot.rs):**
+```rust
+let response = serde_json::json!({
+    "ok": true,
+    "data": result,
+    "meta": { "elapsed_ms": elapsed.as_millis() }
+});
+println!("{}", serde_json::to_string(&response)?);
+```
+
+---
+
+## Boundaries
+
+### Always (autonomous)
+- Run `cargo test explain` and `cargo clippy` after every code change
+- Follow existing query patterns from show/issue.rs and show/mr.rs
+- Use `resolve_project()` for project resolution (fuzzy match)
+- Cap key_decisions at `--max-decisions` (default 10), timeline_excerpt at 20 events
+- Normalize singular entity types (`issue` -> `issues`, `mr` -> `mrs`)
+- Respect `--sections` filter: omit unselected sections from output (both robot and human)
+- Respect `--since` filter: scope events/notes queries with `created_at >= ?` threshold
+
+### Ask First (needs approval)
+- Adding new dependencies to Cargo.toml
+- Modifying existing query functions in show/ or timeline/
+- Changing the entity_references table schema
+
+### Never (hard stops)
+- No LLM calls — explain must be deterministic
+- No API/network calls — fully offline
+- No new database migrations — use existing schema only
+- Do not modify show/ or timeline/ modules (copy patterns instead)
+
+---
+
+## Testing Strategy (TDD — Red-Green)
+
+**Methodology:** Test-Driven Development. Write tests first, confirm red, implement, confirm green.
+
+**Framework:** cargo test, inline `#[cfg(test)]`
+**Location:** `src/cli/commands/explain.rs` (inline test module)
+
+**Test categories:**
+- Unit tests: key-decisions heuristic, activity counting, description truncation
+- Integration tests: full explain pipeline with in-memory DB
+
+**User journey test mapping:**
+| Journey | Test | Scenarios |
+|---------|------|-----------|
+| UJ-1: Agent explains issue | test_explain_issue_basic | All 7 sections present, robot JSON valid |
+| UJ-1: Agent explains MR | test_explain_mr | entity.type = "merge_request", merged_at included |
+| UJ-1: Singular entity type | test_explain_singular_entity_type | `"issue"` normalizes to `"issues"` |
+| UJ-1: Section filtering | test_explain_sections_filter_robot | Only selected sections in output |
+| UJ-1: No-timeline flag | test_explain_no_timeline_flag | timeline_excerpt is None |
+| UJ-2: Human reads narrative | (human render tested manually) | Headers, indentation, color |
+| UJ-3: Key decisions | test_explain_key_decision_heuristic | Note within 60min of state change by same actor |
+| UJ-3: No false decisions | test_explain_key_decision_ignores_unrelated_notes | Different author's note excluded |
+| UJ-3: Max decisions cap | test_explain_max_decisions | Respects `--max-decisions` parameter |
+| UJ-3: Since scopes events | test_explain_since_scopes_events | Only recent events included |
+| UJ-3: Open threads | test_explain_open_threads | Only unresolved discussions in output |
+| UJ-3: Edge case | test_explain_no_notes | Empty sections, no panic |
+| UJ-3: Activity counts | test_explain_activity_counts | Correct state/label/note counts |
+
+---
+
+## Git Workflow
+
+- **jj-first** — all VCS via jj, not git
+- **Commit format:** `feat(explain): <description>`
+- **No branches** — commit in place, use jj bookmarks to push
+
+---
+
+## User Journeys (Prioritized)
+
+### P1 — Critical
+- **UJ-1: Agent queries issue/MR narrative**
+  - Actor: AI agent (via robot mode)
+  - Flow: `lore -J explain issues 42` → JSON with 7 sections → agent parses and acts
+  - Error paths: Issue not found (exit 17), ambiguous project (exit 18)
+  - Implemented by: Task 1, 2, 3, 4
+
+### P2 — Important
+- **UJ-2: Human reads explain output**
+  - Actor: Developer at terminal
+  - Flow: `lore explain issues 42` → formatted narrative with headers, colors, indentation
+  - Error paths: Same as UJ-1 but with human-readable error messages
+  - Implemented by: Task 5
+
+### P3 — Nice to Have
+- **UJ-3: Agent uses key-decisions to understand context**
+  - Actor: AI agent making decisions
+  - Flow: Parse `key_decisions` array → understand who decided what and when → inform action
+  - Error paths: No key decisions found (empty array, not error)
+  - Implemented by: Task 3
+
+---
+
+## Architecture / Data Model
+
+### Data Assembly Pipeline (sync, no async needed)
+
+```
+1. RESOLVE    → resolve_project() + find entity by IID
+2. PARSE      → normalize entity_type, parse --since, validate --sections
+3. DETAIL     → entity metadata (title, state, author, labels, assignees, status)
+4. EVENTS     → resource_state_events + resource_label_events (optionally --since scoped)
+5. NOTES      → non-system notes via discussions join (optionally --since scoped)
+6. HEURISTIC  → key_decisions = events correlated with notes by same actor within 60min
+7. THREADS    → discussions WHERE resolvable=1 AND resolved=0
+8. REFERENCES → entity_references (both directions: source and target)
+9. TIMELINE   → seed_timeline_direct + collect_events (capped at 20, skip if --no-timeline)
+10. FILTER    → apply --sections filter: drop unselected sections before serialization
+11. ASSEMBLE  → combine into ExplainResult
+```
+
+**Section filtering:** When `--sections` is provided, only the listed sections are populated.
+Unselected sections are set to their zero-value (`None`, empty vec, etc.) and omitted
+from robot JSON via `#[serde(skip_serializing_if = "...")]`. The `entity` section is always
+included (needed for identification). Human mode skips rendering unselected sections.
+
+**Time scoping:** When `--since` is provided, parse it using `crate::core::time::parse_since()`
+(same function used by timeline, me, file-history). Add `AND created_at >= ?` to events
+and notes queries. The entity header, references, and open threads are NOT time-scoped
+(they represent current state, not historical events).
+
+### Key Types
+
+```rust
+/// Parameters controlling explain behavior.
+pub struct ExplainParams {
+    pub entity_type: String,       // "issues" or "mrs" (already normalized)
+    pub iid: i64,
+    pub project: Option<String>,
+    pub sections: Option<Vec<String>>,  // None = all sections
+    pub no_timeline: bool,
+    pub max_decisions: usize,      // default 10
+    pub since: Option<i64>,        // ms epoch threshold from --since parsing
+}
+
+#[derive(Debug, Serialize)]
+pub struct ExplainResult {
+    pub entity: EntitySummary,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description_excerpt: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub key_decisions: Option<Vec<KeyDecision>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub activity: Option<ActivitySummary>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub open_threads: Option<Vec<OpenThread>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub related: Option<RelatedEntities>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub timeline_excerpt: Option<Vec<TimelineEventSummary>>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct EntitySummary {
+    #[serde(rename = "type")]
+    pub entity_type: String,    // "issue" or "merge_request"
+    pub iid: i64,
+    pub title: String,
+    pub state: String,
+    pub author: String,
+    pub assignees: Vec<String>,
+    pub labels: Vec<String>,
+    pub created_at: String,     // ISO 8601
+    pub updated_at: String,     // ISO 8601
+    pub url: Option<String>,
+    pub status_name: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct KeyDecision {
+    pub timestamp: String,      // ISO 8601
+    pub actor: String,
+    pub action: String,         // "state: opened -> closed" or "label: +bug"
+    pub context_note: String,   // truncated to 500 chars
+}
+
+#[derive(Debug, Serialize)]
+pub struct ActivitySummary {
+    pub state_changes: usize,
+    pub label_changes: usize,
+    pub notes: usize,           // non-system only
+    pub first_event: Option<String>,   // ISO 8601
+    pub last_event: Option<String>,    // ISO 8601
+}
+
+#[derive(Debug, Serialize)]
+pub struct OpenThread {
+    pub discussion_id: String,
+    pub started_by: String,
+    pub started_at: String,     // ISO 8601
+    pub note_count: usize,
+    pub last_note_at: String,   // ISO 8601
+}
+
+#[derive(Debug, Serialize)]
+pub struct RelatedEntities {
+    pub closing_mrs: Vec<ClosingMrInfo>,
+    pub related_issues: Vec<RelatedEntityInfo>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct TimelineEventSummary {
+    pub timestamp: String,      // ISO 8601
+    pub event_type: String,
+    pub actor: Option<String>,
+    pub summary: String,
+}
+```
+
+### Key Decisions Heuristic
+
+The heuristic identifies notes that explain WHY state/label changes were made:
+
+1. Collect all `resource_state_events` and `resource_label_events` for the entity
+2. Merge into unified chronological list with (timestamp, actor, description)
+3. For each event, find the FIRST non-system note by the SAME actor within 60 minutes AFTER the event
+4. Pair them as a `KeyDecision`
+5. Cap at `params.max_decisions` (default 10)
+
+**SQL for state events:**
+```sql
+SELECT state, actor_username, created_at
+FROM resource_state_events
+WHERE issue_id = ?1   -- or merge_request_id = ?1
+  AND (?2 IS NULL OR created_at >= ?2)   -- --since filter
+ORDER BY created_at ASC
+```
+
+**SQL for label events:**
+```sql
+SELECT action, label_name, actor_username, created_at
+FROM resource_label_events
+WHERE issue_id = ?1   -- or merge_request_id = ?1
+  AND (?2 IS NULL OR created_at >= ?2)   -- --since filter
+ORDER BY created_at ASC
+```
+
+**SQL for non-system notes (for correlation):**
+```sql
+SELECT n.body, n.author_username, n.created_at
+FROM notes n
+JOIN discussions d ON n.discussion_id = d.id
+WHERE d.noteable_type = ?1 AND d.issue_id = ?2   -- or d.merge_request_id
+  AND n.is_system = 0
+  AND (?3 IS NULL OR n.created_at >= ?3)   -- --since filter
+ORDER BY n.created_at ASC
+```
+
+**Entity ID resolution:** The `discussions` table uses `issue_id` / `merge_request_id` columns (CHECK constraint: exactly one non-NULL). The `resource_state_events` and `resource_label_events` tables use the same pattern.
+
+### Cross-References Query
+
+```sql
+-- Outgoing references (this entity references others)
+SELECT target_entity_type, target_entity_id, target_project_path,
+       target_entity_iid, reference_type, source_method
+FROM entity_references
+WHERE source_entity_type = ?1 AND source_entity_id = ?2
+
+-- Incoming references (others reference this entity)
+SELECT source_entity_type, source_entity_id,
+       reference_type, source_method
+FROM entity_references
+WHERE target_entity_type = ?1 AND target_entity_id = ?2
+```
+
+**Note:** For closing MRs, reuse the pattern from show/issue.rs `get_closing_mrs()` which queries entity_references with `reference_type = 'closes'`.
+
+### Open Threads Query
+
+```sql
+SELECT d.gitlab_discussion_id, d.first_note_at, d.last_note_at
+FROM discussions d
+WHERE d.issue_id = ?1   -- or d.merge_request_id
+  AND d.resolvable = 1
+  AND d.resolved = 0
+ORDER BY d.last_note_at DESC
+```
+
+Then for each discussion, fetch the first note's author:
+```sql
+SELECT author_username, created_at
+FROM notes
+WHERE discussion_id = ?1
+ORDER BY created_at ASC
+LIMIT 1
+```
+
+And count notes per discussion:
+```sql
+SELECT COUNT(*) FROM notes WHERE discussion_id = ?1 AND is_system = 0
+```
+
+### Robot Mode Output Schema
+
+```json
+{
+  "ok": true,
+  "data": {
+    "entity": {
+      "type": "issue", "iid": 3864, "title": "...", "state": "opened",
+      "author": "teernisse", "assignees": ["teernisse"],
+      "labels": ["customer:BNSF"], "created_at": "2026-01-10T...",
+      "updated_at": "2026-02-12T...", "url": "...", "status_name": "In progress"
+    },
+    "description_excerpt": "First 500 chars...",
+    "key_decisions": [{
+      "timestamp": "2026-01-15T...",
+      "actor": "teernisse",
+      "action": "state: opened -> closed",
+      "context_note": "Starting work on the integration..."
+    }],
+    "activity": {
+      "state_changes": 3, "label_changes": 5, "notes": 42,
+      "first_event": "2026-01-10T...", "last_event": "2026-02-12T..."
+    },
+    "open_threads": [{
+      "discussion_id": "abc123",
+      "started_by": "cseiber",
+      "started_at": "2026-02-01T...",
+      "note_count": 5,
+      "last_note_at": "2026-02-10T..."
+    }],
+    "related": {
+      "closing_mrs": [{ "iid": 200, "title": "...", "state": "merged" }],
+      "related_issues": [{ "iid": 3800, "title": "Rail Break Card", "type": "related" }]
+    },
+    "timeline_excerpt": [
+      { "timestamp": "...", "event_type": "state_changed", "actor": "teernisse", "summary": "State changed to closed" }
+    ]
+  },
+  "meta": { "elapsed_ms": 350 }
+}
+```
+
+---
+
+## Success Criteria
+
+| # | Criterion | Input | Expected Output |
+|---|-----------|-------|----------------|
+| 1 | Issue explain produces all 7 sections | `lore -J explain issues N` | JSON with entity, description_excerpt, key_decisions, activity, open_threads, related, timeline_excerpt |
+| 2 | MR explain produces all 7 sections | `lore -J explain mrs N` | Same shape, entity.type = "merge_request" |
+| 3 | Key decisions captures correlated notes | State change + note by same actor within 60min | KeyDecision with action + context_note |
+| 4 | Key decisions ignores unrelated notes | Note by different author near state change | Not in key_decisions array |
+| 5 | Open threads filters correctly | 2 discussions: 1 resolved, 1 unresolved | Only unresolved in open_threads |
+| 6 | Activity counts are accurate | 3 state events, 2 label events, 10 notes | Matching counts in activity section |
+| 7 | Performance | Issue with 50 notes | <500ms |
+| 8 | Entity not found | Non-existent IID | Exit code 17, suggestion to sync |
+| 9 | Ambiguous project | IID exists in multiple projects, no -p | Exit code 18, suggestion to use -p |
+| 10 | Human render | `lore explain issues N` (no -J) | Formatted narrative with headers |
+| 11 | Singular entity type accepted | `lore explain issue 42` | Same as `lore explain issues 42` |
+| 12 | Section filtering works | `--sections key_decisions,activity` | Only those 2 sections + entity in JSON |
+| 13 | No-timeline skips timeline | `--no-timeline` | timeline_excerpt absent, faster execution |
+| 14 | Max-decisions caps output | `--max-decisions 3` | At most 3 key_decisions |
+| 15 | Since scopes events/notes | `--since 30d` | Only events/notes from last 30 days in activity, key_decisions |
+
+---
+
+## Non-Goals
+
+- **No LLM summarization** — This is template-based v1. LLM enhancement is a separate future feature.
+- **No new database migrations** — Uses existing schema (resource_state_events, resource_label_events, discussions, notes, entity_references tables all exist).
+- **No modification of show/ or timeline/ modules** — Copy patterns, don't refactor existing code. If we later want to share code, that's a separate refactoring bead.
+- **No interactive mode** — Output only, no prompts or follow-up questions.
+- **No MR diff analysis** — No file-level change summaries. Use `file-history` or `trace` for that.
+- **No assignee/reviewer history** — Activity summary counts events but doesn't track assignment changes over time.
+
+---
+
+## Tasks
+
+### Phase 1: Setup & Registration
+
+- [ ] **Task 1:** Register explain command in CLI and wire dispatch
+  - **Implements:** Infrastructure (UJ-1, UJ-2 prerequisite)
+  - **Files:** `src/cli/mod.rs`, `src/cli/commands/mod.rs`, `src/main.rs`, `src/app/handlers.rs`, NEW `src/cli/commands/explain.rs`
+  - **Depends on:** Nothing
+  - **Test-first:**
+    1. Write `test_explain_issue_basic` in explain.rs: insert a minimal issue + project + 1 discussion + 1 note + 1 state event into in-memory DB, call `run_explain()` with default ExplainParams, assert all 7 top-level sections present in result
+    2. Write `test_explain_mr` in explain.rs: insert MR with merged_at, call `run_explain()`, assert `entity.type == "merge_request"` and merged_at is populated
+    3. Write `test_explain_singular_entity_type`: call with `entity_type: "issue"`, assert it resolves same as `"issues"`
+    4. Run tests — all must FAIL (red)
+    5. Implement: Explain variant in Commands enum (with all flags: `--sections`, `--no-timeline`, `--max-decisions`, `--since`, singular entity type acceptance), handle_explain in handlers.rs (normalize entity_type, parse --since, build ExplainParams), skeleton `run_explain()` in explain.rs
+    6. Run tests — all must PASS (green)
+  - **Acceptance:** `cargo test explain::tests::test_explain_issue_basic`, `test_explain_mr`, and `test_explain_singular_entity_type` pass. Command registered in CLI help with after_help examples block.
+  - **Implementation notes:**
+    - Use inline args pattern (like Drift) with all flags from Code Style section
+    - `entity_type` validated by `#[arg(value_parser = ["issues", "mrs", "issue", "mr"])]`
+    - Normalize in handler: `"issue"` -> `"issues"`, `"mr"` -> `"mrs"`
+    - Parse `--since` using `crate::core::time::parse_since()` — returns ms epoch threshold
+    - Validate `--sections` values against allowed set: `["entity", "description", "key_decisions", "activity", "open_threads", "related", "timeline"]`
+    - Copy the `find_issue`/`find_mr` and `get_*` query patterns from show/issue.rs and show/mr.rs — they're private functions so can't be imported
+    - Use `resolve_project()` from `crate::core::project` for project resolution
+    - Use `ms_to_iso()` from `crate::core::time` for timestamp conversion
+
+### Phase 2: Core Logic
+
+- [ ] **Task 2:** Implement key-decisions heuristic
+  - **Implements:** UJ-3
+  - **Files:** `src/cli/commands/explain.rs`
+  - **Depends on:** Task 1
+  - **Test-first:**
+    1. Write `test_explain_key_decision_heuristic`: insert state change event at T, insert note by SAME author at T+30min, call `extract_key_decisions()`, assert 1 decision with correct action + context_note
+    2. Write `test_explain_key_decision_ignores_unrelated_notes`: insert state change by alice, insert note by bob at T+30min, assert 0 decisions
+    3. Write `test_explain_key_decision_label_event`: insert label add event + correlated note, assert decision.action starts with "label: +"
+    4. Run tests — all must FAIL (red)
+    4. Write `test_explain_max_decisions`: insert 5 correlated event+note pairs, call with `max_decisions: 3`, assert exactly 3 decisions returned
+    5. Write `test_explain_since_scopes_events`: insert event at T-60d and event at T-10d, call with `since: Some(T-30d)`, assert only recent event appears
+    6. Run tests — all must FAIL (red)
+    7. Implement `extract_key_decisions()` function:
+       - Query resource_state_events and resource_label_events for entity (with optional `--since` filter)
+       - Merge into unified chronological list
+       - For each event, find first non-system note by same actor within 60min (notes also `--since` filtered)
+       - Cap at `params.max_decisions`
+    8. Run tests — all must PASS (green)
+  - **Acceptance:** All 5 tests pass. Heuristic correctly correlates events with explanatory notes. `--max-decisions` and `--since` respected.
+  - **Implementation notes:**
+    - State events query: `SELECT state, actor_username, created_at FROM resource_state_events WHERE {id_col} = ?1 AND (?2 IS NULL OR created_at >= ?2) ORDER BY created_at`
+    - Label events query: `SELECT action, label_name, actor_username, created_at FROM resource_label_events WHERE {id_col} = ?1 AND (?2 IS NULL OR created_at >= ?2) ORDER BY created_at`
+    - Notes query: `SELECT n.body, n.author_username, n.created_at FROM notes n JOIN discussions d ON n.discussion_id = d.id WHERE d.{id_col} = ?1 AND n.is_system = 0 AND (?2 IS NULL OR n.created_at >= ?2) ORDER BY n.created_at`
+    - The `{id_col}` is either `issue_id` or `merge_request_id` based on entity_type
+    - Pass `params.since` (Option<i64>) as the `?2` parameter — NULL means no filter
+    - Use `crate::core::time::ms_to_iso()` for timestamp conversion in output
+    - Truncate context_note to 500 chars using `crate::cli::render::truncate()` or a local helper
+
+- [ ] **Task 3:** Implement open threads, activity summary, and cross-references
+  - **Implements:** UJ-1
+  - **Files:** `src/cli/commands/explain.rs`
+  - **Depends on:** Task 1
+  - **Test-first:**
+    1. Write `test_explain_open_threads`: insert 2 discussions (1 with resolved=0 resolvable=1, 1 with resolved=1 resolvable=1), assert only unresolved appears in open_threads
+    2. Write `test_explain_activity_counts`: insert 3 state events + 2 label events + 10 non-system notes, assert activity.state_changes=3, label_changes=2, notes=10
+    3. Write `test_explain_no_notes`: insert issue with zero notes and zero events, assert empty key_decisions, empty open_threads, activity all zeros, description_excerpt = "(no description)" if description is NULL
+    4. Run tests — all must FAIL (red)
+    5. Implement:
+       - `fetch_open_threads()`: query discussions WHERE resolvable=1 AND resolved=0, fetch first note author + note count per thread
+       - `build_activity_summary()`: count state events, label events, non-system notes, find min/max timestamps
+       - `fetch_related_entities()`: query entity_references in both directions (source and target)
+       - Description excerpt: first 500 chars of description, or "(no description)" if NULL
+    6. Run tests — all must PASS (green)
+  - **Acceptance:** All 3 tests pass. Open threads correctly filtered. Activity counts accurate. Empty entity handled gracefully.
+  - **Implementation notes:**
+    - Open threads query: `SELECT d.gitlab_discussion_id, d.first_note_at, d.last_note_at FROM discussions d WHERE d.{id_col} = ?1 AND d.resolvable = 1 AND d.resolved = 0 ORDER BY d.last_note_at DESC`
+    - For first note author: `SELECT author_username FROM notes WHERE discussion_id = ?1 ORDER BY created_at ASC LIMIT 1`
+    - For note count: `SELECT COUNT(*) FROM notes WHERE discussion_id = ?1 AND is_system = 0`
+    - Cross-references: both outgoing and incoming from entity_references table
+    - For closing MRs, reuse the query pattern from show/issue.rs `get_closing_mrs()`
+
+- [ ] **Task 4:** Wire timeline excerpt using existing pipeline
+  - **Implements:** UJ-1
+  - **Files:** `src/cli/commands/explain.rs`
+  - **Depends on:** Task 1
+  - **Test-first:**
+    1. Write `test_explain_timeline_excerpt`: insert issue + state events + notes, call run_explain() with `no_timeline: false`, assert timeline_excerpt is Some and non-empty and capped at 20 events
+    2. Write `test_explain_no_timeline_flag`: call run_explain() with `no_timeline: true`, assert timeline_excerpt is None
+    3. Run tests — both must FAIL (red)
+    4. Implement: when `!params.no_timeline` and `--sections` includes "timeline" (or is None), call `seed_timeline_direct()` with entity type + IID, then `collect_events()`, convert first 20 TimelineEvents into TimelineEventSummary structs. Otherwise set timeline_excerpt to None.
+    5. Run tests — both must PASS (green)
+  - **Acceptance:** Timeline excerpt present with max 20 events when enabled. Skipped entirely when `--no-timeline`. Uses existing timeline pipeline (no reimplementation).
+  - **Implementation notes:**
+    - Import: `use crate::timeline::seed::seed_timeline_direct;` and `use crate::timeline::collect::collect_events;`
+    - `seed_timeline_direct()` takes `(conn, entity_type, iid, project_id)` — verify exact signature before implementing
+    - `collect_events()` returns `Vec<TimelineEvent>` — map to simplified `TimelineEventSummary` (timestamp, event_type string, actor, summary)
+    - Timeline pipeline uses `EntityRef` struct from `crate::timeline::types` — needs entity's local DB id and project_path
+    - Cap at 20 events: `events.truncate(20)` after collection
+    - `--no-timeline` takes precedence over `--sections timeline` (if both specified, skip timeline)
+
+### Phase 3: Output Rendering
+
+- [ ] **Task 5:** Robot mode JSON output and human-readable rendering
+  - **Implements:** UJ-1, UJ-2
+  - **Files:** `src/cli/commands/explain.rs`, `src/app/robot_docs.rs`
+  - **Depends on:** Task 1, 2, 3, 4
+  - **Test-first:**
+    1. Write `test_explain_robot_output_shape`: call run_explain() with all sections, serialize to JSON, assert all 7 top-level keys present
+    2. Write `test_explain_sections_filter_robot`: call run_explain() with `sections: Some(vec!["key_decisions", "activity"])`, serialize, assert only `entity` + `key_decisions` + `activity` keys present (entity always included), assert `description_excerpt`, `open_threads`, `related`, `timeline_excerpt` are absent
+    3. Run tests — both must FAIL (red)
+    4. Implement:
+       - Robot mode: `print_explain_json()` wrapping ExplainResult in `{"ok": true, "data": ..., "meta": {...}}` envelope. `#[serde(skip_serializing_if = "Option::is_none")]` on optional sections handles filtering automatically.
+       - Human mode: `print_explain()` with section headers, colored output, indented key decisions, truncated descriptions. Check `params.sections` before rendering each section.
+       - Register in robot-docs manifest (include `--sections`, `--no-timeline`, `--max-decisions`, `--since` flags)
+    5. Run tests — both must PASS (green)
+  - **Acceptance:** Robot JSON matches schema. Section filtering works in both robot and human mode. Command appears in `lore robot-docs`.
+  - **Implementation notes:**
+    - Robot envelope: use `serde_json::json!()` with `RobotMeta` from `crate::cli::robot`
+    - Human rendering: use `Theme::bold()`, `Icons`, `render::truncate()` from `crate::cli::render`
+    - Follow timeline.rs rendering pattern: header with entity info -> separator line -> sections
+    - Register in robot_docs.rs following the existing pattern for other commands
+    - Section filtering: the `run_explain()` function should already return None for unselected sections. The serializer skips them. Human renderer checks `is_some()` before rendering.
+
+---
+
+## Corrections from Original Bead
+
+The bead (bd-9lbr) was created before a codebase rearchitecture. Key corrections:
+
+1. **`src/core/events_db.rs` does not exist** — Event storage is in `src/ingestion/storage/events.rs` (insert only). Event queries are inline in `timeline/collect.rs`. Explain needs its own inline queries.
+
+2. **`ResourceStateEvent` / `ResourceLabelEvent` structs don't exist** — The timeline queries raw rows directly. Explain should define lightweight local structs or use tuples.
+
+3. **`run_show_issue()` / `run_show_mr()` are private** — They live in `include!()` files inside show/mod.rs. Cannot be imported. Copy the query patterns instead.
+
+4. **bd-2g50 blocker is CLOSED** — `IssueDetail` already has `closed_at`, `references_full`, `user_notes_count`, `confidential`. No blocker.
+
+5. **Clap registration pattern** — The bead shows args directly on the enum variant, which is correct for explain's simple args (matches Drift, Related pattern). No need for a separate ExplainArgs struct.
+
+6. **entity_references has no fetch query** — Only `insert_entity_reference()` and `count_references_for_source()` exist. Explain needs a new SELECT query (inline in explain.rs).
+
+---
+
+## Session Log
+
+### Session 1 — 2026-03-10
+- Read bead bd-9lbr thoroughly — exceptionally detailed but written before rearchitecture
+- Verified infrastructure: show/ (private functions, copy patterns), timeline/ (importable pipeline), events (inline SQL, no typed structs), xref (no fetch query), discussions (resolvable/resolved confirmed in migration 028)
+- Discovered bd-2g50 blocker is CLOSED — no dependency
+- Decided: two positional args (`lore explain issues N`) over single query syntax
+- Decided: formalize + gap-fill approach (bead is thorough, just needs updating)
+- Documented 6 corrections from original bead to current codebase state
+- Drafted complete spec with 5 tasks across 3 phases
+
+### Session 1b — 2026-03-10 (CLI UX Audit)
+- Audited full CLI surface (30+ commands) against explain's proposed UX
+- Identified 8 improvements, user selected 6 to incorporate:
+  1. **after_help examples block** — every other lore command has this, explain was missing it
+  2. **--sections flag** — robot token efficiency, skip unselected sections entirely
+  4. **Singular entity type tolerance** — accept `issue`/`mr` alongside `issues`/`mrs`
+  5. **--no-timeline flag** — skip heaviest section for faster execution
+  7. **--max-decisions N flag** — user control over key_decisions cap (default 10)
+  8. **--since flag** — time-scope events/notes for long-lived entities
+- Skipped: #3 (command aliases ex/narrative), #6 (#42/!99 shorthand)
+- Updated: Code Style, Boundaries, Architecture (ExplainParams + ExplainResult types, section filtering, time scoping, SQL queries), Success Criteria (+5 new), Testing Strategy (+5 new tests), all 5 Tasks
+- ExplainResult sections now `Option<T>` with `skip_serializing_if` for section filtering
+- All sections remain complete — spec is ready for implementation

src/app/dispatch.rs

@@ -0,0 +1,3 @@
+include!("errors.rs");
+include!("handlers.rs");
+include!("robot_docs.rs");

src/app/errors.rs

@@ -0,0 +1,486 @@
+#[derive(Serialize)]
+struct FallbackErrorOutput {
+    error: FallbackError,
+}
+
+#[derive(Serialize)]
+struct FallbackError {
+    code: String,
+    message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    suggestion: Option<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    actions: Vec<String>,
+}
+
+fn handle_error(e: Box<dyn std::error::Error>, robot_mode: bool) -> ! {
+    if let Some(gi_error) = e.downcast_ref::<LoreError>() {
+        if robot_mode {
+            let output = RobotErrorOutput::from(gi_error);
+            eprintln!(
+                "{}",
+                serde_json::to_string(&output).unwrap_or_else(|_| {
+                    let fallback = FallbackErrorOutput {
+                        error: FallbackError {
+                            code: "INTERNAL_ERROR".to_string(),
+                            message: gi_error.to_string(),
+                            suggestion: None,
+                            actions: Vec::new(),
+                        },
+                    };
+                    serde_json::to_string(&fallback)
+                        .unwrap_or_else(|_| r#"{"error":{"code":"INTERNAL_ERROR","message":"Serialization failed"}}"#.to_string())
+                })
+            );
+            std::process::exit(gi_error.exit_code());
+        } else {
+            eprintln!();
+            eprintln!(
+                "  {}  {}",
+                Theme::error().render(Icons::error()),
+                Theme::error().bold().render(&gi_error.to_string())
+            );
+            if let Some(suggestion) = gi_error.suggestion() {
+                eprintln!();
+                eprintln!("     {suggestion}");
+            }
+            let actions = gi_error.actions();
+            if !actions.is_empty() {
+                eprintln!();
+                for action in &actions {
+                    eprintln!(
+                        "     {} {}",
+                        Theme::dim().render("\u{2192}"),
+                        Theme::bold().render(action)
+                    );
+                }
+            }
+            eprintln!();
+            std::process::exit(gi_error.exit_code());
+        }
+    }
+
+    if robot_mode {
+        let output = FallbackErrorOutput {
+            error: FallbackError {
+                code: "INTERNAL_ERROR".to_string(),
+                message: e.to_string(),
+                suggestion: None,
+                actions: Vec::new(),
+            },
+        };
+        eprintln!(
+            "{}",
+            serde_json::to_string(&output).unwrap_or_else(|_| {
+                r#"{"error":{"code":"INTERNAL_ERROR","message":"Serialization failed"}}"#
+                    .to_string()
+            })
+        );
+    } else {
+        eprintln!();
+        eprintln!(
+            "  {}  {}",
+            Theme::error().render(Icons::error()),
+            Theme::error().bold().render(&e.to_string())
+        );
+        eprintln!();
+    }
+    std::process::exit(1);
+}
+
+/// Emit stderr warnings for any corrections applied during Phase 1.5.
+fn emit_correction_warnings(result: &CorrectionResult, robot_mode: bool) {
+    if robot_mode {
+        #[derive(Serialize)]
+        struct CorrectionWarning<'a> {
+            warning: CorrectionWarningInner<'a>,
+        }
+        #[derive(Serialize)]
+        struct CorrectionWarningInner<'a> {
+            r#type: &'static str,
+            corrections: &'a [autocorrect::Correction],
+            teaching: Vec<String>,
+        }
+
+        let teaching: Vec<String> = result
+            .corrections
+            .iter()
+            .map(autocorrect::format_teaching_note)
+            .collect();
+
+        let warning = CorrectionWarning {
+            warning: CorrectionWarningInner {
+                r#type: "ARG_CORRECTED",
+                corrections: &result.corrections,
+                teaching,
+            },
+        };
+        if let Ok(json) = serde_json::to_string(&warning) {
+            eprintln!("{json}");
+        }
+    } else {
+        for c in &result.corrections {
+            eprintln!(
+                "{} {}",
+                Theme::warning().render("Auto-corrected:"),
+                autocorrect::format_teaching_note(c)
+            );
+        }
+    }
+}
+
+/// Phase 1 & 4: Handle clap parsing errors with structured JSON output in robot mode.
+/// Also includes fuzzy command matching and flag-level suggestions.
+fn handle_clap_error(e: clap::Error, robot_mode: bool, corrections: &CorrectionResult) -> ! {
+    use clap::error::ErrorKind;
+
+    // Always let clap handle --help and --version normally (print and exit 0).
+    // These are intentional user actions, not errors, even when stdout is redirected.
+    if matches!(e.kind(), ErrorKind::DisplayHelp | ErrorKind::DisplayVersion) {
+        e.exit()
+    }
+
+    if robot_mode {
+        let error_code = map_clap_error_kind(e.kind());
+        let full_msg = e.to_string();
+        let message = full_msg
+            .lines()
+            .take(3)
+            .collect::<Vec<_>>()
+            .join("; ")
+            .trim()
+            .to_string();
+
+        let (suggestion, correction, valid_values) = match e.kind() {
+            // Phase 4: Suggest similar command for unknown subcommands
+            ErrorKind::InvalidSubcommand => {
+                let suggestion = if let Some(invalid_cmd) = extract_invalid_subcommand(&e) {
+                    suggest_similar_command(&invalid_cmd)
+                } else {
+                    "Run 'lore robot-docs' for valid commands".to_string()
+                };
+                (suggestion, None, None)
+            }
+            // Flag-level fuzzy matching for unknown flags
+            ErrorKind::UnknownArgument => {
+                let invalid_flag = extract_invalid_flag(&e);
+                let similar = invalid_flag
+                    .as_deref()
+                    .and_then(|flag| autocorrect::suggest_similar_flag(flag, &corrections.args));
+                let suggestion = if let Some(ref s) = similar {
+                    format!("Did you mean '{s}'? Run 'lore robot-docs' for all flags")
+                } else {
+                    "Run 'lore robot-docs' for valid flags".to_string()
+                };
+                (suggestion, similar, None)
+            }
+            // Value-level suggestions for invalid enum values
+            ErrorKind::InvalidValue => {
+                let (flag, valid_vals) = extract_invalid_value_context(&e);
+                let suggestion = if let Some(vals) = &valid_vals {
+                    format!(
+                        "Valid values: {}. Run 'lore robot-docs' for details",
+                        vals.join(", ")
+                    )
+                } else if let Some(ref f) = flag {
+                    if let Some(vals) = autocorrect::valid_values_for_flag(f) {
+                        format!("Valid values for {f}: {}", vals.join(", "))
+                    } else {
+                        "Run 'lore robot-docs' for valid values".to_string()
+                    }
+                } else {
+                    "Run 'lore robot-docs' for valid values".to_string()
+                };
+                let vals_vec = valid_vals.or_else(|| {
+                    flag.as_deref()
+                        .and_then(autocorrect::valid_values_for_flag)
+                        .map(|v| v.iter().map(|s| (*s).to_string()).collect())
+                });
+                (suggestion, None, vals_vec)
+            }
+            ErrorKind::MissingRequiredArgument => {
+                let suggestion = format!(
+                    "A required argument is missing. {}",
+                    if let Some(subcmd) = extract_subcommand_from_context(&e) {
+                        format!(
+                            "Example: {}. Run 'lore {subcmd} --help' for required arguments",
+                            command_example(&subcmd)
+                        )
+                    } else {
+                        "Run 'lore robot-docs' for command reference".to_string()
+                    }
+                );
+                (suggestion, None, None)
+            }
+            ErrorKind::MissingSubcommand => {
+                let suggestion =
+                    "No command specified. Common commands: issues, mrs, search, sync, \
+                     timeline, who, me. Run 'lore robot-docs' for the full list"
+                        .to_string();
+                (suggestion, None, None)
+            }
+            ErrorKind::TooFewValues | ErrorKind::TooManyValues => {
+                let suggestion = if let Some(subcmd) = extract_subcommand_from_context(&e) {
+                    format!(
+                        "Example: {}. Run 'lore {subcmd} --help' for usage",
+                        command_example(&subcmd)
+                    )
+                } else {
+                    "Run 'lore robot-docs' for command reference".to_string()
+                };
+                (suggestion, None, None)
+            }
+            _ => (
+                "Run 'lore robot-docs' for valid commands".to_string(),
+                None,
+                None,
+            ),
+        };
+
+        let output = RobotErrorWithSuggestion {
+            error: RobotErrorSuggestionData {
+                code: error_code.to_string(),
+                message,
+                suggestion,
+                correction,
+                valid_values,
+            },
+        };
+        eprintln!(
+            "{}",
+            serde_json::to_string(&output).unwrap_or_else(|_| {
+                r#"{"error":{"code":"PARSE_ERROR","message":"Parse error"}}"#.to_string()
+            })
+        );
+        std::process::exit(2);
+    } else {
+        e.exit()
+    }
+}
+
+/// Map clap ErrorKind to semantic error codes
+fn map_clap_error_kind(kind: clap::error::ErrorKind) -> &'static str {
+    use clap::error::ErrorKind;
+    match kind {
+        ErrorKind::InvalidSubcommand => "UNKNOWN_COMMAND",
+        ErrorKind::UnknownArgument => "UNKNOWN_FLAG",
+        ErrorKind::MissingRequiredArgument => "MISSING_REQUIRED",
+        ErrorKind::InvalidValue => "INVALID_VALUE",
+        ErrorKind::ValueValidation => "INVALID_VALUE",
+        ErrorKind::TooManyValues => "TOO_MANY_VALUES",
+        ErrorKind::TooFewValues => "TOO_FEW_VALUES",
+        ErrorKind::ArgumentConflict => "ARGUMENT_CONFLICT",
+        ErrorKind::MissingSubcommand => "MISSING_COMMAND",
+        ErrorKind::DisplayHelp | ErrorKind::DisplayVersion => "HELP_REQUESTED",
+        _ => "PARSE_ERROR",
+    }
+}
+
+/// Extract the invalid subcommand from a clap error (Phase 4)
+fn extract_invalid_subcommand(e: &clap::Error) -> Option<String> {
+    // Parse the error message to find the invalid subcommand
+    // Format is typically: "error: unrecognized subcommand 'foo'"
+    let msg = e.to_string();
+    if let Some(start) = msg.find('\'')
+        && let Some(end) = msg[start + 1..].find('\'')
+    {
+        return Some(msg[start + 1..start + 1 + end].to_string());
+    }
+    None
+}
+
+/// Extract the invalid flag from a clap UnknownArgument error.
+/// Format is typically: "error: unexpected argument '--xyzzy' found"
+fn extract_invalid_flag(e: &clap::Error) -> Option<String> {
+    let msg = e.to_string();
+    if let Some(start) = msg.find('\'')
+        && let Some(end) = msg[start + 1..].find('\'')
+    {
+        let value = &msg[start + 1..start + 1 + end];
+        if value.starts_with('-') {
+            return Some(value.to_string());
+        }
+    }
+    None
+}
+
+/// Extract flag name and valid values from a clap InvalidValue error.
+/// Returns (flag_name, valid_values_if_listed_in_error).
+fn extract_invalid_value_context(e: &clap::Error) -> (Option<String>, Option<Vec<String>>) {
+    let msg = e.to_string();
+
+    // Try to find the flag name from "[possible values: ...]" pattern or from the arg info
+    // Clap format: "error: invalid value 'opend' for '--state <STATE>'"
+    let flag = if let Some(for_pos) = msg.find("for '") {
+        let after_for = &msg[for_pos + 5..];
+        if let Some(end) = after_for.find('\'') {
+            let raw = &after_for[..end];
+            // Strip angle-bracket value placeholder: "--state <STATE>" -> "--state"
+            Some(raw.split_whitespace().next().unwrap_or(raw).to_string())
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    // Try to extract possible values from the error message
+    // Clap format: "[possible values: opened, closed, merged, locked, all]"
+    let valid_values = if let Some(pv_pos) = msg.find("[possible values: ") {
+        let after_pv = &msg[pv_pos + 18..];
+        after_pv.find(']').map(|end| {
+            after_pv[..end]
+                .split(", ")
+                .map(|s| s.trim().to_string())
+                .collect()
+        })
+    } else {
+        // Fall back to our static registry
+        flag.as_deref()
+            .and_then(autocorrect::valid_values_for_flag)
+            .map(|v| v.iter().map(|s| (*s).to_string()).collect())
+    };
+
+    (flag, valid_values)
+}
+
+/// Extract the subcommand context from a clap error for better suggestions.
+/// Looks at the error message to find which command was being invoked.
+fn extract_subcommand_from_context(e: &clap::Error) -> Option<String> {
+    let msg = e.to_string();
+
+    let known = [
+        "issues",
+        "mrs",
+        "notes",
+        "search",
+        "sync",
+        "ingest",
+        "count",
+        "status",
+        "auth",
+        "doctor",
+        "stats",
+        "timeline",
+        "who",
+        "me",
+        "drift",
+        "related",
+        "trace",
+        "file-history",
+        "generate-docs",
+        "embed",
+        "token",
+        "cron",
+        "init",
+        "migrate",
+    ];
+    for cmd in known {
+        if msg.contains(&format!("lore {cmd}")) || msg.contains(&format!("'{cmd}'")) {
+            return Some(cmd.to_string());
+        }
+    }
+    None
+}
+
+/// Phase 4: Suggest similar command using fuzzy matching
+fn suggest_similar_command(invalid: &str) -> String {
+    // Primary commands + common aliases for fuzzy matching
+    const VALID_COMMANDS: &[(&str, &str)] = &[
+        ("issues", "issues"),
+        ("issue", "issues"),
+        ("mrs", "mrs"),
+        ("mr", "mrs"),
+        ("merge-requests", "mrs"),
+        ("search", "search"),
+        ("find", "search"),
+        ("query", "search"),
+        ("sync", "sync"),
+        ("ingest", "ingest"),
+        ("count", "count"),
+        ("status", "status"),
+        ("auth", "auth"),
+        ("doctor", "doctor"),
+        ("version", "version"),
+        ("init", "init"),
+        ("stats", "stats"),
+        ("stat", "stats"),
+        ("generate-docs", "generate-docs"),
+        ("embed", "embed"),
+        ("migrate", "migrate"),
+        ("health", "health"),
+        ("robot-docs", "robot-docs"),
+        ("completions", "completions"),
+        ("timeline", "timeline"),
+        ("who", "who"),
+        ("notes", "notes"),
+        ("note", "notes"),
+        ("drift", "drift"),
+        ("file-history", "file-history"),
+        ("trace", "trace"),
+        ("related", "related"),
+        ("me", "me"),
+        ("token", "token"),
+        ("cron", "cron"),
+        // Hidden but may be known to agents
+        ("list", "list"),
+        ("show", "show"),
+        ("reset", "reset"),
+        ("backup", "backup"),
+    ];
+
+    let invalid_lower = invalid.to_lowercase();
+
+    // Find the best match using Jaro-Winkler similarity
+    let best_match = VALID_COMMANDS
+        .iter()
+        .map(|(alias, canonical)| (*canonical, jaro_winkler(&invalid_lower, alias)))
+        .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal));
+
+    if let Some((cmd, score)) = best_match
+        && score > 0.7
+    {
+        let example = command_example(cmd);
+        return format!(
+            "Did you mean 'lore {cmd}'? Example: {example}. Run 'lore robot-docs' for all commands"
+        );
+    }
+
+    "Run 'lore robot-docs' for valid commands. Common: issues, mrs, search, sync, timeline, who"
+        .to_string()
+}
+
+/// Return a contextual usage example for a command.
+fn command_example(cmd: &str) -> &'static str {
+    match cmd {
+        "issues" => "lore --robot issues -n 10",
+        "mrs" => "lore --robot mrs -n 10",
+        "search" => "lore --robot search \"auth bug\"",
+        "sync" => "lore --robot sync",
+        "ingest" => "lore --robot ingest issues",
+        "notes" => "lore --robot notes --for-issue 123",
+        "count" => "lore --robot count issues",
+        "status" => "lore --robot status",
+        "stats" => "lore --robot stats",
+        "timeline" => "lore --robot timeline \"auth flow\"",
+        "who" => "lore --robot who --path src/",
+        "health" => "lore --robot health",
+        "generate-docs" => "lore --robot generate-docs",
+        "embed" => "lore --robot embed",
+        "robot-docs" => "lore robot-docs",
+        "trace" => "lore --robot trace src/main.rs",
+        "init" => "lore init",
+        "related" => "lore --robot related issues 42 -n 5",
+        "me" => "lore --robot me",
+        "drift" => "lore --robot drift issues 42",
+        "file-history" => "lore --robot file-history src/main.rs",
+        "token" => "lore --robot token show",
+        "cron" => "lore --robot cron status",
+        "auth" => "lore --robot auth",
+        "doctor" => "lore --robot doctor",
+        "migrate" => "lore --robot migrate",
+        "completions" => "lore completions bash",
+        _ => "lore --robot <command>",
+    }
+}
+

src/app/robot_docs.rs

@@ -0,0 +1,795 @@
+#[derive(Serialize)]
+struct RobotDocsOutput {
+    ok: bool,
+    data: RobotDocsData,
+}
+
+#[derive(Serialize)]
+struct RobotDocsData {
+    name: String,
+    version: String,
+    description: String,
+    activation: RobotDocsActivation,
+    quick_start: serde_json::Value,
+    commands: serde_json::Value,
+    /// Deprecated command aliases (old -> new)
+    aliases: serde_json::Value,
+    /// Pre-clap error tolerance: what the CLI auto-corrects
+    error_tolerance: serde_json::Value,
+    exit_codes: serde_json::Value,
+    /// Error codes emitted by clap parse failures
+    clap_error_codes: serde_json::Value,
+    error_format: String,
+    workflows: serde_json::Value,
+    config_notes: serde_json::Value,
+}
+
+#[derive(Serialize)]
+struct RobotDocsActivation {
+    flags: Vec<String>,
+    env: String,
+    auto: String,
+}
+
+fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::error::Error>> {
+    let version = env!("CARGO_PKG_VERSION").to_string();
+
+    let commands = serde_json::json!({
+        "init": {
+            "description": "Initialize configuration and database",
+            "flags": ["--force", "--non-interactive", "--gitlab-url <URL>", "--token-env-var <VAR>", "--projects <paths>", "--default-project <path>"],
+            "robot_flags": ["--gitlab-url", "--token-env-var", "--projects", "--default-project"],
+            "example": "lore --robot init --gitlab-url https://gitlab.com --token-env-var GITLAB_TOKEN --projects group/project,other/repo --default-project group/project",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"config_path": "string", "data_dir": "string", "user": {"username": "string", "name": "string"}, "projects": "[{path:string, name:string}]", "default_project": "string?"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "health": {
+            "description": "Quick pre-flight check: config, database, schema version",
+            "flags": [],
+            "example": "lore --robot health",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"healthy": "bool", "config_found": "bool", "db_found": "bool", "schema_current": "bool", "schema_version": "int"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "auth": {
+            "description": "Verify GitLab authentication",
+            "flags": [],
+            "example": "lore --robot auth",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"authenticated": "bool", "username": "string", "name": "string", "gitlab_url": "string"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "doctor": {
+            "description": "Full environment health check (config, auth, DB, Ollama)",
+            "flags": [],
+            "example": "lore --robot doctor",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"success": "bool", "checks": "{config:object, auth:object, database:object, ollama:object}"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "ingest": {
+            "description": "Sync data from GitLab",
+            "flags": ["--project <path>", "--force", "--no-force", "--full", "--no-full", "--dry-run", "--no-dry-run", "<entity: issues|mrs>"],
+            "example": "lore --robot ingest issues --project group/repo",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"resource_type": "string", "projects_synced": "int", "issues_fetched?": "int", "mrs_fetched?": "int", "upserted": "int", "labels_created": "int", "discussions_fetched": "int", "notes_upserted": "int"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "sync": {
+            "description": "Full sync pipeline: ingest -> generate-docs -> embed. Supports surgical per-IID mode.",
+            "flags": ["--full", "--no-full", "--force", "--no-force", "--no-embed", "--no-docs", "--no-events", "--no-file-changes", "--no-status", "--dry-run", "--no-dry-run", "-t/--timings", "--lock", "--issue <IID>", "--mr <IID>", "-p/--project <path>", "--preflight-only"],
+            "example": "lore --robot sync",
+            "surgical_mode": {
+                "description": "Sync specific issues or MRs by IID. Runs a scoped pipeline: preflight -> TOCTOU check -> ingest -> dependents -> docs -> embed.",
+                "flags": ["--issue <IID> (repeatable)", "--mr <IID> (repeatable)", "-p/--project <path> (required)", "--preflight-only"],
+                "examples": [
+                    "lore --robot sync --issue 7 -p group/project",
+                    "lore --robot sync --issue 7 --issue 42 --mr 10 -p group/project",
+                    "lore --robot sync --issue 7 -p group/project --preflight-only"
+                ],
+                "constraints": ["--issue/--mr requires -p/--project (or defaultProject in config)", "--full and --issue/--mr are incompatible", "--preflight-only requires --issue or --mr", "Max 100 total targets"],
+                "entity_result_outcomes": ["synced", "skipped_stale", "not_found", "preflight_failed", "error"]
+            },
+            "response_schema": {
+                "normal": {
+                    "ok": "bool",
+                    "data": {"issues_updated": "int", "mrs_updated": "int", "documents_regenerated": "int", "documents_embedded": "int", "resource_events_synced": "int", "resource_events_failed": "int"},
+                    "meta": {"elapsed_ms": "int", "stages?": "[{name:string, elapsed_ms:int, items_processed:int}]"}
+                },
+                "surgical": {
+                    "ok": "bool",
+                    "data": {"surgical_mode": "true", "surgical_iids": "{issues:[int], merge_requests:[int]}", "entity_results": "[{entity_type:string, iid:int, outcome:string, error?:string, toctou_reason?:string}]", "preflight_only?": "bool", "issues_updated": "int", "mrs_updated": "int", "documents_regenerated": "int", "documents_embedded": "int", "discussions_fetched": "int"},
+                    "meta": {"elapsed_ms": "int"}
+                }
+            }
+        },
+        "issues": {
+            "description": "List issues, or view detail with <IID>",
+            "flags": ["<IID>", "-n/--limit", "--fields <list>", "-s/--state", "--status <name>", "-p/--project", "-a/--author", "-A/--assignee", "-l/--label", "-m/--milestone", "--since", "--due-before", "--has-due", "--no-has-due", "--sort", "--asc", "--no-asc", "-o/--open", "--no-open"],
+            "example": "lore --robot issues --state opened --limit 10",
+            "notes": {
+                "status_filter": "--status filters by work item status NAME (case-insensitive). Valid values are in meta.available_statuses of any issues list response.",
+                "status_name": "status_name is the board column label (e.g. 'In review', 'Blocked'). This is the canonical status identifier for filtering."
+            },
+            "response_schema": {
+                "list": {
+                    "ok": "bool",
+                    "data": {"issues": "[{iid:int, title:string, state:string, author_username:string, labels:[string], assignees:[string], discussion_count:int, unresolved_count:int, created_at_iso:string, updated_at_iso:string, web_url:string?, project_path:string, status_name:string?}]", "total_count": "int", "showing": "int"},
+                    "meta": {"elapsed_ms": "int", "available_statuses": "[string] — all distinct status names in the database, for use with --status filter"}
+                },
+                "detail": {
+                    "ok": "bool",
+                    "data": "IssueDetail (full entity with description, discussions, notes, events)",
+                    "meta": {"elapsed_ms": "int"}
+                }
+            },
+            "example_output": {"list": {"ok":true,"data":{"issues":[{"iid":3864,"title":"Switch Health Card","state":"opened","status_name":"In progress","labels":["customer:BNSF"],"assignees":["teernisse"],"discussion_count":12,"updated_at_iso":"2026-02-12T..."}],"total_count":1,"showing":1},"meta":{"elapsed_ms":42}}},
+            "fields_presets": {"minimal": ["iid", "title", "state", "updated_at_iso"]}
+        },
+        "mrs": {
+            "description": "List merge requests, or view detail with <IID>",
+            "flags": ["<IID>", "-n/--limit", "--fields <list>", "-s/--state", "-p/--project", "-a/--author", "-A/--assignee", "-r/--reviewer", "-l/--label", "--since", "-d/--draft", "-D/--no-draft", "--target", "--source", "--sort", "--asc", "--no-asc", "-o/--open", "--no-open"],
+            "example": "lore --robot mrs --state opened",
+            "response_schema": {
+                "list": {
+                    "ok": "bool",
+                    "data": {"mrs": "[{iid:int, title:string, state:string, author_username:string, labels:[string], draft:bool, target_branch:string, source_branch:string, discussion_count:int, unresolved_count:int, created_at_iso:string, updated_at_iso:string, web_url:string?, project_path:string, reviewers:[string]}]", "total_count": "int", "showing": "int"},
+                    "meta": {"elapsed_ms": "int"}
+                },
+                "detail": {
+                    "ok": "bool",
+                    "data": "MrDetail (full entity with description, discussions, notes, events)",
+                    "meta": {"elapsed_ms": "int"}
+                }
+            },
+            "example_output": {"list": {"ok":true,"data":{"mrs":[{"iid":200,"title":"Add throw time chart","state":"opened","draft":false,"author_username":"teernisse","target_branch":"main","source_branch":"feat/throw-time","reviewers":["cseiber"],"discussion_count":5,"updated_at_iso":"2026-02-11T..."}],"total_count":1,"showing":1},"meta":{"elapsed_ms":38}}},
+            "fields_presets": {"minimal": ["iid", "title", "state", "updated_at_iso"]}
+        },
+        "search": {
+            "description": "Search indexed documents (lexical, hybrid, semantic)",
+            "flags": ["<QUERY>", "--mode", "--type", "--author", "-p/--project", "--label", "--path", "--since", "--updated-since", "-n/--limit", "--fields <list>", "--explain", "--no-explain", "--fts-mode"],
+            "example": "lore --robot search 'authentication bug' --mode hybrid --limit 10",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"results": "[{document_id:int, source_type:string, title:string, snippet:string, score:float, url:string?, author:string?, created_at:string?, updated_at:string?, project_path:string, labels:[string], paths:[string]}]", "total_results": "int", "query": "string", "mode": "string", "warnings": "[string]"},
+                "meta": {"elapsed_ms": "int"}
+            },
+            "example_output": {"ok":true,"data":{"query":"throw time","mode":"hybrid","total_results":3,"results":[{"document_id":42,"source_type":"issue","title":"Switch Health Card","score":0.92,"snippet":"...throw time data from BNSF...","project_path":"vs/typescript-code"}],"warnings":[]},"meta":{"elapsed_ms":85}},
+            "fields_presets": {"minimal": ["document_id", "title", "source_type", "score"]}
+        },
+        "count": {
+            "description": "Count entities in local database",
+            "flags": ["<entity: issues|mrs|discussions|notes|events>", "-f/--for <issue|mr>"],
+            "example": "lore --robot count issues",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"entity": "string", "count": "int", "system_excluded?": "int", "breakdown?": {"opened": "int", "closed": "int", "merged?": "int", "locked?": "int"}},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "stats": {
+            "description": "Show document and index statistics",
+            "flags": ["--check", "--no-check", "--repair", "--dry-run", "--no-dry-run"],
+            "example": "lore --robot stats",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"total_documents": "int", "indexed_documents": "int", "embedded_documents": "int", "stale_documents": "int", "integrity?": "object"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "status": {
+            "description": "Show sync state (cursors, last sync times)",
+            "flags": [],
+            "example": "lore --robot status",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"projects": "[{path:string, issues_cursor:string?, mrs_cursor:string?, last_sync:string?}]"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "generate-docs": {
+            "description": "Generate searchable documents from ingested data",
+            "flags": ["--full", "-p/--project <path>"],
+            "example": "lore --robot generate-docs --full",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"generated": "int", "updated": "int", "unchanged": "int", "deleted": "int"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "embed": {
+            "description": "Generate vector embeddings for documents via Ollama",
+            "flags": ["--full", "--no-full", "--retry-failed", "--no-retry-failed"],
+            "example": "lore --robot embed",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"embedded": "int", "skipped": "int", "failed": "int", "total_chunks": "int"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "migrate": {
+            "description": "Run pending database migrations",
+            "flags": [],
+            "example": "lore --robot migrate",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"before_version": "int", "after_version": "int", "migrated": "bool"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "version": {
+            "description": "Show version information",
+            "flags": [],
+            "example": "lore --robot version",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"version": "string", "git_hash?": "string"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "completions": {
+            "description": "Generate shell completions",
+            "flags": ["<shell: bash|zsh|fish|powershell>"],
+            "example": "lore completions bash > ~/.local/share/bash-completion/completions/lore"
+        },
+        "timeline": {
+            "description": "Chronological timeline of events matching a keyword query or entity reference",
+            "flags": ["<QUERY>", "-p/--project", "--since <duration>", "--depth <n>", "--no-mentions", "-n/--limit", "--fields <list>", "--max-seeds", "--max-entities", "--max-evidence"],
+            "query_syntax": {
+                "search": "Any text -> hybrid search seeding (FTS5 + vector)",
+                "entity_direct": "issue:N, i:N, mr:N, m:N -> direct entity seeding (no search, no Ollama)"
+            },
+            "example": "lore --robot timeline issue:42",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"entities": "[{type:string, iid:int, title:string, project_path:string}]", "events": "[{timestamp:string, type:string, entity_type:string, entity_iid:int, detail:string}]", "total_events": "int"},
+                "meta": {"elapsed_ms": "int", "search_mode": "string (hybrid|lexical|direct)"}
+            },
+            "fields_presets": {"minimal": ["timestamp", "type", "entity_iid", "detail"]}
+        },
+        "who": {
+            "description": "People intelligence: experts, workload, active discussions, overlap, review patterns",
+            "flags": ["<target>", "--path <path>", "--active", "--overlap <path>", "--reviews", "--since <duration>", "-p/--project", "-n/--limit", "--fields <list>", "--detail", "--no-detail", "--as-of <date>", "--explain-score", "--include-bots", "--include-closed", "--all-history"],
+            "modes": {
+                "expert": "lore who <file-path> -- Who knows about this area? (also: --path for root files)",
+                "workload": "lore who <username> -- What is someone working on?",
+                "reviews": "lore who <username> --reviews -- Review pattern analysis",
+                "active": "lore who --active -- Active unresolved discussions",
+                "overlap": "lore who --overlap <path> -- Who else is touching these files?"
+            },
+            "example": "lore --robot who src/features/auth/",
+            "response_schema": {
+                "ok": "bool",
+                "data": {
+                    "mode": "string",
+                    "input": {"target": "string|null", "path": "string|null", "project": "string|null", "since": "string|null", "limit": "int"},
+                    "resolved_input": {"mode": "string", "project_id": "int|null", "project_path": "string|null", "since_ms": "int", "since_iso": "string", "since_mode": "string (default|explicit|none)", "limit": "int"},
+                    "...": "mode-specific fields"
+                },
+                "meta": {"elapsed_ms": "int"}
+            },
+            "example_output": {"expert": {"ok":true,"data":{"mode":"expert","result":{"experts":[{"username":"teernisse","score":42,"note_count":15,"diff_note_count":8}]}},"meta":{"elapsed_ms":65}}},
+            "fields_presets": {
+                "expert_minimal": ["username", "score"],
+                "workload_minimal": ["entity_type", "iid", "title", "state"],
+                "active_minimal": ["entity_type", "iid", "title", "participants"]
+            }
+        },
+        "trace": {
+            "description": "Trace why code was introduced: file -> MR -> issue -> discussion. Follows rename chains by default.",
+            "flags": ["<path>", "-p/--project <path>", "--discussions", "--no-follow-renames", "-n/--limit <N>"],
+            "example": "lore --robot trace src/main.rs -p group/repo",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"path": "string", "resolved_paths": "[string]", "trace_chains": "[{mr_iid:int, mr_title:string, mr_state:string, mr_author:string, change_type:string, merged_at_iso:string?, updated_at_iso:string, web_url:string?, issues:[{iid:int, title:string, state:string, reference_type:string, web_url:string?}], discussions:[{discussion_id:string, mr_iid:int, author_username:string, body_snippet:string, path:string, created_at_iso:string}]}]"},
+                "meta": {"tier": "string (api_only)", "line_requested": "int?", "elapsed_ms": "int", "total_chains": "int", "renames_followed": "bool"}
+            }
+        },
+        "file-history": {
+            "description": "Show MRs that touched a file, with rename chain resolution and optional DiffNote discussions",
+            "flags": ["<path>", "-p/--project <path>", "--discussions", "--no-follow-renames", "--merged", "-n/--limit <N>"],
+            "example": "lore --robot file-history src/main.rs -p group/repo",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"path": "string", "rename_chain": "[string]?", "merge_requests": "[{iid:int, title:string, state:string, author_username:string, change_type:string, merged_at_iso:string?, updated_at_iso:string, merge_commit_sha:string?, web_url:string?}]", "discussions": "[{discussion_id:string, author_username:string, body_snippet:string, path:string, created_at_iso:string}]?"},
+                "meta": {"elapsed_ms": "int", "total_mrs": "int", "renames_followed": "bool", "paths_searched": "int"}
+            }
+        },
+        "drift": {
+            "description": "Detect discussion divergence from original issue intent",
+            "flags": ["<entity_type: issues>", "<IID>", "--threshold <0.0-1.0>", "-p/--project <path>"],
+            "example": "lore --robot drift issues 42 --threshold 0.4",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"entity_type": "string", "iid": "int", "title": "string", "threshold": "float", "divergent_discussions": "[{discussion_id:string, similarity:float, snippet:string}]"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "explain": {
+            "description": "Auto-generate a structured narrative of an issue or MR",
+            "flags": ["<entity_type: issues|mrs>", "<IID>", "-p/--project <path>", "--sections <comma-list>", "--no-timeline", "--max-decisions <N>", "--since <period>"],
+            "valid_sections": ["entity", "description", "key_decisions", "activity", "open_threads", "related", "timeline"],
+            "example": "lore --robot explain issues 42 --sections key_decisions,activity --since 30d",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"entity": "{type:string, iid:int, title:string, state:string, author:string, assignees:[string], labels:[string], created_at:string, updated_at:string, url:string?, status_name:string?}", "description_excerpt": "string?", "key_decisions": "[{timestamp:string, actor:string, action:string, context_note:string}]?", "activity": "{state_changes:int, label_changes:int, notes:int, first_event:string?, last_event:string?}?", "open_threads": "[{discussion_id:string, started_by:string, started_at:string, note_count:int, last_note_at:string}]?", "related": "{closing_mrs:[{iid:int, title:string, state:string, web_url:string?}], related_issues:[{entity_type:string, iid:int, title:string?, reference_type:string}]}?", "timeline_excerpt": "[{timestamp:string, event_type:string, actor:string?, summary:string}]?"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "notes": {
+            "description": "List notes from discussions with rich filtering",
+            "flags": ["--limit/-n <N>", "--author/-a <username>", "--note-type <type>", "--contains <text>", "--for-issue <iid>", "--for-mr <iid>", "-p/--project <path>", "--since <period>", "--until <period>", "--path <filepath>", "--resolution <any|unresolved|resolved>", "--sort <created|updated>", "--asc", "--include-system", "--note-id <id>", "--gitlab-note-id <id>", "--discussion-id <id>", "--fields <list|minimal>", "--open"],
+            "robot_flags": ["--format json", "--fields minimal"],
+            "example": "lore --robot notes --author jdefting --since 1y --format json --fields minimal",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"notes": "[NoteListRowJson]", "total_count": "int", "showing": "int"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "cron": {
+            "description": "Manage cron-based automatic syncing (Unix only)",
+            "subcommands": {
+                "install": {"flags": ["--interval <minutes>"], "default_interval": 8},
+                "uninstall": {"flags": []},
+                "status": {"flags": []}
+            },
+            "example": "lore --robot cron status",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"action": "string (install|uninstall|status)", "installed?": "bool", "interval_minutes?": "int", "entry?": "string", "log_path?": "string", "replaced?": "bool", "was_installed?": "bool", "last_run_iso?": "string"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "token": {
+            "description": "Manage stored GitLab token",
+            "subcommands": {
+                "set": {"flags": ["--token <value>"], "note": "Reads from stdin if --token omitted in non-interactive mode"},
+                "show": {"flags": ["--unmask"]}
+            },
+            "example": "lore --robot token show",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"action": "string (set|show)", "token_masked?": "string", "token?": "string", "valid?": "bool", "username?": "string"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "me": {
+            "description": "Personal work dashboard: open issues, authored/reviewing MRs, @mentioned-in items, activity feed, and cursor-based since-last-check inbox with computed attention states",
+            "flags": ["--issues", "--mrs", "--mentions", "--activity", "--since <period>", "-p/--project <path>", "--all", "--user <username>", "--fields <list|minimal>", "--reset-cursor"],
+            "example": "lore --robot me",
+            "response_schema": {
+                "ok": "bool",
+                "data": {
+                    "username": "string",
+                    "since_iso": "string?",
+                    "summary": {"project_count": "int", "open_issue_count": "int", "authored_mr_count": "int", "reviewing_mr_count": "int", "mentioned_in_count": "int", "needs_attention_count": "int"},
+                    "since_last_check": "{cursor_iso:string, total_event_count:int, groups:[{entity_type:string, entity_iid:int, entity_title:string, project:string, events:[{timestamp_iso:string, event_type:string, actor:string?, summary:string, body_preview:string?}]}]}?",
+                    "open_issues": "[{project:string, iid:int, title:string, state:string, attention_state:string, attention_reason:string, status_name:string?, labels:[string], updated_at_iso:string, web_url:string?}]",
+                    "open_mrs_authored": "[{project:string, iid:int, title:string, state:string, attention_state:string, attention_reason:string, draft:bool, detailed_merge_status:string?, author_username:string?, labels:[string], updated_at_iso:string, web_url:string?}]",
+                    "reviewing_mrs": "[same as open_mrs_authored]",
+                    "mentioned_in": "[{entity_type:string, project:string, iid:int, title:string, state:string, attention_state:string, attention_reason:string, updated_at_iso:string, web_url:string?}]",
+                    "activity": "[{timestamp_iso:string, event_type:string, entity_type:string, entity_iid:int, project:string, actor:string?, is_own:bool, summary:string, body_preview:string?}]"
+                },
+                "meta": {"elapsed_ms": "int", "gitlab_base_url": "string (GitLab instance URL for constructing entity links: {base_url}/{project}/-/issues/{iid})"}
+            },
+            "fields_presets": {
+                "me_items_minimal": ["iid", "title", "attention_state", "attention_reason", "updated_at_iso"],
+                "me_mentions_minimal": ["entity_type", "iid", "title", "state", "attention_state", "attention_reason", "updated_at_iso"],
+                "me_activity_minimal": ["timestamp_iso", "event_type", "entity_iid", "actor"]
+            },
+            "notes": {
+                "attention_states": "needs_attention | not_started | awaiting_response | stale | not_ready",
+                "event_types": "note | status_change | label_change | assign | unassign | review_request | milestone_change",
+                "section_flags": "If none of --issues/--mrs/--mentions/--activity specified, all sections returned",
+                "since_default": "1d for activity feed",
+                "issue_filter": "Only In Progress / In Review status issues shown",
+                "since_last_check": "Cursor-based inbox showing events since last run. Null on first run (no cursor yet). Groups events by entity (issue/MR). Sources: others' comments on your items, @mentions, assignment/review-request notes. Cursor auto-advances after each run. Use --reset-cursor to clear.",
+                "cursor_persistence": "Stored per user in ~/.local/share/lore/me_cursor_<username>.json. --project filters display only for since-last-check; cursor still advances for all projects for that user.",
+                "url_construction": "Use meta.gitlab_base_url + project + entity_type + iid to build links: {gitlab_base_url}/{project}/-/{issues|merge_requests}/{iid}"
+            }
+        },
+        "robot-docs": {
+            "description": "This command (agent self-discovery manifest)",
+            "flags": ["--brief"],
+            "example": "lore robot-docs --brief"
+        }
+    });
+
+    let quick_start = serde_json::json!({
+        "glab_equivalents": [
+            { "glab": "glab issue list", "lore": "lore -J issues -n 50", "note": "Richer: includes labels, status, closing MRs, discussion counts" },
+            { "glab": "glab issue view 123", "lore": "lore -J issues 123", "note": "Includes full discussions, work-item status, cross-references" },
+            { "glab": "glab issue list -l bug", "lore": "lore -J issues --label bug", "note": "AND logic for multiple --label flags" },
+            { "glab": "glab mr list", "lore": "lore -J mrs", "note": "Includes draft status, reviewers, discussion counts" },
+            { "glab": "glab mr view 456", "lore": "lore -J mrs 456", "note": "Includes discussions, review threads, source/target branches" },
+            { "glab": "glab mr list -s opened", "lore": "lore -J mrs -s opened", "note": "States: opened, merged, closed, locked, all" },
+            { "glab": "glab api '/projects/:id/issues'", "lore": "lore -J issues -p project", "note": "Fuzzy project matching (suffix or substring)" }
+        ],
+        "lore_exclusive": [
+            "search: FTS5 + vector hybrid search across all entities",
+            "who: Expert/workload/reviews analysis per file path or person",
+            "timeline: Chronological event reconstruction across entities",
+            "trace: Code provenance chains (file -> MR -> issue -> discussion)",
+            "file-history: MR history per file with rename resolution",
+            "notes: Rich note listing with author, type, resolution, path, and discussion filters",
+            "stats: Database statistics with document/note/discussion counts",
+            "count: Entity counts with state breakdowns",
+            "embed: Generate vector embeddings for semantic search via Ollama",
+            "cron: Automated sync scheduling (Unix)",
+            "token: Secure token management with masked display",
+            "me: Personal work dashboard with attention states, activity feed, cursor-based since-last-check inbox, and needs-attention triage"
+        ],
+        "read_write_split": "lore = ALL reads (issues, MRs, search, who, timeline, intelligence). glab = ALL writes (create, update, approve, merge, CI/CD)."
+    });
+
+    // --brief: strip response_schema and example_output from every command (~60% smaller)
+    let mut commands = commands;
+    if brief {
+        strip_schemas(&mut commands);
+    }
+
+    let exit_codes = serde_json::json!({
+        "0": "Success",
+        "1": "Internal error",
+        "2": "Usage error (invalid flags or arguments)",
+        "3": "Config invalid",
+        "4": "Token not set",
+        "5": "GitLab auth failed",
+        "6": "Resource not found",
+        "7": "Rate limited",
+        "8": "Network error",
+        "9": "Database locked",
+        "10": "Database error",
+        "11": "Migration failed",
+        "12": "I/O error",
+        "13": "Transform error",
+        "14": "Ollama unavailable",
+        "15": "Ollama model not found",
+        "16": "Embedding failed",
+        "17": "Not found",
+        "18": "Ambiguous match",
+        "19": "Health check failed",
+        "20": "Config not found",
+        "21": "Embeddings not built"
+    });
+
+    let workflows = serde_json::json!({
+        "first_setup": [
+            "lore --robot init --gitlab-url https://gitlab.com --token-env-var GITLAB_TOKEN --projects group/project",
+            "lore --robot doctor",
+            "lore --robot sync"
+        ],
+        "daily_sync": [
+            "lore --robot sync"
+        ],
+        "search": [
+            "lore --robot search 'query' --mode hybrid"
+        ],
+        "pre_flight": [
+            "lore --robot health"
+        ],
+        "temporal_intelligence": [
+            "lore --robot sync",
+            "lore --robot timeline '<keyword>' --since 30d",
+            "lore --robot timeline '<keyword>' --depth 2"
+        ],
+        "people_intelligence": [
+            "lore --robot who src/path/to/feature/",
+            "lore --robot who @username",
+            "lore --robot who @username --reviews",
+            "lore --robot who --active --since 7d",
+            "lore --robot who --overlap src/path/",
+            "lore --robot who --path README.md"
+        ],
+        "surgical_sync": [
+            "lore --robot sync --issue 7 -p group/project",
+            "lore --robot sync --issue 7 --mr 10 -p group/project",
+            "lore --robot sync --issue 7 -p group/project --preflight-only"
+        ],
+        "personal_dashboard": [
+            "lore --robot me",
+            "lore --robot me --issues",
+            "lore --robot me --activity --since 7d",
+            "lore --robot me --project group/repo",
+            "lore --robot me --fields minimal",
+            "lore --robot me --reset-cursor"
+        ]
+    });
+
+    // Phase 3: Deprecated command aliases
+    let aliases = serde_json::json!({
+        "deprecated_commands": {
+            "list issues": "issues",
+            "list mrs": "mrs",
+            "show issue <IID>": "issues <IID>",
+            "show mr <IID>": "mrs <IID>",
+            "auth-test": "auth",
+            "sync-status": "status"
+        },
+        "command_aliases": {
+            "issue": "issues",
+            "mr": "mrs",
+            "merge-requests": "mrs",
+            "merge-request": "mrs",
+            "mergerequests": "mrs",
+            "mergerequest": "mrs",
+            "generate-docs": "generate-docs",
+            "generatedocs": "generate-docs",
+            "gendocs": "generate-docs",
+            "gen-docs": "generate-docs",
+            "robot-docs": "robot-docs",
+            "robotdocs": "robot-docs"
+        },
+        "pre_clap_aliases": {
+            "note": "Underscore/no-separator forms auto-corrected before parsing",
+            "merge_requests": "mrs",
+            "merge_request": "mrs",
+            "mergerequests": "mrs",
+            "mergerequest": "mrs",
+            "generate_docs": "generate-docs",
+            "generatedocs": "generate-docs",
+            "gendocs": "generate-docs",
+            "gen-docs": "generate-docs",
+            "robot-docs": "robot-docs",
+            "robotdocs": "robot-docs"
+        },
+        "prefix_matching": "Enabled via infer_subcommands. Unambiguous prefixes work: 'iss' -> issues, 'time' -> timeline, 'sea' -> search"
+    });
+
+    let error_tolerance = serde_json::json!({
+        "note": "The CLI auto-corrects common mistakes before parsing. Corrections are applied silently with a teaching note on stderr.",
+        "auto_corrections": [
+            {"type": "single_dash_long_flag", "example": "-robot -> --robot", "mode": "all"},
+            {"type": "case_normalization", "example": "--Robot -> --robot, --State -> --state", "mode": "all"},
+            {"type": "flag_prefix", "example": "--proj -> --project (when unambiguous)", "mode": "all"},
+            {"type": "fuzzy_flag", "example": "--projct -> --project", "mode": "all (threshold 0.9 in robot, 0.8 in human)"},
+            {"type": "subcommand_alias", "example": "merge_requests -> mrs, robotdocs -> robot-docs", "mode": "all"},
+            {"type": "subcommand_fuzzy", "example": "issuess -> issues, timline -> timeline, serach -> search", "mode": "all (threshold 0.85)"},
+            {"type": "flag_as_subcommand", "example": "--robot-docs -> robot-docs, --generate-docs -> generate-docs", "mode": "all"},
+            {"type": "value_normalization", "example": "--state Opened -> --state opened", "mode": "all"},
+            {"type": "value_fuzzy", "example": "--state opend -> --state opened", "mode": "all"},
+            {"type": "prefix_matching", "example": "lore iss -> lore issues, lore time -> lore timeline", "mode": "all (via clap infer_subcommands)"}
+        ],
+        "teaching_notes": "Auto-corrections emit a JSON warning on stderr: {\"warning\":{\"type\":\"ARG_CORRECTED\",\"corrections\":[...],\"teaching\":[...]}}"
+    });
+
+    // Phase 3: Clap error codes (emitted by handle_clap_error)
+    let clap_error_codes = serde_json::json!({
+        "UNKNOWN_COMMAND": "Unrecognized subcommand (includes fuzzy suggestion)",
+        "UNKNOWN_FLAG": "Unrecognized command-line flag",
+        "MISSING_REQUIRED": "Required argument not provided",
+        "INVALID_VALUE": "Invalid value for argument",
+        "TOO_MANY_VALUES": "Too many values provided",
+        "TOO_FEW_VALUES": "Too few values provided",
+        "ARGUMENT_CONFLICT": "Conflicting arguments",
+        "MISSING_COMMAND": "No subcommand provided (in non-robot mode, shows help)",
+        "HELP_REQUESTED": "Help or version flag used",
+        "PARSE_ERROR": "General parse error"
+    });
+
+    let config_notes = serde_json::json!({
+        "defaultProject": {
+            "type": "string?",
+            "description": "Fallback project path used when -p/--project is omitted. Must match a configured project path (exact or suffix). CLI -p always overrides.",
+            "example": "group/project"
+        }
+    });
+
+    let output = RobotDocsOutput {
+        ok: true,
+        data: RobotDocsData {
+            name: "lore".to_string(),
+            version,
+            description: "Local GitLab data management with semantic search".to_string(),
+            activation: RobotDocsActivation {
+                flags: vec!["--robot".to_string(), "-J".to_string(), "--json".to_string()],
+                env: "LORE_ROBOT=1".to_string(),
+                auto: "Non-TTY stdout".to_string(),
+            },
+            quick_start,
+            commands,
+            aliases,
+            error_tolerance,
+            exit_codes,
+            clap_error_codes,
+            error_format: "stderr JSON: {\"error\":{\"code\":\"...\",\"message\":\"...\",\"suggestion\":\"...\",\"actions\":[\"...\"]}}".to_string(),
+            workflows,
+            config_notes,
+        },
+    };
+
+    if robot_mode {
+        println!("{}", serde_json::to_string(&output)?);
+    } else {
+        println!("{}", serde_json::to_string_pretty(&output)?);
+    }
+
+    Ok(())
+}
+
+fn handle_who(
+    config_override: Option<&str>,
+    mut args: WhoArgs,
+    robot_mode: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let start = std::time::Instant::now();
+    let config = Config::load(config_override)?;
+    if args.project.is_none() {
+        args.project = config.default_project.clone();
+    }
+    let run = run_who(&config, &args)?;
+    let elapsed_ms = start.elapsed().as_millis() as u64;
+
+    if robot_mode {
+        print_who_json(&run, &args, elapsed_ms);
+    } else {
+        print_who_human(&run.result, run.resolved_input.project_path.as_deref());
+    }
+    Ok(())
+}
+
+fn handle_me(
+    config_override: Option<&str>,
+    args: MeArgs,
+    robot_mode: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let config = Config::load(config_override)?;
+    run_me(&config, &args, robot_mode)?;
+    Ok(())
+}
+
+async fn handle_drift(
+    config_override: Option<&str>,
+    entity_type: &str,
+    iid: i64,
+    threshold: f32,
+    project: Option<&str>,
+    robot_mode: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let start = std::time::Instant::now();
+    let config = Config::load(config_override)?;
+    let effective_project = config.effective_project(project);
+    let response = run_drift(&config, entity_type, iid, threshold, effective_project).await?;
+    let elapsed_ms = start.elapsed().as_millis() as u64;
+
+    if robot_mode {
+        print_drift_json(&response, elapsed_ms);
+    } else {
+        print_drift_human(&response);
+    }
+    Ok(())
+}
+
+async fn handle_related(
+    config_override: Option<&str>,
+    query_or_type: &str,
+    iid: Option<i64>,
+    limit: usize,
+    project: Option<&str>,
+    robot_mode: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let start = std::time::Instant::now();
+    let config = Config::load(config_override)?;
+    let effective_project = config.effective_project(project);
+    let response = run_related(&config, query_or_type, iid, limit, effective_project).await?;
+    let elapsed_ms = start.elapsed().as_millis() as u64;
+
+    if robot_mode {
+        print_related_json(&response, elapsed_ms);
+    } else {
+        print_related_human(&response);
+    }
+    Ok(())
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn handle_list_compat(
+    config_override: Option<&str>,
+    entity: &str,
+    limit: usize,
+    project_filter: Option<&str>,
+    state_filter: Option<&str>,
+    author_filter: Option<&str>,
+    assignee_filter: Option<&str>,
+    label_filter: Option<&[String]>,
+    milestone_filter: Option<&str>,
+    since_filter: Option<&str>,
+    due_before_filter: Option<&str>,
+    has_due_date: bool,
+    sort: &str,
+    order: &str,
+    open_browser: bool,
+    json_output: bool,
+    draft: bool,
+    no_draft: bool,
+    reviewer_filter: Option<&str>,
+    target_branch_filter: Option<&str>,
+    source_branch_filter: Option<&str>,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let start = std::time::Instant::now();
+    let config = Config::load(config_override)?;
+    let project_filter = config.effective_project(project_filter);
+
+    let state_normalized = state_filter.map(str::to_lowercase);
+    match entity {
+        "issues" => {
+            let filters = ListFilters {
+                limit,
+                project: project_filter,
+                state: state_normalized.as_deref(),
+                author: author_filter,
+                assignee: assignee_filter,
+                labels: label_filter,
+                milestone: milestone_filter,
+                since: since_filter,
+                due_before: due_before_filter,
+                has_due_date,
+                statuses: &[],
+                sort,
+                order,
+            };
+
+            let result = run_list_issues(&config, filters)?;
+
+            if open_browser {
+                open_issue_in_browser(&result);
+            } else if json_output {
+                print_list_issues_json(&result, start.elapsed().as_millis() as u64, None);
+            } else {
+                print_list_issues(&result);
+            }
+
+            Ok(())
+        }
+        "mrs" => {
+            let filters = MrListFilters {
+                limit,
+                project: project_filter,
+                state: state_normalized.as_deref(),
+                author: author_filter,
+                assignee: assignee_filter,
+                reviewer: reviewer_filter,
+                labels: label_filter,
+                since: since_filter,
+                draft,
+                no_draft,
+                target_branch: target_branch_filter,
+                source_branch: source_branch_filter,
+                sort,
+                order,
+            };
+
+            let result = run_list_mrs(&config, filters)?;
+
+            if open_browser {
+                open_mr_in_browser(&result);
+            } else if json_output {
+                print_list_mrs_json(&result, start.elapsed().as_millis() as u64, None);
+            } else {
+                print_list_mrs(&result);
+            }
+
+            Ok(())
+        }
+        _ => {
+            eprintln!(
+                "{}",
+                Theme::error().render(&format!("Unknown entity: {entity}"))
+            );
+            std::process::exit(1);
+        }
+    }
+}
+

src/cli/args.rs

@@ -0,0 +1,870 @@
+use clap::{Args, Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore issues -n 10                     # List 10 most recently updated issues
+  lore issues -s opened -l bug          # Open issues labeled 'bug'
+  lore issues 42 -p group/repo          # Show issue #42 in a specific project
+  lore issues --since 7d -a jsmith      # Issues updated in last 7 days by jsmith")]
+pub struct IssuesArgs {
+    /// Issue IID (omit to list, provide to show details)
+    pub iid: Option<i64>,
+
+    /// Maximum results
+    #[arg(
+        short = 'n',
+        long = "limit",
+        default_value = "50",
+        help_heading = "Output"
+    )]
+    pub limit: usize,
+
+    /// Select output fields (comma-separated, or 'minimal' preset: iid,title,state,updated_at_iso)
+    #[arg(long, help_heading = "Output", value_delimiter = ',')]
+    pub fields: Option<Vec<String>>,
+
+    /// Filter by state (opened, closed, all)
+    #[arg(short = 's', long, help_heading = "Filters", value_parser = ["opened", "closed", "all"])]
+    pub state: Option<String>,
+
+    /// Filter by project path
+    #[arg(short = 'p', long, help_heading = "Filters")]
+    pub project: Option<String>,
+
+    /// Filter by author username
+    #[arg(short = 'a', long, help_heading = "Filters")]
+    pub author: Option<String>,
+
+    /// Filter by assignee username
+    #[arg(short = 'A', long, help_heading = "Filters")]
+    pub assignee: Option<String>,
+
+    /// Filter by label (repeatable, AND logic)
+    #[arg(short = 'l', long, help_heading = "Filters")]
+    pub label: Option<Vec<String>>,
+
+    /// Filter by milestone title
+    #[arg(short = 'm', long, help_heading = "Filters")]
+    pub milestone: Option<String>,
+
+    /// Filter by work-item status name (repeatable, OR logic)
+    #[arg(long, help_heading = "Filters")]
+    pub status: Vec<String>,
+
+    /// Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
+    #[arg(long, help_heading = "Filters")]
+    pub since: Option<String>,
+
+    /// Filter by due date (before this date, YYYY-MM-DD)
+    #[arg(long = "due-before", help_heading = "Filters")]
+    pub due_before: Option<String>,
+
+    /// Show only issues with a due date
+    #[arg(
+        long = "has-due",
+        help_heading = "Filters",
+        overrides_with = "no_has_due"
+    )]
+    pub has_due: bool,
+
+    #[arg(long = "no-has-due", hide = true, overrides_with = "has_due")]
+    pub no_has_due: bool,
+
+    /// Sort field (updated, created, iid)
+    #[arg(long, value_parser = ["updated", "created", "iid"], default_value = "updated", help_heading = "Sorting")]
+    pub sort: String,
+
+    /// Sort ascending (default: descending)
+    #[arg(long, help_heading = "Sorting", overrides_with = "no_asc")]
+    pub asc: bool,
+
+    #[arg(long = "no-asc", hide = true, overrides_with = "asc")]
+    pub no_asc: bool,
+
+    /// Open first matching item in browser
+    #[arg(
+        short = 'o',
+        long,
+        help_heading = "Actions",
+        overrides_with = "no_open"
+    )]
+    pub open: bool,
+
+    #[arg(long = "no-open", hide = true, overrides_with = "open")]
+    pub no_open: bool,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore mrs -s opened                    # List open merge requests
+  lore mrs -s merged --since 2w         # MRs merged in the last 2 weeks
+  lore mrs 99 -p group/repo             # Show MR !99 in a specific project
+  lore mrs -D --reviewer jsmith         # Non-draft MRs reviewed by jsmith")]
+pub struct MrsArgs {
+    /// MR IID (omit to list, provide to show details)
+    pub iid: Option<i64>,
+
+    /// Maximum results
+    #[arg(
+        short = 'n',
+        long = "limit",
+        default_value = "50",
+        help_heading = "Output"
+    )]
+    pub limit: usize,
+
+    /// Select output fields (comma-separated, or 'minimal' preset: iid,title,state,updated_at_iso)
+    #[arg(long, help_heading = "Output", value_delimiter = ',')]
+    pub fields: Option<Vec<String>>,
+
+    /// Filter by state (opened, merged, closed, locked, all)
+    #[arg(short = 's', long, help_heading = "Filters", value_parser = ["opened", "merged", "closed", "locked", "all"])]
+    pub state: Option<String>,
+
+    /// Filter by project path
+    #[arg(short = 'p', long, help_heading = "Filters")]
+    pub project: Option<String>,
+
+    /// Filter by author username
+    #[arg(short = 'a', long, help_heading = "Filters")]
+    pub author: Option<String>,
+
+    /// Filter by assignee username
+    #[arg(short = 'A', long, help_heading = "Filters")]
+    pub assignee: Option<String>,
+
+    /// Filter by reviewer username
+    #[arg(short = 'r', long, help_heading = "Filters")]
+    pub reviewer: Option<String>,
+
+    /// Filter by label (repeatable, AND logic)
+    #[arg(short = 'l', long, help_heading = "Filters")]
+    pub label: Option<Vec<String>>,
+
+    /// Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
+    #[arg(long, help_heading = "Filters")]
+    pub since: Option<String>,
+
+    /// Show only draft MRs
+    #[arg(
+        short = 'd',
+        long,
+        conflicts_with = "no_draft",
+        help_heading = "Filters"
+    )]
+    pub draft: bool,
+
+    /// Exclude draft MRs
+    #[arg(
+        short = 'D',
+        long = "no-draft",
+        conflicts_with = "draft",
+        help_heading = "Filters"
+    )]
+    pub no_draft: bool,
+
+    /// Filter by target branch
+    #[arg(long, help_heading = "Filters")]
+    pub target: Option<String>,
+
+    /// Filter by source branch
+    #[arg(long, help_heading = "Filters")]
+    pub source: Option<String>,
+
+    /// Sort field (updated, created, iid)
+    #[arg(long, value_parser = ["updated", "created", "iid"], default_value = "updated", help_heading = "Sorting")]
+    pub sort: String,
+
+    /// Sort ascending (default: descending)
+    #[arg(long, help_heading = "Sorting", overrides_with = "no_asc")]
+    pub asc: bool,
+
+    #[arg(long = "no-asc", hide = true, overrides_with = "asc")]
+    pub no_asc: bool,
+
+    /// Open first matching item in browser
+    #[arg(
+        short = 'o',
+        long,
+        help_heading = "Actions",
+        overrides_with = "no_open"
+    )]
+    pub open: bool,
+
+    #[arg(long = "no-open", hide = true, overrides_with = "open")]
+    pub no_open: bool,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore notes                                  # List 50 most recent notes
+  lore notes --author alice --since 7d        # Notes by alice in last 7 days
+  lore notes --for-issue 42 -p group/repo     # Notes on issue #42
+  lore notes --path src/ --resolution unresolved  # Unresolved diff notes in src/")]
+pub struct NotesArgs {
+    /// Maximum results
+    #[arg(
+        short = 'n',
+        long = "limit",
+        default_value = "50",
+        help_heading = "Output"
+    )]
+    pub limit: usize,
+
+    /// Select output fields (comma-separated, or 'minimal' preset: id,author_username,body,created_at_iso)
+    #[arg(long, help_heading = "Output", value_delimiter = ',')]
+    pub fields: Option<Vec<String>>,
+
+    /// Filter by author username
+    #[arg(short = 'a', long, help_heading = "Filters")]
+    pub author: Option<String>,
+
+    /// Filter by note type (DiffNote, DiscussionNote)
+    #[arg(long, help_heading = "Filters")]
+    pub note_type: Option<String>,
+
+    /// Filter by body text (substring match)
+    #[arg(long, help_heading = "Filters")]
+    pub contains: Option<String>,
+
+    /// Filter by internal note ID
+    #[arg(long, help_heading = "Filters")]
+    pub note_id: Option<i64>,
+
+    /// Filter by GitLab note ID
+    #[arg(long, help_heading = "Filters")]
+    pub gitlab_note_id: Option<i64>,
+
+    /// Filter by discussion ID
+    #[arg(long, help_heading = "Filters")]
+    pub discussion_id: Option<String>,
+
+    /// Include system notes (excluded by default)
+    #[arg(long, help_heading = "Filters")]
+    pub include_system: bool,
+
+    /// Filter to notes on a specific issue IID (requires --project or default_project)
+    #[arg(long, conflicts_with = "for_mr", help_heading = "Filters")]
+    pub for_issue: Option<i64>,
+
+    /// Filter to notes on a specific MR IID (requires --project or default_project)
+    #[arg(long, conflicts_with = "for_issue", help_heading = "Filters")]
+    pub for_mr: Option<i64>,
+
+    /// Filter by project path
+    #[arg(short = 'p', long, help_heading = "Filters")]
+    pub project: Option<String>,
+
+    /// Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
+    #[arg(long, help_heading = "Filters")]
+    pub since: Option<String>,
+
+    /// Filter until date (YYYY-MM-DD, inclusive end-of-day)
+    #[arg(long, help_heading = "Filters")]
+    pub until: Option<String>,
+
+    /// Filter by file path (exact match or prefix with trailing /)
+    #[arg(long, help_heading = "Filters")]
+    pub path: Option<String>,
+
+    /// Filter by resolution status (any, unresolved, resolved)
+    #[arg(
+        long,
+        value_parser = ["any", "unresolved", "resolved"],
+        help_heading = "Filters"
+    )]
+    pub resolution: Option<String>,
+
+    /// Sort field (created, updated)
+    #[arg(
+        long,
+        value_parser = ["created", "updated"],
+        default_value = "created",
+        help_heading = "Sorting"
+    )]
+    pub sort: String,
+
+    /// Sort ascending (default: descending)
+    #[arg(long, help_heading = "Sorting")]
+    pub asc: bool,
+
+    /// Open first matching item in browser
+    #[arg(long, help_heading = "Actions")]
+    pub open: bool,
+}
+
+#[derive(Parser)]
+pub struct IngestArgs {
+    /// Entity to ingest (issues, mrs). Omit to ingest everything
+    #[arg(value_parser = ["issues", "mrs"])]
+    pub entity: Option<String>,
+
+    /// Filter to single project
+    #[arg(short = 'p', long)]
+    pub project: Option<String>,
+
+    /// Override stale sync lock
+    #[arg(short = 'f', long, overrides_with = "no_force")]
+    pub force: bool,
+
+    #[arg(long = "no-force", hide = true, overrides_with = "force")]
+    pub no_force: bool,
+
+    /// Full re-sync: reset cursors and fetch all data from scratch
+    #[arg(long, overrides_with = "no_full")]
+    pub full: bool,
+
+    #[arg(long = "no-full", hide = true, overrides_with = "full")]
+    pub no_full: bool,
+
+    /// Preview what would be synced without making changes
+    #[arg(long, overrides_with = "no_dry_run")]
+    pub dry_run: bool,
+
+    #[arg(long = "no-dry-run", hide = true, overrides_with = "dry_run")]
+    pub no_dry_run: bool,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore stats                              # Show document and index statistics
+  lore stats --check                      # Run integrity checks
+  lore stats --repair --dry-run           # Preview what repair would fix
+  lore --robot stats                      # JSON output for automation")]
+pub struct StatsArgs {
+    /// Run integrity checks
+    #[arg(long, overrides_with = "no_check")]
+    pub check: bool,
+
+    #[arg(long = "no-check", hide = true, overrides_with = "check")]
+    pub no_check: bool,
+
+    /// Repair integrity issues (auto-enables --check)
+    #[arg(long)]
+    pub repair: bool,
+
+    /// Preview what would be repaired without making changes (requires --repair)
+    #[arg(long, overrides_with = "no_dry_run")]
+    pub dry_run: bool,
+
+    #[arg(long = "no-dry-run", hide = true, overrides_with = "dry_run")]
+    pub no_dry_run: bool,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore search 'authentication bug'               # Hybrid search (default)
+  lore search 'deploy' --mode lexical --type mr   # Lexical search, MRs only
+  lore search 'API rate limit' --since 30d        # Recent results only
+  lore search 'config' -p group/repo --explain    # With ranking explanation")]
+pub struct SearchArgs {
+    /// Search query string
+    pub query: String,
+
+    /// Search mode (lexical, hybrid, semantic)
+    #[arg(long, default_value = "hybrid", value_parser = ["lexical", "hybrid", "semantic"], help_heading = "Mode")]
+    pub mode: String,
+
+    /// Filter by source type (issue, mr, discussion, note)
+    #[arg(long = "type", value_name = "TYPE", value_parser = ["issue", "mr", "discussion", "note"], help_heading = "Filters")]
+    pub source_type: Option<String>,
+
+    /// Filter by author username
+    #[arg(long, help_heading = "Filters")]
+    pub author: Option<String>,
+
+    /// Filter by project path
+    #[arg(short = 'p', long, help_heading = "Filters")]
+    pub project: Option<String>,
+
+    /// Filter by label (repeatable, AND logic)
+    #[arg(long, action = clap::ArgAction::Append, help_heading = "Filters")]
+    pub label: Vec<String>,
+
+    /// Filter by file path (trailing / for prefix match)
+    #[arg(long, help_heading = "Filters")]
+    pub path: Option<String>,
+
+    /// Filter by created since (7d, 2w, or YYYY-MM-DD)
+    #[arg(long, help_heading = "Filters")]
+    pub since: Option<String>,
+
+    /// Filter by updated since (7d, 2w, or YYYY-MM-DD)
+    #[arg(long = "updated-since", help_heading = "Filters")]
+    pub updated_since: Option<String>,
+
+    /// Maximum results (default 20, max 100)
+    #[arg(
+        short = 'n',
+        long = "limit",
+        default_value = "20",
+        help_heading = "Output"
+    )]
+    pub limit: usize,
+
+    /// Select output fields (comma-separated, or 'minimal' preset: document_id,title,source_type,score)
+    #[arg(long, help_heading = "Output", value_delimiter = ',')]
+    pub fields: Option<Vec<String>>,
+
+    /// Show ranking explanation per result
+    #[arg(long, help_heading = "Output", overrides_with = "no_explain")]
+    pub explain: bool,
+
+    #[arg(long = "no-explain", hide = true, overrides_with = "explain")]
+    pub no_explain: bool,
+
+    /// FTS query mode: safe (default) or raw
+    #[arg(long = "fts-mode", default_value = "safe", value_parser = ["safe", "raw"], help_heading = "Mode")]
+    pub fts_mode: String,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore generate-docs                      # Generate docs for dirty entities
+  lore generate-docs --full               # Full rebuild of all documents
+  lore generate-docs --full -p group/repo # Full rebuild for one project")]
+pub struct GenerateDocsArgs {
+    /// Full rebuild: seed all entities into dirty queue, then drain
+    #[arg(long)]
+    pub full: bool,
+
+    /// Filter to single project
+    #[arg(short = 'p', long)]
+    pub project: Option<String>,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore sync                             # Full pipeline: ingest + docs + embed
+  lore sync --no-embed                  # Skip embedding step
+  lore sync --no-status                 # Skip work-item status enrichment
+  lore sync --full --force              # Full re-sync, override stale lock
+  lore sync --dry-run                   # Preview what would change
+  lore sync --issue 42 -p group/repo    # Surgically sync one issue
+  lore sync --mr 10 --mr 20 -p g/r     # Surgically sync two MRs")]
+pub struct SyncArgs {
+    /// Reset cursors, fetch everything
+    #[arg(long, overrides_with = "no_full")]
+    pub full: bool,
+
+    #[arg(long = "no-full", hide = true, overrides_with = "full")]
+    pub no_full: bool,
+
+    /// Override stale lock
+    #[arg(long, overrides_with = "no_force")]
+    pub force: bool,
+
+    #[arg(long = "no-force", hide = true, overrides_with = "force")]
+    pub no_force: bool,
+
+    /// Skip embedding step
+    #[arg(long)]
+    pub no_embed: bool,
+
+    /// Skip document regeneration
+    #[arg(long)]
+    pub no_docs: bool,
+
+    /// Skip resource event fetching (overrides config)
+    #[arg(long = "no-events")]
+    pub no_events: bool,
+
+    /// Skip MR file change fetching (overrides config)
+    #[arg(long = "no-file-changes")]
+    pub no_file_changes: bool,
+
+    /// Skip work-item status enrichment via GraphQL (overrides config)
+    #[arg(long = "no-status")]
+    pub no_status: bool,
+
+    /// Preview what would be synced without making changes
+    #[arg(long, overrides_with = "no_dry_run")]
+    pub dry_run: bool,
+
+    #[arg(long = "no-dry-run", hide = true, overrides_with = "dry_run")]
+    pub no_dry_run: bool,
+
+    /// Show detailed timing breakdown for sync stages
+    #[arg(short = 't', long = "timings")]
+    pub timings: bool,
+
+    /// Acquire file lock before syncing (skip if another sync is running)
+    #[arg(long)]
+    pub lock: bool,
+
+    /// Surgically sync specific issues by IID (repeatable, must be positive)
+    #[arg(long, value_parser = clap::value_parser!(u64).range(1..), action = clap::ArgAction::Append)]
+    pub issue: Vec<u64>,
+
+    /// Surgically sync specific merge requests by IID (repeatable, must be positive)
+    #[arg(long, value_parser = clap::value_parser!(u64).range(1..), action = clap::ArgAction::Append)]
+    pub mr: Vec<u64>,
+
+    /// Scope to a single project (required when --issue or --mr is used)
+    #[arg(short = 'p', long)]
+    pub project: Option<String>,
+
+    /// Validate remote entities exist without DB writes (preflight only)
+    #[arg(long)]
+    pub preflight_only: bool,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore embed                              # Embed new/changed documents
+  lore embed --full                       # Re-embed all documents from scratch
+  lore embed --retry-failed               # Retry previously failed embeddings")]
+pub struct EmbedArgs {
+    /// Re-embed all documents (clears existing embeddings first)
+    #[arg(long, overrides_with = "no_full")]
+    pub full: bool,
+
+    #[arg(long = "no-full", hide = true, overrides_with = "full")]
+    pub no_full: bool,
+
+    /// Retry previously failed embeddings
+    #[arg(long, overrides_with = "no_retry_failed")]
+    pub retry_failed: bool,
+
+    #[arg(long = "no-retry-failed", hide = true, overrides_with = "retry_failed")]
+    pub no_retry_failed: bool,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore timeline 'deployment'                          # Search-based seeding
+  lore timeline issue:42                              # Direct: issue #42 and related entities
+  lore timeline i:42                                  # Shorthand for issue:42
+  lore timeline mr:99                                 # Direct: MR !99 and related entities
+  lore timeline 'auth' --since 30d -p group/repo      # Scoped to project and time
+  lore timeline 'migration' --depth 2              # Deep cross-reference expansion
+  lore timeline 'auth' --no-mentions               # Only 'closes' and 'related' edges")]
+pub struct TimelineArgs {
+    /// Search text or entity reference (issue:N, i:N, mr:N, m:N)
+    pub query: String,
+
+    /// Scope to a specific project (fuzzy match)
+    #[arg(short = 'p', long, help_heading = "Filters")]
+    pub project: Option<String>,
+
+    /// Only show events after this date (e.g. "6m", "2w", "2024-01-01")
+    #[arg(long, help_heading = "Filters")]
+    pub since: Option<String>,
+
+    /// Cross-reference expansion depth (0 = no expansion)
+    #[arg(long, default_value = "1", help_heading = "Expansion")]
+    pub depth: u32,
+
+    /// Skip 'mentioned' edges during expansion (only follow 'closes' and 'related')
+    #[arg(long = "no-mentions", help_heading = "Expansion")]
+    pub no_mentions: bool,
+
+    /// Maximum number of events to display
+    #[arg(
+        short = 'n',
+        long = "limit",
+        default_value = "100",
+        help_heading = "Output"
+    )]
+    pub limit: usize,
+
+    /// Select output fields (comma-separated, or 'minimal' preset: timestamp,type,entity_iid,detail)
+    #[arg(long, help_heading = "Output", value_delimiter = ',')]
+    pub fields: Option<Vec<String>>,
+
+    /// Maximum seed entities from search
+    #[arg(long = "max-seeds", default_value = "10", help_heading = "Expansion")]
+    pub max_seeds: usize,
+
+    /// Maximum expanded entities via cross-references
+    #[arg(
+        long = "max-entities",
+        default_value = "50",
+        help_heading = "Expansion"
+    )]
+    pub max_entities: usize,
+
+    /// Maximum evidence notes included
+    #[arg(
+        long = "max-evidence",
+        default_value = "10",
+        help_heading = "Expansion"
+    )]
+    pub max_evidence: usize,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore who src/features/auth/           # Who knows about this area?
+  lore who @asmith                      # What is asmith working on?
+  lore who @asmith --reviews            # What review patterns does asmith have?
+  lore who --active                     # What discussions need attention?
+  lore who --overlap src/features/auth/ # Who else is touching these files?
+  lore who --path README.md             # Expert lookup for a root file
+  lore who --path Makefile              # Expert lookup for a dotless root file")]
+pub struct WhoArgs {
+    /// Username or file path (path if contains /)
+    pub target: Option<String>,
+
+    /// Force expert mode for a file/directory path.
+    /// Root files (README.md, LICENSE, Makefile) are treated as exact matches.
+    /// Use a trailing `/` to force directory-prefix matching.
+    #[arg(long, help_heading = "Mode", conflicts_with_all = ["active", "overlap", "reviews"])]
+    pub path: Option<String>,
+
+    /// Show active unresolved discussions
+    #[arg(long, help_heading = "Mode", conflicts_with_all = ["target", "overlap", "reviews", "path"])]
+    pub active: bool,
+
+    /// Find users with MRs/notes touching this file path
+    #[arg(long, help_heading = "Mode", conflicts_with_all = ["target", "active", "reviews", "path"])]
+    pub overlap: Option<String>,
+
+    /// Show review pattern analysis (requires username target)
+    #[arg(long, help_heading = "Mode", requires = "target", conflicts_with_all = ["active", "overlap", "path"])]
+    pub reviews: bool,
+
+    /// Time window (7d, 2w, 6m, YYYY-MM-DD). Default varies by mode.
+    #[arg(long, help_heading = "Filters")]
+    pub since: Option<String>,
+
+    /// Scope to a project (supports fuzzy matching)
+    #[arg(short = 'p', long, help_heading = "Filters")]
+    pub project: Option<String>,
+
+    /// Maximum results per section (1..=500); omit for unlimited
+    #[arg(
+        short = 'n',
+        long = "limit",
+        value_parser = clap::value_parser!(u16).range(1..=500),
+        help_heading = "Output"
+    )]
+    pub limit: Option<u16>,
+
+    /// Select output fields (comma-separated, or 'minimal' preset; varies by mode)
+    #[arg(long, help_heading = "Output", value_delimiter = ',')]
+    pub fields: Option<Vec<String>>,
+
+    /// Show per-MR detail breakdown (expert mode only)
+    #[arg(
+        long,
+        help_heading = "Output",
+        overrides_with = "no_detail",
+        conflicts_with = "explain_score"
+    )]
+    pub detail: bool,
+
+    #[arg(long = "no-detail", hide = true, overrides_with = "detail")]
+    pub no_detail: bool,
+
+    /// Score as if "now" is this date (ISO 8601 or duration like 30d). Expert mode only.
+    #[arg(long = "as-of", help_heading = "Scoring")]
+    pub as_of: Option<String>,
+
+    /// Show per-component score breakdown in output. Expert mode only.
+    #[arg(long = "explain-score", help_heading = "Scoring")]
+    pub explain_score: bool,
+
+    /// Include bot users in results (normally excluded via scoring.excluded_usernames).
+    #[arg(long = "include-bots", help_heading = "Scoring")]
+    pub include_bots: bool,
+
+    /// Include discussions on closed issues and merged/closed MRs
+    #[arg(long, help_heading = "Filters")]
+    pub include_closed: bool,
+
+    /// Remove the default time window (query all history). Conflicts with --since.
+    #[arg(
+        long = "all-history",
+        help_heading = "Filters",
+        conflicts_with = "since"
+    )]
+    pub all_history: bool,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore me                                 # Full dashboard (default project or all)
+  lore me --issues                        # Issues section only
+  lore me --mrs                           # MRs section only
+  lore me --activity                      # Activity feed only
+  lore me --all                           # All synced projects
+  lore me --since 2d                      # Activity window (default: 30d)
+  lore me --project group/repo            # Scope to one project
+  lore me --user jdoe                     # Override configured username")]
+pub struct MeArgs {
+    /// Show open issues section
+    #[arg(long, help_heading = "Sections")]
+    pub issues: bool,
+
+    /// Show authored + reviewing MRs section
+    #[arg(long, help_heading = "Sections")]
+    pub mrs: bool,
+
+    /// Show activity feed section
+    #[arg(long, help_heading = "Sections")]
+    pub activity: bool,
+
+    /// Show items you're @mentioned in (not assigned/authored/reviewing)
+    #[arg(long, help_heading = "Sections")]
+    pub mentions: bool,
+
+    /// Activity window (e.g. 7d, 2w, 30d). Default: 30d. Only affects activity section.
+    #[arg(long, help_heading = "Filters")]
+    pub since: Option<String>,
+
+    /// Scope to a project (supports fuzzy matching)
+    #[arg(short = 'p', long, help_heading = "Filters", conflicts_with = "all")]
+    pub project: Option<String>,
+
+    /// Show all synced projects (overrides default_project)
+    #[arg(long, help_heading = "Filters", conflicts_with = "project")]
+    pub all: bool,
+
+    /// Override configured username
+    #[arg(long = "user", help_heading = "Filters")]
+    pub user: Option<String>,
+
+    /// Select output fields (comma-separated, or 'minimal' preset)
+    #[arg(long, help_heading = "Output", value_delimiter = ',')]
+    pub fields: Option<Vec<String>>,
+
+    /// Reset the since-last-check cursor (next run shows no new events)
+    #[arg(long, help_heading = "Output")]
+    pub reset_cursor: bool,
+}
+
+impl MeArgs {
+    /// Returns true if no section flags were passed (show all sections).
+    pub fn show_all_sections(&self) -> bool {
+        !self.issues && !self.mrs && !self.activity && !self.mentions
+    }
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore file-history src/main.rs                  # MRs that touched this file
+  lore file-history src/auth/ -p group/repo      # Scoped to project
+  lore file-history src/foo.rs --discussions      # Include DiffNote snippets
+  lore file-history src/bar.rs --no-follow-renames  # Skip rename chain")]
+pub struct FileHistoryArgs {
+    /// File path to trace history for
+    pub path: String,
+
+    /// Scope to a specific project (fuzzy match)
+    #[arg(short = 'p', long, help_heading = "Filters")]
+    pub project: Option<String>,
+
+    /// Include discussion snippets from DiffNotes on this file
+    #[arg(long, help_heading = "Output")]
+    pub discussions: bool,
+
+    /// Disable rename chain resolution
+    #[arg(long = "no-follow-renames", help_heading = "Filters")]
+    pub no_follow_renames: bool,
+
+    /// Only show merged MRs
+    #[arg(long, help_heading = "Filters")]
+    pub merged: bool,
+
+    /// Maximum results
+    #[arg(
+        short = 'n',
+        long = "limit",
+        default_value = "50",
+        help_heading = "Output"
+    )]
+    pub limit: usize,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore trace src/main.rs                      # Why was this file changed?
+  lore trace src/auth/ -p group/repo          # Scoped to project
+  lore trace src/foo.rs --discussions          # Include DiffNote context
+  lore trace src/bar.rs:42                    # Line hint (Tier 2 warning)")]
+pub struct TraceArgs {
+    /// File path to trace (supports :line suffix for future Tier 2)
+    pub path: String,
+
+    /// Scope to a specific project (fuzzy match)
+    #[arg(short = 'p', long, help_heading = "Filters")]
+    pub project: Option<String>,
+
+    /// Include DiffNote discussion snippets
+    #[arg(long, help_heading = "Output")]
+    pub discussions: bool,
+
+    /// Disable rename chain resolution
+    #[arg(long = "no-follow-renames", help_heading = "Filters")]
+    pub no_follow_renames: bool,
+
+    /// Maximum trace chains to display
+    #[arg(
+        short = 'n',
+        long = "limit",
+        default_value = "20",
+        help_heading = "Output"
+    )]
+    pub limit: usize,
+}
+
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore count issues                       # Total issues in local database
+  lore count notes --for mr               # Notes on merge requests only
+  lore count discussions --for issue       # Discussions on issues only")]
+pub struct CountArgs {
+    /// Entity type to count (issues, mrs, discussions, notes, events)
+    #[arg(value_parser = ["issues", "mrs", "discussions", "notes", "events"])]
+    pub entity: String,
+
+    /// Parent type filter: issue or mr (for discussions/notes)
+    #[arg(short = 'f', long = "for", value_parser = ["issue", "mr"])]
+    pub for_entity: Option<String>,
+}
+
+#[derive(Parser)]
+pub struct CronArgs {
+    #[command(subcommand)]
+    pub action: CronAction,
+}
+
+#[derive(Subcommand)]
+pub enum CronAction {
+    /// Install cron job for automatic syncing
+    Install {
+        /// Sync interval in minutes (default: 8)
+        #[arg(long, default_value = "8")]
+        interval: u32,
+    },
+
+    /// Remove cron job
+    Uninstall,
+
+    /// Show current cron configuration
+    Status,
+}
+
+#[derive(Args)]
+pub struct TokenArgs {
+    #[command(subcommand)]
+    pub action: TokenAction,
+}
+
+#[derive(Subcommand)]
+pub enum TokenAction {
+    /// Store a GitLab token in the config file
+    Set {
+        /// Token value (reads from stdin if omitted in non-interactive mode)
+        #[arg(long)]
+        token: Option<String>,
+    },
+
+    /// Show the current token (masked by default)
+    Show {
+        /// Show the full unmasked token
+        #[arg(long)]
+        unmask: bool,
+    },
+}

src/cli/autocorrect.rs

@@ -22,9 +22,14 @@ pub enum CorrectionRule {
     CaseNormalization,
     FuzzyFlag,
     SubcommandAlias,
+    /// Fuzzy subcommand match: "issuess" → "issues"
+    SubcommandFuzzy,
+    /// Flag-style subcommand: "--robot-docs" → "robot-docs"
+    FlagAsSubcommand,
     ValueNormalization,
     ValueFuzzy,
     FlagPrefix,
+    NoColorExpansion,
 }
 
 /// Result of the correction pass over raw args.
@@ -128,6 +133,11 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
             "--dry-run",
             "--no-dry-run",
             "--timings",
+            "--lock",
+            "--issue",
+            "--mr",
+            "--project",
+            "--preflight-only",
         ],
     ),
     (
@@ -177,6 +187,7 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
             "--max-evidence",
         ],
     ),
+    ("related", &["--limit", "--project"]),
     (
         "who",
         &[
@@ -193,16 +204,26 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
             "--as-of",
             "--explain-score",
             "--include-bots",
+            "--include-closed",
             "--all-history",
         ],
     ),
     ("drift", &["--threshold", "--project"]),
+    (
+        "explain",
+        &[
+            "--project",
+            "--sections",
+            "--no-timeline",
+            "--max-decisions",
+            "--since",
+        ],
+    ),
     (
         "notes",
         &[
             "--limit",
             "--fields",
-            "--format",
             "--author",
             "--note-type",
             "--contains",
@@ -225,6 +246,7 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
     (
         "init",
         &[
+            "--refresh",
             "--force",
             "--non-interactive",
             "--gitlab-url",
@@ -278,8 +300,22 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
             "--source-branch",
         ],
     ),
-    ("show", &["--project"]),
     ("reset", &["--yes"]),
+    (
+        "me",
+        &[
+            "--issues",
+            "--mrs",
+            "--activity",
+            "--mentions",
+            "--since",
+            "--project",
+            "--all",
+            "--user",
+            "--fields",
+            "--reset-cursor",
+        ],
+    ),
 ];
 
 /// Valid values for enum-like flags, used for post-clap error enhancement.
@@ -329,6 +365,51 @@ const FUZZY_FLAG_THRESHOLD: f64 = 0.8;
 /// avoid misleading agents. Still catches obvious typos like `--projct`.
 const FUZZY_FLAG_THRESHOLD_STRICT: f64 = 0.9;
 
+/// Fuzzy subcommand threshold — higher than flags because subcommand names
+/// are shorter words where JW scores inflate more easily.
+const FUZZY_SUBCMD_THRESHOLD: f64 = 0.85;
+
+/// All canonical subcommand names for fuzzy matching and flag-as-subcommand
+/// detection. Includes hidden commands so agents that know about them can
+/// still benefit from typo correction.
+const CANONICAL_SUBCOMMANDS: &[&str] = &[
+    "issues",
+    "mrs",
+    "notes",
+    "ingest",
+    "count",
+    "status",
+    "auth",
+    "doctor",
+    "version",
+    "init",
+    "search",
+    "stats",
+    "generate-docs",
+    "embed",
+    "sync",
+    "migrate",
+    "health",
+    "robot-docs",
+    "completions",
+    "timeline",
+    "who",
+    "me",
+    "file-history",
+    "trace",
+    "drift",
+    "explain",
+    "related",
+    "cron",
+    "token",
+    // Hidden but still valid
+    "backup",
+    "reset",
+    "list",
+    "auth-test",
+    "sync-status",
+];
+
 // ---------------------------------------------------------------------------
 // Core logic
 // ---------------------------------------------------------------------------
@@ -423,9 +504,21 @@ pub fn correct_args(raw: Vec<String>, strict: bool) -> CorrectionResult {
         }
 
         if let Some(fixed) = try_correct(&arg, &valid, strict) {
+            if fixed.rule == CorrectionRule::NoColorExpansion {
+                // Expand --no-color → --color never
+                corrections.push(Correction {
+                    original: fixed.original,
+                    corrected: "--color never".to_string(),
+                    rule: CorrectionRule::NoColorExpansion,
+                    confidence: 1.0,
+                });
+                corrected.push("--color".to_string());
+                corrected.push("never".to_string());
+            } else {
                 let s = fixed.corrected.clone();
                 corrections.push(fixed);
                 corrected.push(s);
+            }
         } else {
             corrected.push(arg);
         }
@@ -440,13 +533,15 @@ pub fn correct_args(raw: Vec<String>, strict: bool) -> CorrectionResult {
     }
 }
 
-/// Phase A: Replace subcommand aliases with their canonical names.
+/// Phase A: Replace subcommand aliases with their canonical names, fuzzy-match
+/// typo'd subcommands, and detect flag-style subcommands (`--robot-docs`).
 ///
-/// Handles forms that can't be expressed as clap `alias`/`visible_alias`
+/// Three-step pipeline:
-/// (underscores, no-separator forms). Case-insensitive matching.
+/// - A1: Exact alias match (underscore/no-separator forms)
+/// - A2: Fuzzy subcommand match ("issuess" → "issues")
+/// - A3: Flag-as-subcommand ("--robot-docs" → "robot-docs")
 fn correct_subcommand(mut args: Vec<String>, corrections: &mut Vec<Correction>) -> Vec<String> {
-    // Find the subcommand position index, then check the alias map.
+    // Find the subcommand position index.
-    // Can't use iterators easily because we need to mutate args[i].
     let mut skip_next = false;
     let mut subcmd_idx = None;
     for (i, arg) in args.iter().enumerate().skip(1) {
@@ -466,8 +561,10 @@ fn correct_subcommand(mut args: Vec<String>, corrections: &mut Vec<Correction>)
         subcmd_idx = Some(i);
         break;
     }
-    if let Some(i) = subcmd_idx
+
-        && let Some((_, canonical)) = SUBCOMMAND_ALIASES
+    if let Some(i) = subcmd_idx {
+        // A1: Exact alias match (existing logic)
+        if let Some((_, canonical)) = SUBCOMMAND_ALIASES
             .iter()
             .find(|(alias, _)| alias.eq_ignore_ascii_case(&args[i]))
         {
@@ -479,6 +576,91 @@ fn correct_subcommand(mut args: Vec<String>, corrections: &mut Vec<Correction>)
             });
             args[i] = (*canonical).to_string();
         }
+        // A2: Fuzzy subcommand match — only if not already a canonical name
+        else {
+            let lower = args[i].to_lowercase();
+            if !CANONICAL_SUBCOMMANDS.contains(&lower.as_str()) {
+                // Guard: don't fuzzy-match words that look like misplaced global flags
+                // (e.g., "robot" should not match "robot-docs")
+                let as_flag = format!("--{lower}");
+                let is_flag_word = GLOBAL_FLAGS
+                    .iter()
+                    .any(|f| f.eq_ignore_ascii_case(&as_flag));
+
+                // Guard: don't fuzzy-match if it's a valid prefix of a canonical command
+                // (clap's infer_subcommands handles prefix resolution)
+                let is_prefix = CANONICAL_SUBCOMMANDS
+                    .iter()
+                    .any(|cmd| cmd.starts_with(&*lower) && *cmd != lower);
+
+                if !is_flag_word && !is_prefix {
+                    let best = CANONICAL_SUBCOMMANDS
+                        .iter()
+                        .map(|cmd| (*cmd, jaro_winkler(&lower, cmd)))
+                        .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal));
+
+                    if let Some((cmd, score)) = best
+                        && score >= FUZZY_SUBCMD_THRESHOLD
+                    {
+                        corrections.push(Correction {
+                            original: args[i].clone(),
+                            corrected: cmd.to_string(),
+                            rule: CorrectionRule::SubcommandFuzzy,
+                            confidence: score,
+                        });
+                        args[i] = cmd.to_string();
+                    }
+                }
+            }
+        }
+    } else {
+        // A3: No subcommand detected — check for flag-style subcommands.
+        // Agents sometimes type `--robot-docs` or `--generate-docs` as flags.
+        let mut flag_as_subcmd: Option<(usize, String)> = None;
+        let mut flag_skip = false;
+        for (i, arg) in args.iter().enumerate().skip(1) {
+            if flag_skip {
+                flag_skip = false;
+                continue;
+            }
+            if !arg.starts_with("--") || arg.contains('=') {
+                continue;
+            }
+
+            let arg_lower = arg.to_lowercase();
+            // Skip clap built-in flags (--help, --version)
+            if CLAP_BUILTINS
+                .iter()
+                .any(|b| b.eq_ignore_ascii_case(&arg_lower))
+            {
+                continue;
+            }
+            // Skip known global flags
+            if GLOBAL_FLAGS.iter().any(|f| f.to_lowercase() == arg_lower) {
+                if matches!(arg_lower.as_str(), "--config" | "--color" | "--log-format") {
+                    flag_skip = true;
+                }
+                continue;
+            }
+
+            let stripped = arg_lower[2..].to_string();
+            if CANONICAL_SUBCOMMANDS.contains(&stripped.as_str()) {
+                flag_as_subcmd = Some((i, stripped));
+                break;
+            }
+        }
+
+        if let Some((i, subcmd)) = flag_as_subcmd {
+            corrections.push(Correction {
+                original: args[i].clone(),
+                corrected: subcmd.clone(),
+                rule: CorrectionRule::FlagAsSubcommand,
+                confidence: 1.0,
+            });
+            args[i] = subcmd;
+        }
+    }
+
     args
 }
 
@@ -610,12 +792,27 @@ const CLAP_BUILTINS: &[&str] = &["--help", "--version"];
 ///
 /// When `strict` is true, fuzzy matching is disabled — only deterministic
 /// corrections (single-dash fix, case normalization) are applied.
+///
+/// Special case: `--no-color` is rewritten to `--color never` by returning
+/// the `--color` correction and letting the caller handle arg insertion.
+/// However, since we correct one arg at a time, we use `NoColorExpansion`
+/// to signal that the next phase should insert `never` after this arg.
 fn try_correct(arg: &str, valid_flags: &[&str], strict: bool) -> Option<Correction> {
     // Only attempt correction on flag-like args (starts with `-`)
     if !arg.starts_with('-') {
         return None;
     }
 
+    // Special case: --no-color → --color never (common agent/user expectation)
+    if arg.eq_ignore_ascii_case("--no-color") {
+        return Some(Correction {
+            original: arg.to_string(),
+            corrected: "--no-color".to_string(), // sentinel; expanded in correct_args
+            rule: CorrectionRule::NoColorExpansion,
+            confidence: 1.0,
+        });
+    }
+
     // B2: Never correct clap built-in flags (--help, --version)
     let flag_part_for_builtin = if let Some(eq_pos) = arg.find('=') {
         &arg[..eq_pos]
@@ -765,9 +962,21 @@ fn try_correct(arg: &str, valid_flags: &[&str], strict: bool) -> Option<Correcti
 }
 
 /// Find the best fuzzy match among valid flags for a given (lowercased) input.
+///
+/// Applies a length guard to prevent short candidates (e.g. `--for`, 5 chars
+/// including dashes) from inflating Jaro-Winkler scores against long inputs.
+/// When the input is more than 40% longer than a candidate, that candidate is
+/// excluded from fuzzy consideration (it can still match via prefix rule).
 fn best_fuzzy_match<'a>(input: &str, valid_flags: &[&'a str]) -> Option<(&'a str, f64)> {
     valid_flags
         .iter()
+        .filter(|&&flag| {
+            // Guard: skip short candidates when input is much longer.
+            // e.g. "--foobar" (8 chars) should not fuzzy-match "--for" (5 chars)
+            // Ratio: input must be within 1.4x the candidate length.
+            let max_input_len = (flag.len() as f64 * 1.4) as usize;
+            input.len() <= max_input_len
+        })
         .map(|&flag| (flag, jaro_winkler(input, flag)))
         .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal))
 }
@@ -827,6 +1036,18 @@ pub fn format_teaching_note(correction: &Correction) -> String {
                 correction.corrected, correction.original
             )
         }
+        CorrectionRule::SubcommandFuzzy => {
+            format!(
+                "Correct command spelling: lore {} (not lore {})",
+                correction.corrected, correction.original
+            )
+        }
+        CorrectionRule::FlagAsSubcommand => {
+            format!(
+                "Commands are positional, not flags: lore {} (not lore --{})",
+                correction.corrected, correction.corrected
+            )
+        }
         CorrectionRule::ValueNormalization => {
             format!(
                 "Values are lowercase: {} (not {})",
@@ -845,6 +1066,9 @@ pub fn format_teaching_note(correction: &Correction) -> String {
                 correction.corrected, correction.original
             )
         }
+        CorrectionRule::NoColorExpansion => {
+            "Use `--color never` instead of `--no-color`".to_string()
+        }
     }
 }
 
@@ -1285,6 +1509,53 @@ mod tests {
         assert!(note.contains("full flag name"));
     }
 
+    // ---- --no-color expansion ----
+
+    #[test]
+    fn no_color_expands_to_color_never() {
+        let result = correct_args(args("lore --no-color health"), false);
+        assert_eq!(result.corrections.len(), 1);
+        assert_eq!(result.corrections[0].rule, CorrectionRule::NoColorExpansion);
+        assert_eq!(result.args, args("lore --color never health"));
+    }
+
+    #[test]
+    fn no_color_case_insensitive() {
+        let result = correct_args(args("lore --No-Color issues"), false);
+        assert_eq!(result.corrections.len(), 1);
+        assert_eq!(result.args, args("lore --color never issues"));
+    }
+
+    #[test]
+    fn no_color_with_robot_mode() {
+        let result = correct_args(args("lore --robot --no-color health"), true);
+        assert_eq!(result.corrections.len(), 1);
+        assert_eq!(result.args, args("lore --robot --color never health"));
+    }
+
+    // ---- Fuzzy matching length guard ----
+
+    #[test]
+    fn foobar_does_not_match_for() {
+        // --foobar (8 chars) should NOT fuzzy-match --for (5 chars)
+        let result = correct_args(args("lore count --foobar issues"), false);
+        assert!(
+            !result.corrections.iter().any(|c| c.corrected == "--for"),
+            "expected --foobar not to match --for"
+        );
+    }
+
+    #[test]
+    fn fro_still_matches_for() {
+        // --fro (5 chars) is short enough to fuzzy-match --for (5 chars)
+        // and also qualifies as a prefix match
+        let result = correct_args(args("lore count --fro issues"), false);
+        assert!(
+            result.corrections.iter().any(|c| c.corrected == "--for"),
+            "expected --fro to match --for"
+        );
+    }
+
     // ---- Post-clap suggestion helpers ----
 
     #[test]
@@ -1340,6 +1611,198 @@ mod tests {
         assert_eq!(detect_subcommand(&args("lore --robot")), None);
     }
 
+    // ---- Fuzzy subcommand matching (A2) ----
+
+    #[test]
+    fn fuzzy_subcommand_issuess() {
+        let result = correct_args(args("lore --robot issuess -n 10"), false);
+        assert!(
+            result
+                .corrections
+                .iter()
+                .any(|c| c.rule == CorrectionRule::SubcommandFuzzy && c.corrected == "issues"),
+            "expected 'issuess' to fuzzy-match 'issues'"
+        );
+        assert!(result.args.contains(&"issues".to_string()));
+    }
+
+    #[test]
+    fn fuzzy_subcommand_timline() {
+        let result = correct_args(args("lore timline \"auth\""), false);
+        assert!(
+            result.corrections.iter().any(|c| c.corrected == "timeline"),
+            "expected 'timline' to fuzzy-match 'timeline'"
+        );
+    }
+
+    #[test]
+    fn fuzzy_subcommand_serach() {
+        let result = correct_args(args("lore --robot serach \"auth bug\""), false);
+        assert!(
+            result.corrections.iter().any(|c| c.corrected == "search"),
+            "expected 'serach' to fuzzy-match 'search'"
+        );
+    }
+
+    #[test]
+    fn fuzzy_subcommand_already_valid_untouched() {
+        let result = correct_args(args("lore issues -n 10"), false);
+        assert!(
+            !result
+                .corrections
+                .iter()
+                .any(|c| c.rule == CorrectionRule::SubcommandFuzzy)
+        );
+    }
+
+    #[test]
+    fn fuzzy_subcommand_robot_not_matched_to_robot_docs() {
+        // "robot" looks like a misplaced --robot flag, not a typo for "robot-docs"
+        let result = correct_args(args("lore robot issues"), false);
+        assert!(
+            !result
+                .corrections
+                .iter()
+                .any(|c| c.rule == CorrectionRule::SubcommandFuzzy),
+            "expected 'robot' NOT to fuzzy-match 'robot-docs' (it's a misplaced flag)"
+        );
+    }
+
+    #[test]
+    fn fuzzy_subcommand_prefix_deferred_to_clap() {
+        // "iss" is a prefix of "issues" — clap's infer_subcommands handles this
+        let result = correct_args(args("lore iss -n 10"), false);
+        assert!(
+            !result
+                .corrections
+                .iter()
+                .any(|c| c.rule == CorrectionRule::SubcommandFuzzy),
+            "expected prefix 'iss' NOT to be fuzzy-matched (clap handles it)"
+        );
+    }
+
+    #[test]
+    fn fuzzy_subcommand_wildly_wrong_not_matched() {
+        let result = correct_args(args("lore xyzzyplugh"), false);
+        assert!(
+            !result
+                .corrections
+                .iter()
+                .any(|c| c.rule == CorrectionRule::SubcommandFuzzy),
+            "expected gibberish NOT to fuzzy-match any command"
+        );
+    }
+
+    // ---- Flag-as-subcommand (A3) ----
+
+    #[test]
+    fn flag_as_subcommand_robot_docs() {
+        let result = correct_args(args("lore --robot-docs"), false);
+        assert!(
+            result
+                .corrections
+                .iter()
+                .any(|c| c.rule == CorrectionRule::FlagAsSubcommand && c.corrected == "robot-docs"),
+            "expected '--robot-docs' to be corrected to 'robot-docs'"
+        );
+        assert!(result.args.contains(&"robot-docs".to_string()));
+    }
+
+    #[test]
+    fn flag_as_subcommand_generate_docs() {
+        let result = correct_args(args("lore --generate-docs"), false);
+        assert!(
+            result
+                .corrections
+                .iter()
+                .any(|c| c.corrected == "generate-docs"),
+            "expected '--generate-docs' to be corrected to 'generate-docs'"
+        );
+    }
+
+    #[test]
+    fn flag_as_subcommand_with_robot_flag() {
+        // `lore --robot --robot-docs` — --robot is a valid global flag, --robot-docs is not
+        let result = correct_args(args("lore --robot --robot-docs"), false);
+        assert!(
+            result
+                .corrections
+                .iter()
+                .any(|c| c.corrected == "robot-docs"),
+        );
+        assert_eq!(result.args, args("lore --robot robot-docs"));
+    }
+
+    #[test]
+    fn flag_as_subcommand_does_not_touch_real_flags() {
+        // --robot is a real global flag, should NOT be rewritten to "robot"
+        let result = correct_args(args("lore --robot issues"), false);
+        assert!(
+            !result
+                .corrections
+                .iter()
+                .any(|c| c.rule == CorrectionRule::FlagAsSubcommand),
+        );
+    }
+
+    #[test]
+    fn flag_as_subcommand_not_triggered_when_subcommand_present() {
+        // A subcommand IS detected, so A3 shouldn't activate
+        let result = correct_args(args("lore issues --robot-docs"), false);
+        assert!(
+            !result
+                .corrections
+                .iter()
+                .any(|c| c.rule == CorrectionRule::FlagAsSubcommand),
+            "expected A3 not to trigger when subcommand is already present"
+        );
+    }
+
+    // ---- Teaching notes for new rules ----
+
+    #[test]
+    fn teaching_note_subcommand_fuzzy() {
+        let c = Correction {
+            original: "issuess".to_string(),
+            corrected: "issues".to_string(),
+            rule: CorrectionRule::SubcommandFuzzy,
+            confidence: 0.92,
+        };
+        let note = format_teaching_note(&c);
+        assert!(note.contains("spelling"));
+        assert!(note.contains("issues"));
+    }
+
+    #[test]
+    fn teaching_note_flag_as_subcommand() {
+        let c = Correction {
+            original: "--robot-docs".to_string(),
+            corrected: "robot-docs".to_string(),
+            rule: CorrectionRule::FlagAsSubcommand,
+            confidence: 1.0,
+        };
+        let note = format_teaching_note(&c);
+        assert!(note.contains("positional"));
+        assert!(note.contains("robot-docs"));
+    }
+
+    // ---- Canonical subcommands registry drift test ----
+
+    #[test]
+    fn canonical_subcommands_covers_clap() {
+        use clap::CommandFactory;
+        let cmd = crate::cli::Cli::command();
+
+        for sub in cmd.get_subcommands() {
+            let name = sub.get_name();
+            assert!(
+                CANONICAL_SUBCOMMANDS.contains(&name),
+                "Clap subcommand '{name}' is missing from CANONICAL_SUBCOMMANDS. \
+                 Add it to autocorrect.rs."
+            );
+        }
+    }
+
     // ---- Registry drift test ----
     // This test uses clap introspection to verify our static registry covers
     // all long flags defined in the Cli struct.

src/cli/commands/auth_test.rs

@@ -1,5 +1,5 @@
 use crate::core::config::Config;
-use crate::core::error::{LoreError, Result};
+use crate::core::error::Result;
 use crate::gitlab::GitLabClient;
 
 pub struct AuthTestResult {
@@ -11,17 +11,7 @@ pub struct AuthTestResult {
 pub async fn run_auth_test(config_path: Option<&str>) -> Result<AuthTestResult> {
     let config = Config::load(config_path)?;
 
-    let token = std::env::var(&config.gitlab.token_env_var)
+    let token = config.gitlab.resolve_token()?;
-        .map(|t| t.trim().to_string())
-        .map_err(|_| LoreError::TokenNotSet {
-            env_var: config.gitlab.token_env_var.clone(),
-        })?;
-
-    if token.is_empty() {
-        return Err(LoreError::TokenNotSet {
-            env_var: config.gitlab.token_env_var.clone(),
-        });
-    }
 
     let client = GitLabClient::new(&config.gitlab.base_url, &token, None);
 

src/cli/commands/count.rs

@@ -6,8 +6,8 @@ use crate::Config;
 use crate::cli::robot::RobotMeta;
 use crate::core::db::create_connection;
 use crate::core::error::Result;
-use crate::core::events_db::{self, EventCounts};
 use crate::core::paths::get_db_path;
+use crate::ingestion::storage::events::{EventCounts, count_events};
 
 pub struct CountResult {
     pub entity: String,
@@ -208,7 +208,7 @@ struct CountJsonBreakdown {
 pub fn run_count_events(config: &Config) -> Result<EventCounts> {
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
-    events_db::count_events(&conn)
+    count_events(&conn)
 }
 
 #[derive(Serialize)]
@@ -254,10 +254,13 @@ pub fn print_event_count_json(counts: &EventCounts, elapsed_ms: u64) {
             },
             total: counts.total(),
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
 
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 pub fn print_event_count(counts: &EventCounts) {
@@ -322,10 +325,13 @@ pub fn print_count_json(result: &CountResult, elapsed_ms: u64) {
             system_excluded: result.system_count,
             breakdown,
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
 
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 pub fn print_count(result: &CountResult) {

src/cli/commands/cron.rs

@@ -0,0 +1,292 @@
+use serde::Serialize;
+
+use crate::Config;
+use crate::cli::render::Theme;
+use crate::cli::robot::RobotMeta;
+use crate::core::cron::{
+    CronInstallResult, CronStatusResult, CronUninstallResult, cron_status, install_cron,
+    uninstall_cron,
+};
+use crate::core::db::create_connection;
+use crate::core::error::Result;
+use crate::core::paths::get_db_path;
+use crate::core::time::ms_to_iso;
+
+// ── install ──
+
+pub fn run_cron_install(interval_minutes: u32) -> Result<CronInstallResult> {
+    install_cron(interval_minutes)
+}
+
+pub fn print_cron_install(result: &CronInstallResult) {
+    if result.replaced {
+        println!(
+            "  {} cron entry updated (was already installed)",
+            Theme::success().render("Updated")
+        );
+    } else {
+        println!(
+            "  {} cron entry installed",
+            Theme::success().render("Installed")
+        );
+    }
+    println!();
+    println!("  {} {}", Theme::dim().render("entry:"), result.entry);
+    println!(
+        "  {} every {} minutes",
+        Theme::dim().render("interval:"),
+        result.interval_minutes
+    );
+    println!(
+        "  {} {}",
+        Theme::dim().render("log:"),
+        result.log_path.display()
+    );
+
+    if cfg!(target_os = "macos") {
+        println!();
+        println!(
+            "  {} On macOS, the terminal running cron may need",
+            Theme::warning().render("Note:")
+        );
+        println!("        Full Disk Access in System Settings > Privacy & Security.");
+    }
+    println!();
+}
+
+#[derive(Serialize)]
+struct CronInstallJson {
+    ok: bool,
+    data: CronInstallData,
+    meta: RobotMeta,
+}
+
+#[derive(Serialize)]
+struct CronInstallData {
+    action: &'static str,
+    entry: String,
+    interval_minutes: u32,
+    log_path: String,
+    replaced: bool,
+}
+
+pub fn print_cron_install_json(result: &CronInstallResult, elapsed_ms: u64) {
+    let output = CronInstallJson {
+        ok: true,
+        data: CronInstallData {
+            action: "install",
+            entry: result.entry.clone(),
+            interval_minutes: result.interval_minutes,
+            log_path: result.log_path.display().to_string(),
+            replaced: result.replaced,
+        },
+        meta: RobotMeta::new(elapsed_ms),
+    };
+    if let Ok(json) = serde_json::to_string(&output) {
+        println!("{json}");
+    }
+}
+
+// ── uninstall ──
+
+pub fn run_cron_uninstall() -> Result<CronUninstallResult> {
+    uninstall_cron()
+}
+
+pub fn print_cron_uninstall(result: &CronUninstallResult) {
+    if result.was_installed {
+        println!(
+            "  {} cron entry removed",
+            Theme::success().render("Removed")
+        );
+    } else {
+        println!(
+            "  {} no lore-sync cron entry found",
+            Theme::dim().render("Nothing to remove:")
+        );
+    }
+    println!();
+}
+
+#[derive(Serialize)]
+struct CronUninstallJson {
+    ok: bool,
+    data: CronUninstallData,
+    meta: RobotMeta,
+}
+
+#[derive(Serialize)]
+struct CronUninstallData {
+    action: &'static str,
+    was_installed: bool,
+}
+
+pub fn print_cron_uninstall_json(result: &CronUninstallResult, elapsed_ms: u64) {
+    let output = CronUninstallJson {
+        ok: true,
+        data: CronUninstallData {
+            action: "uninstall",
+            was_installed: result.was_installed,
+        },
+        meta: RobotMeta::new(elapsed_ms),
+    };
+    if let Ok(json) = serde_json::to_string(&output) {
+        println!("{json}");
+    }
+}
+
+// ── status ──
+
+pub fn run_cron_status(config: &Config) -> Result<CronStatusInfo> {
+    let status = cron_status()?;
+
+    // Query last sync run from DB
+    let last_sync = get_last_sync_time(config).unwrap_or_default();
+
+    Ok(CronStatusInfo { status, last_sync })
+}
+
+pub struct CronStatusInfo {
+    pub status: CronStatusResult,
+    pub last_sync: Option<LastSyncInfo>,
+}
+
+pub struct LastSyncInfo {
+    pub started_at_iso: String,
+    pub status: String,
+}
+
+fn get_last_sync_time(config: &Config) -> Result<Option<LastSyncInfo>> {
+    let db_path = get_db_path(config.storage.db_path.as_deref());
+    if !db_path.exists() {
+        return Ok(None);
+    }
+    let conn = create_connection(&db_path)?;
+    let result = conn.query_row(
+        "SELECT started_at, status FROM sync_runs ORDER BY started_at DESC LIMIT 1",
+        [],
+        |row| {
+            let started_at: i64 = row.get(0)?;
+            let status: String = row.get(1)?;
+            Ok(LastSyncInfo {
+                started_at_iso: ms_to_iso(started_at),
+                status,
+            })
+        },
+    );
+    match result {
+        Ok(info) => Ok(Some(info)),
+        Err(rusqlite::Error::QueryReturnedNoRows) => Ok(None),
+        // Table may not exist if migrations haven't run yet
+        Err(rusqlite::Error::SqliteFailure(_, Some(ref msg))) if msg.contains("no such table") => {
+            Ok(None)
+        }
+        Err(e) => Err(e.into()),
+    }
+}
+
+pub fn print_cron_status(info: &CronStatusInfo) {
+    if info.status.installed {
+        println!(
+            "  {} lore-sync is installed in crontab",
+            Theme::success().render("Installed")
+        );
+        if let Some(interval) = info.status.interval_minutes {
+            println!(
+                "  {} every {} minutes",
+                Theme::dim().render("interval:"),
+                interval
+            );
+        }
+        if let Some(ref binary) = info.status.binary_path {
+            let label = if info.status.binary_mismatch {
+                Theme::warning().render("binary:")
+            } else {
+                Theme::dim().render("binary:")
+            };
+            println!("  {label} {binary}");
+            if info.status.binary_mismatch
+                && let Some(ref current) = info.status.current_binary
+            {
+                println!(
+                    "  {}",
+                    Theme::warning().render(&format!("  current binary is {current} (mismatch!)"))
+                );
+            }
+        }
+        if let Some(ref log) = info.status.log_path {
+            println!("  {} {}", Theme::dim().render("log:"), log.display());
+        }
+    } else {
+        println!(
+            "  {} lore-sync is not installed in crontab",
+            Theme::dim().render("Not installed:")
+        );
+        println!(
+            "  {} lore cron install",
+            Theme::dim().render("install with:")
+        );
+    }
+
+    if let Some(ref last) = info.last_sync {
+        println!(
+            "  {} {} ({})",
+            Theme::dim().render("last sync:"),
+            last.started_at_iso,
+            last.status
+        );
+    }
+    println!();
+}
+
+#[derive(Serialize)]
+struct CronStatusJson {
+    ok: bool,
+    data: CronStatusData,
+    meta: RobotMeta,
+}
+
+#[derive(Serialize)]
+struct CronStatusData {
+    installed: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    interval_minutes: Option<u32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    binary_path: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    current_binary: Option<String>,
+    binary_mismatch: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    log_path: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    cron_entry: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    last_sync_at: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    last_sync_status: Option<String>,
+}
+
+pub fn print_cron_status_json(info: &CronStatusInfo, elapsed_ms: u64) {
+    let output = CronStatusJson {
+        ok: true,
+        data: CronStatusData {
+            installed: info.status.installed,
+            interval_minutes: info.status.interval_minutes,
+            binary_path: info.status.binary_path.clone(),
+            current_binary: info.status.current_binary.clone(),
+            binary_mismatch: info.status.binary_mismatch,
+            log_path: info
+                .status
+                .log_path
+                .as_ref()
+                .map(|p| p.display().to_string()),
+            cron_entry: info.status.cron_entry.clone(),
+            last_sync_at: info.last_sync.as_ref().map(|s| s.started_at_iso.clone()),
+            last_sync_status: info.last_sync.as_ref().map(|s| s.status.clone()),
+        },
+        meta: RobotMeta::new(elapsed_ms),
+    };
+    if let Ok(json) = serde_json::to_string(&output) {
+        println!("{json}");
+    }
+}

src/cli/commands/doctor.rs

@@ -240,14 +240,14 @@ async fn check_gitlab(config: Option<&Config>) -> GitLabCheck {
         };
     };
 
-    let token = match std::env::var(&config.gitlab.token_env_var) {
+    let token = match config.gitlab.resolve_token() {
-        Ok(t) if !t.trim().is_empty() => t.trim().to_string(),
+        Ok(t) => t,
-        _ => {
+        Err(_) => {
             return GitLabCheck {
                 result: CheckResult {
                     status: CheckStatus::Error,
                     message: Some(format!(
-                        "{} not set in environment",
+                        "Token not set. Run 'lore token set' or export {}.",
                         config.gitlab.token_env_var
                     )),
                 },
@@ -257,6 +257,8 @@ async fn check_gitlab(config: Option<&Config>) -> GitLabCheck {
         }
     };
 
+    let source = config.gitlab.token_source().unwrap_or("unknown");
+
     let client = GitLabClient::new(&config.gitlab.base_url, &token, None);
 
     match client.get_current_user().await {
@@ -264,7 +266,7 @@ async fn check_gitlab(config: Option<&Config>) -> GitLabCheck {
             result: CheckResult {
                 status: CheckStatus::Ok,
                 message: Some(format!(
-                    "{} (authenticated as @{})",
+                    "{} (authenticated as @{}, token from {source})",
                     config.gitlab.base_url, user.username
                 )),
             },
@@ -383,25 +385,11 @@ async fn check_ollama(config: Option<&Config>) -> OllamaCheck {
     let base_url = &config.embedding.base_url;
     let model = &config.embedding.model;
 
-    let client = match reqwest::Client::builder()
+    let client = crate::http::Client::with_timeout(std::time::Duration::from_secs(2));
-        .timeout(std::time::Duration::from_secs(2))
+    let url = format!("{base_url}/api/tags");
-        .build()
-    {
-        Ok(client) => client,
-        Err(e) => {
-            return OllamaCheck {
-                result: CheckResult {
-                    status: CheckStatus::Warning,
-                    message: Some(format!("Failed to build HTTP client: {e}")),
-                },
-                url: Some(base_url.clone()),
-                model: Some(model.clone()),
-            };
-        }
-    };
 
-    match client.get(format!("{base_url}/api/tags")).send().await {
+    match client.get(&url, &[]).await {
-        Ok(response) if response.status().is_success() => {
+        Ok(response) if response.is_success() => {
             #[derive(serde::Deserialize)]
             struct TagsResponse {
                 models: Option<Vec<ModelInfo>>,
@@ -411,7 +399,7 @@ async fn check_ollama(config: Option<&Config>) -> OllamaCheck {
                 name: String,
             }
 
-            match response.json::<TagsResponse>().await {
+            match response.json::<TagsResponse>() {
                 Ok(data) => {
                     let models = data.models.unwrap_or_default();
                     let model_names: Vec<&str> = models
@@ -460,7 +448,7 @@ async fn check_ollama(config: Option<&Config>) -> OllamaCheck {
         Ok(response) => OllamaCheck {
             result: CheckResult {
                 status: CheckStatus::Warning,
-                message: Some(format!("Ollama responded with {}", response.status())),
+                message: Some(format!("Ollama responded with {}", response.status)),
             },
             url: Some(base_url.clone()),
             model: Some(model.clone()),

src/cli/commands/drift.rs

@@ -382,7 +382,7 @@ fn extract_drift_topics(description: &str, notes: &[NoteRow], drift_idx: usize)
     }
 
     let mut sorted: Vec<(String, usize)> = freq.into_iter().collect();
-    sorted.sort_by(|a, b| b.1.cmp(&a.1));
+    sorted.sort_by_key(|b| std::cmp::Reverse(b.1));
 
     sorted
         .into_iter()
@@ -468,7 +468,7 @@ pub fn print_drift_human(response: &DriftResponse) {
 }
 
 pub fn print_drift_json(response: &DriftResponse, elapsed_ms: u64) {
-    let meta = RobotMeta { elapsed_ms };
+    let meta = RobotMeta::new(elapsed_ms);
     let output = serde_json::json!({
         "ok": true,
         "data": response,

src/cli/commands/embed.rs

@@ -135,7 +135,10 @@ pub fn print_embed_json(result: &EmbedCommandResult, elapsed_ms: u64) {
     let output = EmbedJsonOutput {
         ok: true,
         data: result,
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }

src/cli/commands/file_history.rs

@@ -1,9 +1,11 @@
 use serde::Serialize;
 
+use tracing::info;
+
 use crate::Config;
 use crate::cli::render::{self, Icons, Theme};
 use crate::core::db::create_connection;
-use crate::core::error::Result;
+use crate::core::error::{LoreError, Result};
 use crate::core::file_history::resolve_rename_chain;
 use crate::core::paths::get_db_path;
 use crate::core::project::resolve_project;
@@ -46,6 +48,9 @@ pub struct FileHistoryResult {
     pub discussions: Vec<FileDiscussion>,
     pub total_mrs: usize,
     pub paths_searched: usize,
+    /// Diagnostic hints explaining why results may be empty.
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub hints: Vec<String>,
 }
 
 /// Run the file-history query.
@@ -77,6 +82,11 @@ pub fn run_file_history(
 
     let paths_searched = all_paths.len();
 
+    info!(
+        paths = paths_searched,
+        renames_followed, "file-history: resolved {} path(s) for '{}'", paths_searched, path
+    );
+
     // Build placeholders for IN clause
     let placeholders: Vec<String> = (0..all_paths.len())
         .map(|i| format!("?{}", i + 2))
@@ -135,14 +145,31 @@ pub fn run_file_history(
                 web_url: row.get(8)?,
             })
         })?
-        .filter_map(std::result::Result::ok)
+        .collect::<std::result::Result<Vec<_>, _>>()?;
-        .collect();
 
     let total_mrs = merge_requests.len();
 
+    info!(
+        mr_count = total_mrs,
+        "file-history: found {} MR(s) touching '{}'", total_mrs, path
+    );
+
     // Optionally fetch DiffNote discussions on this file
     let discussions = if include_discussions && !merge_requests.is_empty() {
-        fetch_file_discussions(&conn, &all_paths, project_id)?
+        let discs = fetch_file_discussions(&conn, &all_paths, project_id)?;
+        info!(
+            discussion_count = discs.len(),
+            "file-history: found {} discussion(s)",
+            discs.len()
+        );
+        discs
+    } else {
+        Vec::new()
+    };
+
+    // Build diagnostic hints when no results found
+    let hints = if total_mrs == 0 {
+        build_file_history_hints(&conn, project_id, &all_paths)?
     } else {
         Vec::new()
     };
@@ -155,6 +182,7 @@ pub fn run_file_history(
         discussions,
         total_mrs,
         paths_searched,
+        hints,
     })
 }
 
@@ -179,8 +207,7 @@ fn fetch_file_discussions(
          JOIN discussions d ON d.id = n.discussion_id \
          WHERE n.position_new_path IN ({in_clause}) {project_filter} \
            AND n.is_system = 0 \
-         ORDER BY n.created_at DESC \
+         ORDER BY n.created_at DESC"
-         LIMIT 50"
     );
 
     let mut stmt = conn.prepare(&sql)?;
@@ -210,12 +237,57 @@ fn fetch_file_discussions(
                 created_at_iso: ms_to_iso(created_at),
             })
         })?
-        .filter_map(std::result::Result::ok)
+        .collect::<std::result::Result<Vec<_>, _>>()?;
-        .collect();
 
     Ok(discussions)
 }
 
+/// Build diagnostic hints explaining why a file-history query returned no results.
+fn build_file_history_hints(
+    conn: &rusqlite::Connection,
+    project_id: Option<i64>,
+    paths: &[String],
+) -> Result<Vec<String>> {
+    let mut hints = Vec::new();
+
+    // Check if mr_file_changes has ANY rows for this project
+    let has_file_changes: bool = if let Some(pid) = project_id {
+        conn.query_row(
+            "SELECT EXISTS(SELECT 1 FROM mr_file_changes WHERE project_id = ?1 LIMIT 1)",
+            rusqlite::params![pid],
+            |row| row.get(0),
+        )?
+    } else {
+        conn.query_row(
+            "SELECT EXISTS(SELECT 1 FROM mr_file_changes LIMIT 1)",
+            [],
+            |row| row.get(0),
+        )?
+    };
+
+    if !has_file_changes {
+        hints.push(
+            "No MR file changes have been synced yet. Run 'lore sync' to fetch file change data."
+                .to_string(),
+        );
+        return Ok(hints);
+    }
+
+    // File changes exist but none match these paths
+    let path_list = paths
+        .iter()
+        .map(|p| format!("'{p}'"))
+        .collect::<Vec<_>>()
+        .join(", ");
+    hints.push(format!(
+        "Searched paths [{}] were not found in MR file changes. \
+         The file may predate the sync window or use a different path.",
+        path_list
+    ));
+
+    Ok(hints)
+}
+
 // ── Human output ────────────────────────────────────────────────────────────
 
 pub fn print_file_history(result: &FileHistoryResult) {
@@ -250,10 +322,16 @@ pub fn print_file_history(result: &FileHistoryResult) {
             Icons::info(),
             Theme::dim().render("No merge requests found touching this file.")
         );
+        if !result.renames_followed && result.rename_chain.len() == 1 {
             println!(
-            "  {}",
+                "  {} Searched: {}",
-            Theme::dim().render("Hint: Run 'lore sync' to fetch MR file changes.")
+                Icons::info(),
+                Theme::dim().render(&result.rename_chain[0])
             );
+        }
+        for hint in &result.hints {
+            println!("  {} {}", Icons::info(), Theme::dim().render(hint));
+        }
         println!();
         return;
     }
@@ -313,7 +391,7 @@ pub fn print_file_history(result: &FileHistoryResult) {
 
 // ── Robot (JSON) output ─────────────────────────────────────────────────────
 
-pub fn print_file_history_json(result: &FileHistoryResult, elapsed_ms: u64) {
+pub fn print_file_history_json(result: &FileHistoryResult, elapsed_ms: u64) -> Result<()> {
     let output = serde_json::json!({
         "ok": true,
         "data": {
@@ -327,8 +405,14 @@ pub fn print_file_history_json(result: &FileHistoryResult, elapsed_ms: u64) {
             "total_mrs": result.total_mrs,
             "renames_followed": result.renames_followed,
             "paths_searched": result.paths_searched,
+            "hints": if result.hints.is_empty() { None } else { Some(&result.hints) },
         }
     });
 
-    println!("{}", serde_json::to_string(&output).unwrap_or_default());
+    println!(
+        "{}",
+        serde_json::to_string(&output)
+            .map_err(|e| LoreError::Other(format!("JSON serialization failed: {e}")))?
+    );
+    Ok(())
 }

src/cli/commands/generate_docs.rs

@@ -257,9 +257,12 @@ pub fn print_generate_docs_json(result: &GenerateDocsResult, elapsed_ms: u64) {
             unchanged: result.unchanged,
             errored: result.errored,
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 #[cfg(test)]

src/cli/commands/ingest/mod.rs

@@ -0,0 +1,26 @@
+use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use crate::cli::render::Theme;
+use indicatif::{ProgressBar, ProgressStyle};
+use rusqlite::Connection;
+use serde::Serialize;
+
+use tracing::Instrument;
+
+use crate::Config;
+use crate::cli::robot::RobotMeta;
+use crate::core::db::create_connection;
+use crate::core::error::{LoreError, Result};
+use crate::core::lock::{AppLock, LockOptions};
+use crate::core::paths::get_db_path;
+use crate::core::project::resolve_project;
+use crate::core::shutdown::ShutdownSignal;
+use crate::gitlab::GitLabClient;
+use crate::ingestion::{
+    IngestMrProjectResult, IngestProjectResult, ProgressEvent, ingest_project_issues_with_progress,
+    ingest_project_merge_requests_with_progress,
+};
+
+include!("run.rs");
+include!("render.rs");

src/cli/commands/ingest/render.rs

@@ -0,0 +1,331 @@
+fn print_issue_project_summary(path: &str, result: &IngestProjectResult) {
+    let labels_str = if result.labels_created > 0 {
+        format!(", {} new labels", result.labels_created)
+    } else {
+        String::new()
+    };
+
+    println!(
+        "  {}: {} issues fetched{}",
+        Theme::info().render(path),
+        result.issues_upserted,
+        labels_str
+    );
+
+    if result.issues_synced_discussions > 0 {
+        println!(
+            "    {} issues -> {} discussions, {} notes",
+            result.issues_synced_discussions, result.discussions_fetched, result.notes_upserted
+        );
+    }
+
+    if result.issues_skipped_discussion_sync > 0 {
+        println!(
+            "    {} unchanged issues (discussion sync skipped)",
+            Theme::dim().render(&result.issues_skipped_discussion_sync.to_string())
+        );
+    }
+}
+
+fn print_mr_project_summary(path: &str, result: &IngestMrProjectResult) {
+    let labels_str = if result.labels_created > 0 {
+        format!(", {} new labels", result.labels_created)
+    } else {
+        String::new()
+    };
+
+    let assignees_str = if result.assignees_linked > 0 || result.reviewers_linked > 0 {
+        format!(
+            ", {} assignees, {} reviewers",
+            result.assignees_linked, result.reviewers_linked
+        )
+    } else {
+        String::new()
+    };
+
+    println!(
+        "  {}: {} MRs fetched{}{}",
+        Theme::info().render(path),
+        result.mrs_upserted,
+        labels_str,
+        assignees_str
+    );
+
+    if result.mrs_synced_discussions > 0 {
+        let diffnotes_str = if result.diffnotes_count > 0 {
+            format!(" ({} diff notes)", result.diffnotes_count)
+        } else {
+            String::new()
+        };
+        println!(
+            "    {} MRs -> {} discussions, {} notes{}",
+            result.mrs_synced_discussions,
+            result.discussions_fetched,
+            result.notes_upserted,
+            diffnotes_str
+        );
+    }
+
+    if result.mrs_skipped_discussion_sync > 0 {
+        println!(
+            "    {} unchanged MRs (discussion sync skipped)",
+            Theme::dim().render(&result.mrs_skipped_discussion_sync.to_string())
+        );
+    }
+}
+
+#[derive(Serialize)]
+struct IngestJsonOutput {
+    ok: bool,
+    data: IngestJsonData,
+    meta: RobotMeta,
+}
+
+#[derive(Serialize)]
+struct IngestJsonData {
+    resource_type: String,
+    projects_synced: usize,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    issues: Option<IngestIssueStats>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    merge_requests: Option<IngestMrStats>,
+    labels_created: usize,
+    discussions_fetched: usize,
+    notes_upserted: usize,
+    resource_events_fetched: usize,
+    resource_events_failed: usize,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    status_enrichment: Vec<StatusEnrichmentJson>,
+    status_enrichment_errors: usize,
+}
+
+#[derive(Serialize)]
+struct StatusEnrichmentJson {
+    mode: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    reason: Option<String>,
+    seen: usize,
+    enriched: usize,
+    cleared: usize,
+    without_widget: usize,
+    partial_errors: usize,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    first_partial_error: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    error: Option<String>,
+}
+
+#[derive(Serialize)]
+struct IngestIssueStats {
+    fetched: usize,
+    upserted: usize,
+    synced_discussions: usize,
+    skipped_discussion_sync: usize,
+}
+
+#[derive(Serialize)]
+struct IngestMrStats {
+    fetched: usize,
+    upserted: usize,
+    synced_discussions: usize,
+    skipped_discussion_sync: usize,
+    assignees_linked: usize,
+    reviewers_linked: usize,
+    diffnotes_count: usize,
+}
+
+pub fn print_ingest_summary_json(result: &IngestResult, elapsed_ms: u64) {
+    let (issues, merge_requests) = if result.resource_type == "issues" {
+        (
+            Some(IngestIssueStats {
+                fetched: result.issues_fetched,
+                upserted: result.issues_upserted,
+                synced_discussions: result.issues_synced_discussions,
+                skipped_discussion_sync: result.issues_skipped_discussion_sync,
+            }),
+            None,
+        )
+    } else {
+        (
+            None,
+            Some(IngestMrStats {
+                fetched: result.mrs_fetched,
+                upserted: result.mrs_upserted,
+                synced_discussions: result.mrs_synced_discussions,
+                skipped_discussion_sync: result.mrs_skipped_discussion_sync,
+                assignees_linked: result.assignees_linked,
+                reviewers_linked: result.reviewers_linked,
+                diffnotes_count: result.diffnotes_count,
+            }),
+        )
+    };
+
+    let status_enrichment: Vec<StatusEnrichmentJson> = result
+        .status_enrichment_projects
+        .iter()
+        .map(|p| StatusEnrichmentJson {
+            mode: p.mode.clone(),
+            reason: p.reason.clone(),
+            seen: p.seen,
+            enriched: p.enriched,
+            cleared: p.cleared,
+            without_widget: p.without_widget,
+            partial_errors: p.partial_errors,
+            first_partial_error: p.first_partial_error.clone(),
+            error: p.error.clone(),
+        })
+        .collect();
+
+    let output = IngestJsonOutput {
+        ok: true,
+        data: IngestJsonData {
+            resource_type: result.resource_type.clone(),
+            projects_synced: result.projects_synced,
+            issues,
+            merge_requests,
+            labels_created: result.labels_created,
+            discussions_fetched: result.discussions_fetched,
+            notes_upserted: result.notes_upserted,
+            resource_events_fetched: result.resource_events_fetched,
+            resource_events_failed: result.resource_events_failed,
+            status_enrichment,
+            status_enrichment_errors: result.status_enrichment_errors,
+        },
+        meta: RobotMeta::new(elapsed_ms),
+    };
+
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
+}
+
+pub fn print_ingest_summary(result: &IngestResult) {
+    println!();
+
+    if result.resource_type == "issues" {
+        println!(
+            "{}",
+            Theme::success().render(&format!(
+                "Total: {} issues, {} discussions, {} notes",
+                result.issues_upserted, result.discussions_fetched, result.notes_upserted
+            ))
+        );
+
+        if result.issues_skipped_discussion_sync > 0 {
+            println!(
+                "{}",
+                Theme::dim().render(&format!(
+                    "Skipped discussion sync for {} unchanged issues.",
+                    result.issues_skipped_discussion_sync
+                ))
+            );
+        }
+    } else {
+        let diffnotes_str = if result.diffnotes_count > 0 {
+            format!(" ({} diff notes)", result.diffnotes_count)
+        } else {
+            String::new()
+        };
+
+        println!(
+            "{}",
+            Theme::success().render(&format!(
+                "Total: {} MRs, {} discussions, {} notes{}",
+                result.mrs_upserted,
+                result.discussions_fetched,
+                result.notes_upserted,
+                diffnotes_str
+            ))
+        );
+
+        if result.mrs_skipped_discussion_sync > 0 {
+            println!(
+                "{}",
+                Theme::dim().render(&format!(
+                    "Skipped discussion sync for {} unchanged MRs.",
+                    result.mrs_skipped_discussion_sync
+                ))
+            );
+        }
+    }
+
+    if result.resource_events_fetched > 0 || result.resource_events_failed > 0 {
+        println!(
+            "  Resource events: {} fetched{}",
+            result.resource_events_fetched,
+            if result.resource_events_failed > 0 {
+                format!(", {} failed", result.resource_events_failed)
+            } else {
+                String::new()
+            }
+        );
+    }
+}
+
+pub fn print_dry_run_preview(preview: &DryRunPreview) {
+    println!(
+        "{} {}",
+        Theme::info().bold().render("Dry Run Preview"),
+        Theme::warning().render("(no changes will be made)")
+    );
+    println!();
+
+    let type_label = if preview.resource_type == "issues" {
+        "issues"
+    } else {
+        "merge requests"
+    };
+
+    println!("  Resource type: {}", Theme::bold().render(type_label));
+    println!(
+        "  Sync mode: {}",
+        if preview.sync_mode == "full" {
+            Theme::warning().render("full (all data will be re-fetched)")
+        } else {
+            Theme::success().render("incremental (only changes since last sync)")
+        }
+    );
+    println!("  Projects: {}", preview.projects.len());
+    println!();
+
+    println!("{}", Theme::info().bold().render("Projects to sync:"));
+    for project in &preview.projects {
+        let sync_status = if !project.has_cursor {
+            Theme::warning().render("initial sync")
+        } else {
+            Theme::success().render("incremental")
+        };
+
+        println!(
+            "  {} ({})",
+            Theme::bold().render(&project.path),
+            sync_status
+        );
+        println!("    Existing {}: {}", type_label, project.existing_count);
+
+        if let Some(ref last_synced) = project.last_synced {
+            println!("    Last synced: {}", last_synced);
+        }
+    }
+}
+
+#[derive(Serialize)]
+struct DryRunJsonOutput {
+    ok: bool,
+    dry_run: bool,
+    data: DryRunPreview,
+}
+
+pub fn print_dry_run_preview_json(preview: &DryRunPreview) {
+    let output = DryRunJsonOutput {
+        ok: true,
+        dry_run: true,
+        data: preview.clone(),
+    };
+
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
+}

src/cli/commands/ingest/run.rs

@@ -1,27 +1,3 @@
-use std::sync::Arc;
-use std::sync::atomic::{AtomicUsize, Ordering};
-
-use crate::cli::render::Theme;
-use indicatif::{ProgressBar, ProgressStyle};
-use rusqlite::Connection;
-use serde::Serialize;
-
-use tracing::Instrument;
-
-use crate::Config;
-use crate::cli::robot::RobotMeta;
-use crate::core::db::create_connection;
-use crate::core::error::{LoreError, Result};
-use crate::core::lock::{AppLock, LockOptions};
-use crate::core::paths::get_db_path;
-use crate::core::project::resolve_project;
-use crate::core::shutdown::ShutdownSignal;
-use crate::gitlab::GitLabClient;
-use crate::ingestion::{
-    IngestMrProjectResult, IngestProjectResult, ProgressEvent, ingest_project_issues_with_progress,
-    ingest_project_merge_requests_with_progress,
-};
-
 #[derive(Default)]
 pub struct IngestResult {
     pub resource_type: String,
@@ -293,16 +269,13 @@ async fn run_ingest_inner(
     );
     lock.acquire(force)?;
 
-    let token =
+    let token = config.gitlab.resolve_token()?;
-        std::env::var(&config.gitlab.token_env_var).map_err(|_| LoreError::TokenNotSet {
-            env_var: config.gitlab.token_env_var.clone(),
-        })?;
 
-    let client = GitLabClient::new(
+    let client = Arc::new(GitLabClient::new(
         &config.gitlab.base_url,
         &token,
         Some(config.sync.requests_per_second),
-    );
+    ));
 
     let projects = get_projects_to_sync(&conn, &config.projects, project_filter)?;
 
@@ -379,7 +352,7 @@ async fn run_ingest_inner(
 
     let project_results: Vec<Result<ProjectIngestOutcome>> = stream::iter(projects.iter())
         .map(|(local_project_id, gitlab_project_id, path)| {
-            let client = client.clone();
+            let client = Arc::clone(&client);
             let db_path = db_path.clone();
             let config = config.clone();
             let resource_type = resource_type_owned.clone();
@@ -786,328 +759,3 @@ fn get_projects_to_sync(
     Ok(projects)
 }
 
-fn print_issue_project_summary(path: &str, result: &IngestProjectResult) {
-    let labels_str = if result.labels_created > 0 {
-        format!(", {} new labels", result.labels_created)
-    } else {
-        String::new()
-    };
-
-    println!(
-        "  {}: {} issues fetched{}",
-        Theme::info().render(path),
-        result.issues_upserted,
-        labels_str
-    );
-
-    if result.issues_synced_discussions > 0 {
-        println!(
-            "    {} issues -> {} discussions, {} notes",
-            result.issues_synced_discussions, result.discussions_fetched, result.notes_upserted
-        );
-    }
-
-    if result.issues_skipped_discussion_sync > 0 {
-        println!(
-            "    {} unchanged issues (discussion sync skipped)",
-            Theme::dim().render(&result.issues_skipped_discussion_sync.to_string())
-        );
-    }
-}
-
-fn print_mr_project_summary(path: &str, result: &IngestMrProjectResult) {
-    let labels_str = if result.labels_created > 0 {
-        format!(", {} new labels", result.labels_created)
-    } else {
-        String::new()
-    };
-
-    let assignees_str = if result.assignees_linked > 0 || result.reviewers_linked > 0 {
-        format!(
-            ", {} assignees, {} reviewers",
-            result.assignees_linked, result.reviewers_linked
-        )
-    } else {
-        String::new()
-    };
-
-    println!(
-        "  {}: {} MRs fetched{}{}",
-        Theme::info().render(path),
-        result.mrs_upserted,
-        labels_str,
-        assignees_str
-    );
-
-    if result.mrs_synced_discussions > 0 {
-        let diffnotes_str = if result.diffnotes_count > 0 {
-            format!(" ({} diff notes)", result.diffnotes_count)
-        } else {
-            String::new()
-        };
-        println!(
-            "    {} MRs -> {} discussions, {} notes{}",
-            result.mrs_synced_discussions,
-            result.discussions_fetched,
-            result.notes_upserted,
-            diffnotes_str
-        );
-    }
-
-    if result.mrs_skipped_discussion_sync > 0 {
-        println!(
-            "    {} unchanged MRs (discussion sync skipped)",
-            Theme::dim().render(&result.mrs_skipped_discussion_sync.to_string())
-        );
-    }
-}
-
-#[derive(Serialize)]
-struct IngestJsonOutput {
-    ok: bool,
-    data: IngestJsonData,
-    meta: RobotMeta,
-}
-
-#[derive(Serialize)]
-struct IngestJsonData {
-    resource_type: String,
-    projects_synced: usize,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    issues: Option<IngestIssueStats>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    merge_requests: Option<IngestMrStats>,
-    labels_created: usize,
-    discussions_fetched: usize,
-    notes_upserted: usize,
-    resource_events_fetched: usize,
-    resource_events_failed: usize,
-    #[serde(skip_serializing_if = "Vec::is_empty")]
-    status_enrichment: Vec<StatusEnrichmentJson>,
-    status_enrichment_errors: usize,
-}
-
-#[derive(Serialize)]
-struct StatusEnrichmentJson {
-    mode: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    reason: Option<String>,
-    seen: usize,
-    enriched: usize,
-    cleared: usize,
-    without_widget: usize,
-    partial_errors: usize,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    first_partial_error: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    error: Option<String>,
-}
-
-#[derive(Serialize)]
-struct IngestIssueStats {
-    fetched: usize,
-    upserted: usize,
-    synced_discussions: usize,
-    skipped_discussion_sync: usize,
-}
-
-#[derive(Serialize)]
-struct IngestMrStats {
-    fetched: usize,
-    upserted: usize,
-    synced_discussions: usize,
-    skipped_discussion_sync: usize,
-    assignees_linked: usize,
-    reviewers_linked: usize,
-    diffnotes_count: usize,
-}
-
-pub fn print_ingest_summary_json(result: &IngestResult, elapsed_ms: u64) {
-    let (issues, merge_requests) = if result.resource_type == "issues" {
-        (
-            Some(IngestIssueStats {
-                fetched: result.issues_fetched,
-                upserted: result.issues_upserted,
-                synced_discussions: result.issues_synced_discussions,
-                skipped_discussion_sync: result.issues_skipped_discussion_sync,
-            }),
-            None,
-        )
-    } else {
-        (
-            None,
-            Some(IngestMrStats {
-                fetched: result.mrs_fetched,
-                upserted: result.mrs_upserted,
-                synced_discussions: result.mrs_synced_discussions,
-                skipped_discussion_sync: result.mrs_skipped_discussion_sync,
-                assignees_linked: result.assignees_linked,
-                reviewers_linked: result.reviewers_linked,
-                diffnotes_count: result.diffnotes_count,
-            }),
-        )
-    };
-
-    let status_enrichment: Vec<StatusEnrichmentJson> = result
-        .status_enrichment_projects
-        .iter()
-        .map(|p| StatusEnrichmentJson {
-            mode: p.mode.clone(),
-            reason: p.reason.clone(),
-            seen: p.seen,
-            enriched: p.enriched,
-            cleared: p.cleared,
-            without_widget: p.without_widget,
-            partial_errors: p.partial_errors,
-            first_partial_error: p.first_partial_error.clone(),
-            error: p.error.clone(),
-        })
-        .collect();
-
-    let output = IngestJsonOutput {
-        ok: true,
-        data: IngestJsonData {
-            resource_type: result.resource_type.clone(),
-            projects_synced: result.projects_synced,
-            issues,
-            merge_requests,
-            labels_created: result.labels_created,
-            discussions_fetched: result.discussions_fetched,
-            notes_upserted: result.notes_upserted,
-            resource_events_fetched: result.resource_events_fetched,
-            resource_events_failed: result.resource_events_failed,
-            status_enrichment,
-            status_enrichment_errors: result.status_enrichment_errors,
-        },
-        meta: RobotMeta { elapsed_ms },
-    };
-
-    println!("{}", serde_json::to_string(&output).unwrap());
-}
-
-pub fn print_ingest_summary(result: &IngestResult) {
-    println!();
-
-    if result.resource_type == "issues" {
-        println!(
-            "{}",
-            Theme::success().render(&format!(
-                "Total: {} issues, {} discussions, {} notes",
-                result.issues_upserted, result.discussions_fetched, result.notes_upserted
-            ))
-        );
-
-        if result.issues_skipped_discussion_sync > 0 {
-            println!(
-                "{}",
-                Theme::dim().render(&format!(
-                    "Skipped discussion sync for {} unchanged issues.",
-                    result.issues_skipped_discussion_sync
-                ))
-            );
-        }
-    } else {
-        let diffnotes_str = if result.diffnotes_count > 0 {
-            format!(" ({} diff notes)", result.diffnotes_count)
-        } else {
-            String::new()
-        };
-
-        println!(
-            "{}",
-            Theme::success().render(&format!(
-                "Total: {} MRs, {} discussions, {} notes{}",
-                result.mrs_upserted,
-                result.discussions_fetched,
-                result.notes_upserted,
-                diffnotes_str
-            ))
-        );
-
-        if result.mrs_skipped_discussion_sync > 0 {
-            println!(
-                "{}",
-                Theme::dim().render(&format!(
-                    "Skipped discussion sync for {} unchanged MRs.",
-                    result.mrs_skipped_discussion_sync
-                ))
-            );
-        }
-    }
-
-    if result.resource_events_fetched > 0 || result.resource_events_failed > 0 {
-        println!(
-            "  Resource events: {} fetched{}",
-            result.resource_events_fetched,
-            if result.resource_events_failed > 0 {
-                format!(", {} failed", result.resource_events_failed)
-            } else {
-                String::new()
-            }
-        );
-    }
-}
-
-pub fn print_dry_run_preview(preview: &DryRunPreview) {
-    println!(
-        "{} {}",
-        Theme::info().bold().render("Dry Run Preview"),
-        Theme::warning().render("(no changes will be made)")
-    );
-    println!();
-
-    let type_label = if preview.resource_type == "issues" {
-        "issues"
-    } else {
-        "merge requests"
-    };
-
-    println!("  Resource type: {}", Theme::bold().render(type_label));
-    println!(
-        "  Sync mode: {}",
-        if preview.sync_mode == "full" {
-            Theme::warning().render("full (all data will be re-fetched)")
-        } else {
-            Theme::success().render("incremental (only changes since last sync)")
-        }
-    );
-    println!("  Projects: {}", preview.projects.len());
-    println!();
-
-    println!("{}", Theme::info().bold().render("Projects to sync:"));
-    for project in &preview.projects {
-        let sync_status = if !project.has_cursor {
-            Theme::warning().render("initial sync")
-        } else {
-            Theme::success().render("incremental")
-        };
-
-        println!(
-            "  {} ({})",
-            Theme::bold().render(&project.path),
-            sync_status
-        );
-        println!("    Existing {}: {}", type_label, project.existing_count);
-
-        if let Some(ref last_synced) = project.last_synced {
-            println!("    Last synced: {}", last_synced);
-        }
-    }
-}
-
-#[derive(Serialize)]
-struct DryRunJsonOutput {
-    ok: bool,
-    dry_run: bool,
-    data: DryRunPreview,
-}
-
-pub fn print_dry_run_preview_json(preview: &DryRunPreview) {
-    let output = DryRunJsonOutput {
-        ok: true,
-        dry_run: true,
-        data: preview.clone(),
-    };
-
-    println!("{}", serde_json::to_string(&output).unwrap());
-}

src/cli/commands/init.rs

@@ -1,9 +1,10 @@
 use std::fs;
+use std::io::{IsTerminal, Read};
 
-use crate::core::config::{MinimalConfig, MinimalGitLabConfig, ProjectConfig};
+use crate::core::config::{Config, MinimalConfig, MinimalGitLabConfig, ProjectConfig};
 use crate::core::db::{create_connection, run_migrations};
 use crate::core::error::{LoreError, Result};
-use crate::core::paths::{get_config_path, get_data_dir};
+use crate::core::paths::{ensure_config_permissions, get_config_path, get_data_dir};
 use crate::gitlab::{GitLabClient, GitLabProject};
 
 pub struct InitInputs {
@@ -37,6 +38,159 @@ pub struct ProjectInfo {
     pub name: String,
 }
 
+// ── Refresh types ──
+
+pub struct RefreshOptions {
+    pub config_path: Option<String>,
+    pub non_interactive: bool,
+}
+
+pub struct RefreshResult {
+    pub user: UserInfo,
+    pub projects_registered: Vec<ProjectInfo>,
+    pub projects_failed: Vec<ProjectFailure>,
+    pub orphans_found: Vec<String>,
+    pub orphans_deleted: Vec<String>,
+}
+
+pub struct ProjectFailure {
+    pub path: String,
+    pub error: String,
+}
+
+/// Re-read existing config and register any new projects in the database.
+/// Does NOT modify the config file.
+pub async fn run_init_refresh(options: RefreshOptions) -> Result<RefreshResult> {
+    let config_path = get_config_path(options.config_path.as_deref());
+
+    if !config_path.exists() {
+        return Err(LoreError::ConfigNotFound {
+            path: config_path.display().to_string(),
+        });
+    }
+
+    let config = Config::load(options.config_path.as_deref())?;
+    let token = config.gitlab.resolve_token()?;
+    let client = GitLabClient::new(&config.gitlab.base_url, &token, None);
+
+    // Validate auth
+    let gitlab_user = client.get_current_user().await.map_err(|e| {
+        if matches!(e, LoreError::GitLabAuthFailed) {
+            LoreError::Other(format!(
+                "Authentication failed for {}",
+                config.gitlab.base_url
+            ))
+        } else {
+            e
+        }
+    })?;
+
+    let user = UserInfo {
+        username: gitlab_user.username,
+        name: gitlab_user.name,
+    };
+
+    // Validate each project
+    let mut validated_projects: Vec<(ProjectInfo, GitLabProject)> = Vec::new();
+    let mut failed_projects: Vec<ProjectFailure> = Vec::new();
+
+    for project_config in &config.projects {
+        match client.get_project(&project_config.path).await {
+            Ok(project) => {
+                validated_projects.push((
+                    ProjectInfo {
+                        path: project_config.path.clone(),
+                        name: project.name.clone().unwrap_or_else(|| {
+                            project_config
+                                .path
+                                .split('/')
+                                .next_back()
+                                .unwrap_or(&project_config.path)
+                                .to_string()
+                        }),
+                    },
+                    project,
+                ));
+            }
+            Err(e) => {
+                let error_msg = if matches!(e, LoreError::GitLabNotFound { .. }) {
+                    "not found".to_string()
+                } else {
+                    e.to_string()
+                };
+                failed_projects.push(ProjectFailure {
+                    path: project_config.path.clone(),
+                    error: error_msg,
+                });
+            }
+        }
+    }
+
+    // Open database
+    let data_dir = get_data_dir();
+    let db_path = data_dir.join("lore.db");
+    let conn = create_connection(&db_path)?;
+    run_migrations(&conn)?;
+
+    // Find orphans: projects in DB but not in config
+    let config_paths: std::collections::HashSet<&str> =
+        config.projects.iter().map(|p| p.path.as_str()).collect();
+
+    let mut stmt = conn.prepare("SELECT path_with_namespace FROM projects")?;
+    let db_projects: Vec<String> = stmt
+        .query_map([], |row| row.get(0))?
+        .filter_map(|r| r.ok())
+        .collect();
+
+    let orphans: Vec<String> = db_projects
+        .into_iter()
+        .filter(|p| !config_paths.contains(p.as_str()))
+        .collect();
+
+    // Upsert validated projects
+    for (_, gitlab_project) in &validated_projects {
+        conn.execute(
+            "INSERT INTO projects (gitlab_project_id, path_with_namespace, default_branch, web_url)
+             VALUES (?, ?, ?, ?)
+             ON CONFLICT(gitlab_project_id) DO UPDATE SET
+               path_with_namespace = excluded.path_with_namespace,
+               default_branch = excluded.default_branch,
+               web_url = excluded.web_url",
+            (
+                gitlab_project.id,
+                &gitlab_project.path_with_namespace,
+                &gitlab_project.default_branch,
+                &gitlab_project.web_url,
+            ),
+        )?;
+    }
+
+    Ok(RefreshResult {
+        user,
+        projects_registered: validated_projects.into_iter().map(|(p, _)| p).collect(),
+        projects_failed: failed_projects,
+        orphans_found: orphans,
+        orphans_deleted: Vec::new(), // Caller handles deletion after user prompt
+    })
+}
+
+/// Delete orphan projects from the database.
+pub fn delete_orphan_projects(config_path: Option<&str>, orphans: &[String]) -> Result<usize> {
+    let data_dir = get_data_dir();
+    let db_path = data_dir.join("lore.db");
+    let conn = create_connection(&db_path)?;
+
+    let _ = config_path; // Reserved for future use
+
+    let mut deleted = 0;
+    for path in orphans {
+        let rows = conn.execute("DELETE FROM projects WHERE path_with_namespace = ?", [path])?;
+        deleted += rows;
+    }
+
+    Ok(deleted)
+}
+
 pub async fn run_init(inputs: InitInputs, options: InitOptions) -> Result<InitResult> {
     let config_path = get_config_path(options.config_path.as_deref());
     let data_dir = get_data_dir();
@@ -172,3 +326,141 @@ pub async fn run_init(inputs: InitInputs, options: InitOptions) -> Result<InitRe
         default_project: inputs.default_project,
     })
 }
+
+// ── token set / show ──
+
+pub struct TokenSetResult {
+    pub username: String,
+    pub config_path: String,
+}
+
+pub struct TokenShowResult {
+    pub token: String,
+    pub source: &'static str,
+}
+
+/// Read token from --token flag or stdin, validate against GitLab, store in config.
+pub async fn run_token_set(
+    config_path_override: Option<&str>,
+    token_arg: Option<String>,
+) -> Result<TokenSetResult> {
+    let config_path = get_config_path(config_path_override);
+
+    if !config_path.exists() {
+        return Err(LoreError::ConfigNotFound {
+            path: config_path.display().to_string(),
+        });
+    }
+
+    // Resolve token value: flag > stdin > error
+    let token = if let Some(t) = token_arg {
+        t.trim().to_string()
+    } else if !std::io::stdin().is_terminal() {
+        let mut buf = String::new();
+        std::io::stdin()
+            .read_to_string(&mut buf)
+            .map_err(|e| LoreError::Other(format!("Failed to read token from stdin: {e}")))?;
+        buf.trim().to_string()
+    } else {
+        return Err(LoreError::Other(
+            "No token provided. Use --token or pipe to stdin.".to_string(),
+        ));
+    };
+
+    if token.is_empty() {
+        return Err(LoreError::Other("Token cannot be empty.".to_string()));
+    }
+
+    // Load config to get the base URL for validation
+    let config = Config::load(config_path_override)?;
+
+    // Validate token against GitLab
+    let client = GitLabClient::new(&config.gitlab.base_url, &token, None);
+    let user = client.get_current_user().await.map_err(|e| {
+        if matches!(e, LoreError::GitLabAuthFailed) {
+            LoreError::Other("Token validation failed: authentication rejected by GitLab.".into())
+        } else {
+            e
+        }
+    })?;
+
+    // Read config as raw JSON, insert token, write back
+    let content = fs::read_to_string(&config_path)
+        .map_err(|e| LoreError::Other(format!("Failed to read config file: {e}")))?;
+
+    let mut json: serde_json::Value =
+        serde_json::from_str(&content).map_err(|e| LoreError::ConfigInvalid {
+            details: format!("Invalid JSON in config file: {e}"),
+        })?;
+
+    json["gitlab"]["token"] = serde_json::Value::String(token);
+
+    let output = serde_json::to_string_pretty(&json)
+        .map_err(|e| LoreError::Other(format!("Failed to serialize config: {e}")))?;
+    fs::write(&config_path, format!("{output}\n"))?;
+
+    // Enforce permissions
+    ensure_config_permissions(&config_path);
+
+    Ok(TokenSetResult {
+        username: user.username,
+        config_path: config_path.display().to_string(),
+    })
+}
+
+/// Show the current token (masked or unmasked) and its source.
+pub fn run_token_show(config_path_override: Option<&str>, unmask: bool) -> Result<TokenShowResult> {
+    let config = Config::load(config_path_override)?;
+
+    let source = config
+        .gitlab
+        .token_source()
+        .ok_or_else(|| LoreError::TokenNotSet {
+            env_var: config.gitlab.token_env_var.clone(),
+        })?;
+
+    let token = config.gitlab.resolve_token()?;
+
+    let display_token = if unmask { token } else { mask_token(&token) };
+
+    Ok(TokenShowResult {
+        token: display_token,
+        source,
+    })
+}
+
+fn mask_token(token: &str) -> String {
+    let len = token.len();
+    if len <= 8 {
+        "*".repeat(len)
+    } else {
+        let visible = &token[..4];
+        format!("{visible}{}", "*".repeat(len - 4))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn mask_token_hides_short_tokens_completely() {
+        assert_eq!(mask_token(""), "");
+        assert_eq!(mask_token("a"), "*");
+        assert_eq!(mask_token("abcd"), "****");
+        assert_eq!(mask_token("abcdefgh"), "********");
+    }
+
+    #[test]
+    fn mask_token_reveals_first_four_chars_for_long_tokens() {
+        assert_eq!(mask_token("abcdefghi"), "abcd*****");
+        assert_eq!(mask_token("glpat-xyzABC123456"), "glpa**************");
+    }
+
+    #[test]
+    fn mask_token_boundary_at_nine_chars() {
+        // 8 chars → fully masked, 9 chars → first 4 visible
+        assert_eq!(mask_token("12345678"), "********");
+        assert_eq!(mask_token("123456789"), "1234*****");
+    }
+}

src/cli/commands/list/issues.rs

@@ -0,0 +1,443 @@
+use crate::cli::render::{self, Align, Icons, StyledCell, Table as LoreTable, Theme};
+use rusqlite::Connection;
+use serde::Serialize;
+
+use crate::Config;
+use crate::cli::robot::{expand_fields_preset, filter_fields};
+use crate::core::db::create_connection;
+use crate::core::error::{LoreError, Result};
+use crate::core::paths::get_db_path;
+use crate::core::project::resolve_project;
+use crate::core::time::{ms_to_iso, parse_since};
+
+use super::render_helpers::{format_assignees, format_discussions};
+
+#[derive(Debug, Serialize)]
+pub struct IssueListRow {
+    pub iid: i64,
+    pub title: String,
+    pub state: String,
+    pub author_username: String,
+    pub created_at: i64,
+    pub updated_at: i64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub web_url: Option<String>,
+    pub project_path: String,
+    pub labels: Vec<String>,
+    pub assignees: Vec<String>,
+    pub discussion_count: i64,
+    pub unresolved_count: i64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status_name: Option<String>,
+    #[serde(skip_serializing)]
+    pub status_category: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status_color: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status_icon_name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status_synced_at: Option<i64>,
+}
+
+#[derive(Serialize)]
+pub struct IssueListRowJson {
+    pub iid: i64,
+    pub title: String,
+    pub state: String,
+    pub author_username: String,
+    pub labels: Vec<String>,
+    pub assignees: Vec<String>,
+    pub discussion_count: i64,
+    pub unresolved_count: i64,
+    pub created_at_iso: String,
+    pub updated_at_iso: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub web_url: Option<String>,
+    pub project_path: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status_name: Option<String>,
+    #[serde(skip_serializing)]
+    pub status_category: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status_color: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status_icon_name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status_synced_at_iso: Option<String>,
+}
+
+impl From<&IssueListRow> for IssueListRowJson {
+    fn from(row: &IssueListRow) -> Self {
+        Self {
+            iid: row.iid,
+            title: row.title.clone(),
+            state: row.state.clone(),
+            author_username: row.author_username.clone(),
+            labels: row.labels.clone(),
+            assignees: row.assignees.clone(),
+            discussion_count: row.discussion_count,
+            unresolved_count: row.unresolved_count,
+            created_at_iso: ms_to_iso(row.created_at),
+            updated_at_iso: ms_to_iso(row.updated_at),
+            web_url: row.web_url.clone(),
+            project_path: row.project_path.clone(),
+            status_name: row.status_name.clone(),
+            status_category: row.status_category.clone(),
+            status_color: row.status_color.clone(),
+            status_icon_name: row.status_icon_name.clone(),
+            status_synced_at_iso: row.status_synced_at.map(ms_to_iso),
+        }
+    }
+}
+
+#[derive(Serialize)]
+pub struct ListResult {
+    pub issues: Vec<IssueListRow>,
+    pub total_count: usize,
+    pub available_statuses: Vec<String>,
+}
+
+#[derive(Serialize)]
+pub struct ListResultJson {
+    pub issues: Vec<IssueListRowJson>,
+    pub total_count: usize,
+    pub showing: usize,
+}
+
+impl From<&ListResult> for ListResultJson {
+    fn from(result: &ListResult) -> Self {
+        Self {
+            issues: result.issues.iter().map(IssueListRowJson::from).collect(),
+            total_count: result.total_count,
+            showing: result.issues.len(),
+        }
+    }
+}
+
+pub struct ListFilters<'a> {
+    pub limit: usize,
+    pub project: Option<&'a str>,
+    pub state: Option<&'a str>,
+    pub author: Option<&'a str>,
+    pub assignee: Option<&'a str>,
+    pub labels: Option<&'a [String]>,
+    pub milestone: Option<&'a str>,
+    pub since: Option<&'a str>,
+    pub due_before: Option<&'a str>,
+    pub has_due_date: bool,
+    pub statuses: &'a [String],
+    pub sort: &'a str,
+    pub order: &'a str,
+}
+
+pub fn run_list_issues(config: &Config, filters: ListFilters) -> Result<ListResult> {
+    let db_path = get_db_path(config.storage.db_path.as_deref());
+    let conn = create_connection(&db_path)?;
+
+    let mut result = query_issues(&conn, &filters)?;
+    result.available_statuses = query_available_statuses(&conn)?;
+    Ok(result)
+}
+
+fn query_available_statuses(conn: &Connection) -> Result<Vec<String>> {
+    let mut stmt = conn.prepare(
+        "SELECT DISTINCT status_name FROM issues WHERE status_name IS NOT NULL ORDER BY status_name",
+    )?;
+    let statuses = stmt
+        .query_map([], |row| row.get::<_, String>(0))?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+    Ok(statuses)
+}
+
+fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult> {
+    let mut where_clauses = Vec::new();
+    let mut params: Vec<Box<dyn rusqlite::ToSql>> = Vec::new();
+
+    if let Some(project) = filters.project {
+        let project_id = resolve_project(conn, project)?;
+        where_clauses.push("i.project_id = ?");
+        params.push(Box::new(project_id));
+    }
+
+    if let Some(state) = filters.state
+        && state != "all"
+    {
+        where_clauses.push("i.state = ?");
+        params.push(Box::new(state.to_string()));
+    }
+
+    if let Some(author) = filters.author {
+        let username = author.strip_prefix('@').unwrap_or(author);
+        where_clauses.push("i.author_username = ?");
+        params.push(Box::new(username.to_string()));
+    }
+
+    if let Some(assignee) = filters.assignee {
+        let username = assignee.strip_prefix('@').unwrap_or(assignee);
+        where_clauses.push(
+            "EXISTS (SELECT 1 FROM issue_assignees ia
+             WHERE ia.issue_id = i.id AND ia.username = ?)",
+        );
+        params.push(Box::new(username.to_string()));
+    }
+
+    if let Some(since_str) = filters.since {
+        let cutoff_ms = parse_since(since_str).ok_or_else(|| {
+            LoreError::Other(format!(
+                "Invalid --since value '{}'. Use relative (7d, 2w, 1m) or absolute (YYYY-MM-DD) format.",
+                since_str
+            ))
+        })?;
+        where_clauses.push("i.updated_at >= ?");
+        params.push(Box::new(cutoff_ms));
+    }
+
+    if let Some(labels) = filters.labels {
+        for label in labels {
+            where_clauses.push(
+                "EXISTS (SELECT 1 FROM issue_labels il
+                 JOIN labels l ON il.label_id = l.id
+                 WHERE il.issue_id = i.id AND l.name = ?)",
+            );
+            params.push(Box::new(label.clone()));
+        }
+    }
+
+    if let Some(milestone) = filters.milestone {
+        where_clauses.push("i.milestone_title = ?");
+        params.push(Box::new(milestone.to_string()));
+    }
+
+    if let Some(due_before) = filters.due_before {
+        where_clauses.push("i.due_date IS NOT NULL AND i.due_date <= ?");
+        params.push(Box::new(due_before.to_string()));
+    }
+
+    if filters.has_due_date {
+        where_clauses.push("i.due_date IS NOT NULL");
+    }
+
+    let status_in_clause;
+    if filters.statuses.len() == 1 {
+        where_clauses.push("i.status_name = ? COLLATE NOCASE");
+        params.push(Box::new(filters.statuses[0].clone()));
+    } else if filters.statuses.len() > 1 {
+        let placeholders: Vec<&str> = filters.statuses.iter().map(|_| "?").collect();
+        status_in_clause = format!(
+            "i.status_name COLLATE NOCASE IN ({})",
+            placeholders.join(", ")
+        );
+        where_clauses.push(&status_in_clause);
+        for s in filters.statuses {
+            params.push(Box::new(s.clone()));
+        }
+    }
+
+    let where_sql = if where_clauses.is_empty() {
+        String::new()
+    } else {
+        format!("WHERE {}", where_clauses.join(" AND "))
+    };
+
+    let count_sql = format!(
+        "SELECT COUNT(*) FROM issues i
+         JOIN projects p ON i.project_id = p.id
+         {where_sql}"
+    );
+
+    let param_refs: Vec<&dyn rusqlite::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+    let total_count: i64 = conn.query_row(&count_sql, param_refs.as_slice(), |row| row.get(0))?;
+    let total_count = total_count as usize;
+
+    let sort_column = match filters.sort {
+        "created" => "i.created_at",
+        "iid" => "i.iid",
+        _ => "i.updated_at",
+    };
+    let order = if filters.order == "asc" {
+        "ASC"
+    } else {
+        "DESC"
+    };
+
+    let query_sql = format!(
+        "SELECT
+            i.iid,
+            i.title,
+            i.state,
+            i.author_username,
+            i.created_at,
+            i.updated_at,
+            i.web_url,
+            p.path_with_namespace,
+            (SELECT GROUP_CONCAT(l.name, X'1F')
+             FROM issue_labels il
+             JOIN labels l ON il.label_id = l.id
+             WHERE il.issue_id = i.id) AS labels_csv,
+            (SELECT GROUP_CONCAT(ia.username, X'1F')
+             FROM issue_assignees ia
+             WHERE ia.issue_id = i.id) AS assignees_csv,
+            (SELECT COUNT(*) FROM discussions d
+             WHERE d.issue_id = i.id) AS discussion_count,
+            (SELECT COUNT(*) FROM discussions d
+             WHERE d.issue_id = i.id AND d.resolvable = 1 AND d.resolved = 0) AS unresolved_count,
+            i.status_name,
+            i.status_category,
+            i.status_color,
+            i.status_icon_name,
+            i.status_synced_at
+         FROM issues i
+         JOIN projects p ON i.project_id = p.id
+         {where_sql}
+         ORDER BY {sort_column} {order}
+         LIMIT ?"
+    );
+
+    params.push(Box::new(filters.limit as i64));
+    let param_refs: Vec<&dyn rusqlite::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+
+    let mut stmt = conn.prepare(&query_sql)?;
+    let issues: Vec<IssueListRow> = stmt
+        .query_map(param_refs.as_slice(), |row| {
+            let labels_csv: Option<String> = row.get(8)?;
+            let labels = labels_csv
+                .map(|s| s.split('\x1F').map(String::from).collect())
+                .unwrap_or_default();
+
+            let assignees_csv: Option<String> = row.get(9)?;
+            let assignees = assignees_csv
+                .map(|s| s.split('\x1F').map(String::from).collect())
+                .unwrap_or_default();
+
+            Ok(IssueListRow {
+                iid: row.get(0)?,
+                title: row.get(1)?,
+                state: row.get(2)?,
+                author_username: row.get(3)?,
+                created_at: row.get(4)?,
+                updated_at: row.get(5)?,
+                web_url: row.get(6)?,
+                project_path: row.get(7)?,
+                labels,
+                assignees,
+                discussion_count: row.get(10)?,
+                unresolved_count: row.get(11)?,
+                status_name: row.get(12)?,
+                status_category: row.get(13)?,
+                status_color: row.get(14)?,
+                status_icon_name: row.get(15)?,
+                status_synced_at: row.get(16)?,
+            })
+        })?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    Ok(ListResult {
+        issues,
+        total_count,
+        available_statuses: Vec::new(),
+    })
+}
+
+pub fn print_list_issues(result: &ListResult) {
+    if result.issues.is_empty() {
+        println!("No issues found.");
+        return;
+    }
+
+    println!(
+        "{}  {} of {}\n",
+        Theme::bold().render("Issues"),
+        result.issues.len(),
+        result.total_count
+    );
+
+    let has_any_status = result.issues.iter().any(|i| i.status_name.is_some());
+
+    let mut headers = vec!["IID", "Title", "State"];
+    if has_any_status {
+        headers.push("Status");
+    }
+    headers.extend(["Assignee", "Labels", "Disc", "Updated"]);
+
+    let mut table = LoreTable::new().headers(&headers).align(0, Align::Right);
+
+    for issue in &result.issues {
+        let title = render::truncate(&issue.title, 45);
+        let relative_time = render::format_relative_time_compact(issue.updated_at);
+        let labels = render::format_labels_bare(&issue.labels, 2);
+        let assignee = format_assignees(&issue.assignees);
+        let discussions = format_discussions(issue.discussion_count, issue.unresolved_count);
+
+        let (icon, state_style) = if issue.state == "opened" {
+            (Icons::issue_opened(), Theme::success())
+        } else {
+            (Icons::issue_closed(), Theme::dim())
+        };
+        let state_cell = StyledCell::styled(format!("{icon} {}", issue.state), state_style);
+
+        let mut row = vec![
+            StyledCell::styled(format!("#{}", issue.iid), Theme::info()),
+            StyledCell::plain(title),
+            state_cell,
+        ];
+        if has_any_status {
+            match &issue.status_name {
+                Some(status) => {
+                    row.push(StyledCell::plain(render::style_with_hex(
+                        status,
+                        issue.status_color.as_deref(),
+                    )));
+                }
+                None => {
+                    row.push(StyledCell::plain(""));
+                }
+            }
+        }
+        row.extend([
+            StyledCell::styled(assignee, Theme::accent()),
+            StyledCell::styled(labels, Theme::warning()),
+            discussions,
+            StyledCell::styled(relative_time, Theme::dim()),
+        ]);
+        table.add_row(row);
+    }
+
+    println!("{}", table.render());
+}
+
+pub fn print_list_issues_json(result: &ListResult, elapsed_ms: u64, fields: Option<&[String]>) {
+    let json_result = ListResultJson::from(result);
+    let output = serde_json::json!({
+        "ok": true,
+        "data": json_result,
+        "meta": {
+            "elapsed_ms": elapsed_ms,
+            "available_statuses": result.available_statuses,
+        },
+    });
+    let mut output = output;
+    if let Some(f) = fields {
+        let expanded = expand_fields_preset(f, "issues");
+        filter_fields(&mut output, "issues", &expanded);
+    }
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
+}
+
+pub fn open_issue_in_browser(result: &ListResult) -> Option<String> {
+    let first_issue = result.issues.first()?;
+    let url = first_issue.web_url.as_ref()?;
+
+    match open::that(url) {
+        Ok(()) => {
+            println!("Opened: {url}");
+            Some(url.clone())
+        }
+        Err(e) => {
+            eprintln!("Failed to open browser: {e}");
+            None
+        }
+    }
+}

src/cli/commands/list/list_tests.rs

@@ -1,6 +1,9 @@
 use super::*;
 use crate::cli::render;
 use crate::core::time::now_ms;
+use crate::test_support::{
+    insert_project as insert_test_project, setup_test_db as setup_note_test_db, test_config,
+};
 
 #[test]
 fn truncate_leaves_short_strings_alone() {
@@ -82,32 +85,6 @@ fn format_discussions_with_unresolved() {
 // Note query layer tests
 // -----------------------------------------------------------------------
 
-use std::path::Path;
-
-use crate::core::config::{
-    Config, EmbeddingConfig, GitLabConfig, LoggingConfig, ProjectConfig, ScoringConfig,
-    StorageConfig, SyncConfig,
-};
-use crate::core::db::{create_connection, run_migrations};
-
-fn test_config(default_project: Option<&str>) -> Config {
-    Config {
-        gitlab: GitLabConfig {
-            base_url: "https://gitlab.example.com".to_string(),
-            token_env_var: "GITLAB_TOKEN".to_string(),
-        },
-        projects: vec![ProjectConfig {
-            path: "group/project".to_string(),
-        }],
-        default_project: default_project.map(String::from),
-        sync: SyncConfig::default(),
-        storage: StorageConfig::default(),
-        embedding: EmbeddingConfig::default(),
-        logging: LoggingConfig::default(),
-        scoring: ScoringConfig::default(),
-    }
-}
-
 fn default_note_filters() -> NoteListFilters {
     NoteListFilters {
         limit: 50,
@@ -130,26 +107,6 @@ fn default_note_filters() -> NoteListFilters {
     }
 }
 
-fn setup_note_test_db() -> Connection {
-    let conn = create_connection(Path::new(":memory:")).unwrap();
-    run_migrations(&conn).unwrap();
-    conn
-}
-
-fn insert_test_project(conn: &Connection, id: i64, path: &str) {
-    conn.execute(
-        "INSERT INTO projects (id, gitlab_project_id, path_with_namespace, web_url)
-         VALUES (?1, ?2, ?3, ?4)",
-        rusqlite::params![
-            id,
-            id * 100,
-            path,
-            format!("https://gitlab.example.com/{path}")
-        ],
-    )
-    .unwrap();
-}
-
 fn insert_test_issue(conn: &Connection, id: i64, project_id: i64, iid: i64, title: &str) {
     conn.execute(
         "INSERT INTO issues (id, gitlab_id, project_id, iid, title, state, author_username,
@@ -1269,60 +1226,6 @@ fn test_truncate_note_body() {
     assert!(result.ends_with("..."));
 }
 
-#[test]
-fn test_csv_escape_basic() {
-    assert_eq!(csv_escape("simple"), "simple");
-    assert_eq!(csv_escape("has,comma"), "\"has,comma\"");
-    assert_eq!(csv_escape("has\"quote"), "\"has\"\"quote\"");
-    assert_eq!(csv_escape("has\nnewline"), "\"has\nnewline\"");
-}
-
-#[test]
-fn test_csv_output_basic() {
-    let result = NoteListResult {
-        notes: vec![NoteListRow {
-            id: 1,
-            gitlab_id: 100,
-            author_username: "alice".to_string(),
-            body: Some("Hello, world".to_string()),
-            note_type: Some("DiffNote".to_string()),
-            is_system: false,
-            created_at: 1_000_000,
-            updated_at: 2_000_000,
-            position_new_path: Some("src/main.rs".to_string()),
-            position_new_line: Some(42),
-            position_old_path: None,
-            position_old_line: None,
-            resolvable: true,
-            resolved: false,
-            resolved_by: None,
-            noteable_type: Some("Issue".to_string()),
-            parent_iid: Some(7),
-            parent_title: Some("Test issue".to_string()),
-            project_path: "group/project".to_string(),
-        }],
-        total_count: 1,
-    };
-
-    // Verify csv_escape handles the comma in body correctly
-    let body = result.notes[0].body.as_deref().unwrap();
-    let escaped = csv_escape(body);
-    assert_eq!(escaped, "\"Hello, world\"");
-
-    // Verify the formatting helpers
-    assert_eq!(
-        format_note_type(result.notes[0].note_type.as_deref()),
-        "Diff"
-    );
-    assert_eq!(
-        format_note_parent(
-            result.notes[0].noteable_type.as_deref(),
-            result.notes[0].parent_iid,
-        ),
-        "Issue #7"
-    );
-}
-
 #[test]
 fn test_jsonl_output_one_per_line() {
     let result = NoteListResult {

src/cli/commands/list/mod.rs

@@ -0,0 +1,28 @@
+mod issues;
+mod mrs;
+mod notes;
+mod render_helpers;
+
+pub use issues::{
+    IssueListRow, IssueListRowJson, ListFilters, ListResult, ListResultJson, open_issue_in_browser,
+    print_list_issues, print_list_issues_json, run_list_issues,
+};
+pub use mrs::{
+    MrListFilters, MrListResult, MrListResultJson, MrListRow, MrListRowJson, open_mr_in_browser,
+    print_list_mrs, print_list_mrs_json, run_list_mrs,
+};
+pub use notes::{
+    NoteListFilters, NoteListResult, NoteListResultJson, NoteListRow, NoteListRowJson,
+    print_list_notes, print_list_notes_json, query_notes,
+};
+
+#[cfg(test)]
+use crate::core::path_resolver::escape_like as note_escape_like;
+#[cfg(test)]
+use render_helpers::{format_discussions, format_note_parent, format_note_type, truncate_body};
+#[cfg(test)]
+use rusqlite::Connection;
+
+#[cfg(test)]
+#[path = "list_tests.rs"]
+mod tests;