feat(tui): Phase 2 Issue List + MR List screens

Implement state, action, and view layers for both list screens:
- Issue List: keyset pagination, snapshot fence, filter DSL, label aggregation
- MR List: mirrors Issue pattern with draft/reviewer/target branch filters
- Migration 027: covering indexes for TUI list screen queries
- Updated Msg types to use typed Page structs instead of raw Vec<Row>
- 303 tests passing, clippy clean

Beads: bd-3ei1, bd-2kr0, bd-3pm2

.beads/last-touched

@@ -1 +1 @@
-bd-1lj5
+bd-2kr0

.gitignore

@@ -1,11 +1,6 @@
-# Dependencies
-node_modules/
-
-# Build output
-dist/
-
-# Test coverage
-coverage/
+# Rust build output
+/target
+**/target/
 
 # IDE
 .idea/
@@ -25,15 +20,11 @@ Thumbs.db
 
 # Logs
 *.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
 
 # Local config files
 lore.config.json
-.liquid-mail.toml
 
-# beads
+# beads viewer cache
 .bv/
 
 # SQLite databases (local development)
@@ -41,10 +32,15 @@ lore.config.json
 *.db-wal
 *.db-shm
 
-
 # Mock seed data
 tools/mock-seed/
 
 # Added by cargo
 
 /target
+
+# Profiling / benchmarks
+perf.data
+perf.data.old
+flamegraph.svg
+*.profraw

.opencode/rules

@@ -0,0 +1,50 @@
+
+````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

@@ -0,0 +1,11 @@
+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,17 +127,66 @@ 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 Liquid Mail's shared log for progress, decisions, and cross-session context.
+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.
 
 **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
+- **Single source of truth:** Beads for task status/priority/dependencies; Agent Mail for conversation and audit
+- **Shared identifiers:** Use Beads issue ID (e.g., `br-123`) as Mail `thread_id` and prefix subjects with `[br-123]`
+- **Reservations:** When starting a task, call `file_reservation_paths()` with the issue ID in `reason`
 
 ### Typical Agent Flow
 
@@ -146,34 +195,35 @@ Beads provides a lightweight, dependency-aware issue database and CLI (`br` / be
    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
+2. **Reserve edit surface (Mail):**
+   ```
+   file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="br-123")
    ```
 
-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>"
+3. **Announce start (Mail):**
+   ```
+   send_message(..., thread_id="br-123", subject="[br-123] Start: <title>", ack_required=true)
    ```
 
-4. **Complete (Beads is authority):**
+4. **Work and update:** Reply in-thread with progress
+
+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 | 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 |
+| Concept | Value |
+|---------|-------|
+| Mail `thread_id` | `br-###` |
+| Mail subject | `[br-###] ...` |
+| File reservation `reason` | `br-###` |
+| Commit messages | Include `br-###` for traceability |
 
 ---
 
@@ -181,7 +231,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 (progress logging, decisions, cross-session context), use Liquid Mail.
+**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.
 
 **CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.**
 
@@ -623,16 +673,6 @@ 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

@@ -1,960 +0,0 @@
-# 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.9.4"
+version = "0.8.3"
 edition = "2024"
 description = "Gitlore - Local GitLab data management with semantic search"
 authors = ["Taylor Eernisse"]
@@ -25,15 +25,16 @@ clap_complete = "4"
 dialoguer = "0.12"
 console = "0.16"
 indicatif = "0.18"
-lipgloss = { package = "charmed-lipgloss", version = "0.2", default-features = false, features = ["native"] }
+lipgloss = { package = "charmed-lipgloss", version = "0.1", default-features = false, features = ["native"] }
 open = "5"
 
 # HTTP
-asupersync = { version = "0.2", features = ["tls", "tls-native-roots"] }
+reqwest = { version = "0.12", features = ["json"] }
+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", "async-await"] }
+futures = { version = "0.3", default-features = false, features = ["alloc"] }
 
 # Utilities
 thiserror = "2"
@@ -59,7 +60,6 @@ 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,9 +12,6 @@ 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
@@ -24,12 +21,9 @@ 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
 
@@ -83,21 +77,6 @@ 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
 
@@ -211,8 +190,6 @@ 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
@@ -376,13 +353,12 @@ Shows: total DiffNotes, categorized by code area with percentage breakdown.
 
 #### Active Mode
 
-Surface unresolved discussions needing attention. By default, only discussions on open issues and non-merged MRs are shown.
+Surface unresolved discussions needing attention.
 
 ```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.
@@ -406,44 +382,11 @@ 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.
@@ -522,6 +465,8 @@ 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)
@@ -548,52 +493,9 @@ 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.
@@ -604,54 +506,9 @@ 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. Supports both incremental (cursor-based) and surgical (per-IID) modes.
+Run the full sync pipeline: ingest from GitLab (including work item status enrichment via GraphQL), generate searchable documents, and compute embeddings.
 
 ```bash
 lore sync                    # Full pipeline
@@ -661,29 +518,11 @@ 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.
@@ -768,35 +607,16 @@ Displays:
 
 ### `lore init`
 
-Initialize configuration and database interactively, or refresh the database to match an existing config.
+Initialize configuration and database interactively.
 
 ```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
@@ -865,7 +685,7 @@ Show version information including the git commit hash.
 
 ```bash
 lore version
-# lore version 0.9.2 (571c304)
+# lore version 0.1.0 (abc1234)
 ```
 
 ## Robot Mode
@@ -908,7 +728,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`, `me`, `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`, `search`, `timeline`, and `who` list commands:
 
 ```bash
 # Minimal preset (~60% fewer tokens)
@@ -933,7 +753,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`, `--no-color` -> `--color never` (unambiguous only) | All |
+| Flag prefix expansion | `--proj` -> `--project` (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 |
@@ -965,7 +785,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`, `lore tra` -> `lore trace`).
+Unambiguous prefixes also work via subcommand inference (e.g., `lore iss` -> `lore issues`, `lore time` -> `lore timeline`).
 
 ### Agent Self-Discovery
 
@@ -1020,8 +840,6 @@ 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
@@ -1029,7 +847,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). Icon sets default to `unicode` and can be overridden via `--icons`, `LORE_ICONS`, or `NERD_FONTS` environment variables.
+Color output respects `NO_COLOR` and `CLICOLOR` environment variables in `auto` mode (the default).
 
 ## Shell Completions
 
@@ -1077,7 +895,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 (supports surgical mode tracking with per-entity results) |
+| `sync_runs` | Audit trail of sync operations |
 | `sync_cursors` | Cursor positions for incremental sync |
 | `app_locks` | Crash-safe single-flight lock |
 | `raw_payloads` | Compressed original API responses |

acceptance-criteria.md

@@ -1,64 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-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

@@ -1,72 +0,0 @@
-# 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

@@ -1,33 +0,0 @@
-# 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

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

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

@@ -1,18 +0,0 @@
-# 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

@@ -1,44 +0,0 @@
-# 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

@@ -1,28 +0,0 @@
-# 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

@@ -1,53 +0,0 @@
-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

@@ -1,113 +0,0 @@
-# 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

@@ -1,56 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
-# 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

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

agents/plan-reviewer/AGENTS.md

@@ -1,115 +0,0 @@
-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

@@ -1,37 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-# 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

@@ -1,388 +0,0 @@
-# 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

@@ -1,966 +0,0 @@
-# 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)

crates/lore-tui/Cargo.toml

@@ -0,0 +1,46 @@
+[package]
+name = "lore-tui"
+version = "0.1.0"
+edition = "2024"
+description = "Terminal UI for Gitlore — local GitLab data explorer"
+authors = ["Taylor Eernisse"]
+license = "MIT"
+
+[[bin]]
+name = "lore-tui"
+path = "src/main.rs"
+
+[dependencies]
+# FrankenTUI (Elm-architecture TUI framework)
+ftui = "0.1.1"
+
+# Lore library (config, db, ingestion, search, etc.)
+lore = { path = "../.." }
+
+# CLI
+clap = { version = "4", features = ["derive", "env"] }
+
+# Error handling
+anyhow = "1"
+
+# Time
+chrono = { version = "0.4", features = ["serde"] }
+
+# Paths
+dirs = "6"
+
+# Database (read-only queries from TUI)
+rusqlite = { version = "0.38", features = ["bundled"] }
+
+# Terminal (crossterm for raw mode + event reading, used by ftui runtime)
+crossterm = "0.28"
+
+# Serialization (crash context NDJSON dumps)
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# Regex (used by safety module for PII/secret redaction)
+regex = "1"
+
+[dev-dependencies]
+tempfile = "3"

crates/lore-tui/rust-toolchain.toml

@@ -0,0 +1,4 @@
+[toolchain]
+channel = "nightly-2026-02-08"
+profile = "minimal"
+components = ["rustfmt", "clippy"]

crates/lore-tui/src/app/mod.rs

@@ -0,0 +1,73 @@
+#![allow(dead_code)] // Phase 1: methods consumed as screens are implemented
+
+//! Full FrankenTUI Model implementation for the lore TUI.
+//!
+//! LoreApp is the central coordinator: it owns all state, dispatches
+//! messages through a 5-stage key pipeline, records crash context
+//! breadcrumbs, manages async tasks via the supervisor, and routes
+//! view() to per-screen render functions.
+
+mod tests;
+mod update;
+
+use crate::clock::{Clock, SystemClock};
+use crate::commands::{CommandRegistry, build_registry};
+use crate::crash_context::CrashContext;
+use crate::db::DbManager;
+use crate::message::InputMode;
+use crate::navigation::NavigationStack;
+use crate::state::AppState;
+use crate::task_supervisor::TaskSupervisor;
+
+// ---------------------------------------------------------------------------
+// LoreApp
+// ---------------------------------------------------------------------------
+
+/// Root model for the lore TUI.
+///
+/// Owns all state and implements the FrankenTUI Model trait. The
+/// update() method is the single entry point for all state transitions.
+pub struct LoreApp {
+    pub state: AppState,
+    pub navigation: NavigationStack,
+    pub supervisor: TaskSupervisor,
+    pub crash_context: CrashContext,
+    pub command_registry: CommandRegistry,
+    pub input_mode: InputMode,
+    pub clock: Box<dyn Clock>,
+    pub db: Option<DbManager>,
+}
+
+impl LoreApp {
+    /// Create a new LoreApp with default state.
+    ///
+    /// Uses a real system clock and no DB connection (set separately).
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            state: AppState::default(),
+            navigation: NavigationStack::new(),
+            supervisor: TaskSupervisor::new(),
+            crash_context: CrashContext::new(),
+            command_registry: build_registry(),
+            input_mode: InputMode::Normal,
+            clock: Box::new(SystemClock),
+            db: None,
+        }
+    }
+
+    /// Create a LoreApp for testing with a custom clock.
+    #[cfg(test)]
+    fn with_clock(clock: Box<dyn Clock>) -> Self {
+        Self {
+            clock,
+            ..Self::new()
+        }
+    }
+}
+
+impl Default for LoreApp {
+    fn default() -> Self {
+        Self::new()
+    }
+}

crates/lore-tui/src/app/tests.rs

@@ -0,0 +1,330 @@
+//! Tests for LoreApp.
+
+#![cfg(test)]
+
+use chrono::TimeDelta;
+use ftui::{Cmd, Event, KeyCode, KeyEvent, Model, Modifiers};
+
+use crate::clock::FakeClock;
+use crate::message::{InputMode, Msg, Screen};
+
+use super::LoreApp;
+
+fn test_app() -> LoreApp {
+    LoreApp::with_clock(Box::new(FakeClock::new(chrono::Utc::now())))
+}
+
+/// Verify that `App::fullscreen(LoreApp::new()).run()` compiles.
+fn _assert_app_fullscreen_compiles() {
+    fn _inner() {
+        use ftui::App;
+        let _app_builder = App::fullscreen(LoreApp::new());
+    }
+}
+
+/// Verify that `App::inline(LoreApp::new(), 12).run()` compiles.
+fn _assert_app_inline_compiles() {
+    fn _inner() {
+        use ftui::App;
+        let _app_builder = App::inline(LoreApp::new(), 12);
+    }
+}
+
+#[test]
+fn test_lore_app_init_returns_none() {
+    let mut app = test_app();
+    let cmd = app.init();
+    assert!(matches!(cmd, Cmd::None));
+}
+
+#[test]
+fn test_lore_app_quit_returns_quit_cmd() {
+    let mut app = test_app();
+    let cmd = app.update(Msg::Quit);
+    assert!(matches!(cmd, Cmd::Quit));
+}
+
+#[test]
+fn test_lore_app_tick_returns_none() {
+    let mut app = test_app();
+    let cmd = app.update(Msg::Tick);
+    assert!(matches!(cmd, Cmd::None));
+}
+
+#[test]
+fn test_lore_app_navigate_to_updates_nav_stack() {
+    let mut app = test_app();
+    let cmd = app.update(Msg::NavigateTo(Screen::IssueList));
+    assert!(matches!(cmd, Cmd::None));
+    assert!(app.navigation.is_at(&Screen::IssueList));
+    assert_eq!(app.navigation.depth(), 2);
+}
+
+#[test]
+fn test_lore_app_go_back() {
+    let mut app = test_app();
+    app.update(Msg::NavigateTo(Screen::IssueList));
+    app.update(Msg::GoBack);
+    assert!(app.navigation.is_at(&Screen::Dashboard));
+}
+
+#[test]
+fn test_lore_app_go_forward() {
+    let mut app = test_app();
+    app.update(Msg::NavigateTo(Screen::IssueList));
+    app.update(Msg::GoBack);
+    app.update(Msg::GoForward);
+    assert!(app.navigation.is_at(&Screen::IssueList));
+}
+
+#[test]
+fn test_ctrl_c_always_quits() {
+    let mut app = test_app();
+    let key = KeyEvent::new(KeyCode::Char('c')).with_modifiers(Modifiers::CTRL);
+    let cmd = app.update(Msg::RawEvent(Event::Key(key)));
+    assert!(matches!(cmd, Cmd::Quit));
+}
+
+#[test]
+fn test_q_key_quits_in_normal_mode() {
+    let mut app = test_app();
+    let key = KeyEvent::new(KeyCode::Char('q'));
+    let cmd = app.update(Msg::RawEvent(Event::Key(key)));
+    assert!(matches!(cmd, Cmd::Quit));
+}
+
+#[test]
+fn test_q_key_blocked_in_text_mode() {
+    let mut app = test_app();
+    app.input_mode = InputMode::Text;
+    let key = KeyEvent::new(KeyCode::Char('q'));
+    let cmd = app.update(Msg::RawEvent(Event::Key(key)));
+    // q in text mode should NOT quit.
+    assert!(matches!(cmd, Cmd::None));
+}
+
+#[test]
+fn test_esc_blurs_text_mode() {
+    let mut app = test_app();
+    app.input_mode = InputMode::Text;
+    app.state.search.query_focused = true;
+
+    let key = KeyEvent::new(KeyCode::Escape);
+    app.update(Msg::RawEvent(Event::Key(key)));
+
+    assert!(matches!(app.input_mode, InputMode::Normal));
+    assert!(!app.state.has_text_focus());
+}
+
+#[test]
+fn test_g_prefix_enters_go_mode() {
+    let mut app = test_app();
+    let key = KeyEvent::new(KeyCode::Char('g'));
+    app.update(Msg::RawEvent(Event::Key(key)));
+    assert!(matches!(app.input_mode, InputMode::GoPrefix { .. }));
+}
+
+#[test]
+fn test_g_then_i_navigates_to_issues() {
+    let mut app = test_app();
+
+    // First key: 'g'
+    let key_g = KeyEvent::new(KeyCode::Char('g'));
+    app.update(Msg::RawEvent(Event::Key(key_g)));
+
+    // Second key: 'i'
+    let key_i = KeyEvent::new(KeyCode::Char('i'));
+    app.update(Msg::RawEvent(Event::Key(key_i)));
+
+    assert!(app.navigation.is_at(&Screen::IssueList));
+}
+
+#[test]
+fn test_go_prefix_timeout_cancels() {
+    let clock = FakeClock::new(chrono::Utc::now());
+    let mut app = LoreApp::with_clock(Box::new(clock.clone()));
+
+    // Press 'g'.
+    let key_g = KeyEvent::new(KeyCode::Char('g'));
+    app.update(Msg::RawEvent(Event::Key(key_g)));
+    assert!(matches!(app.input_mode, InputMode::GoPrefix { .. }));
+
+    // Advance clock past timeout.
+    clock.advance(TimeDelta::milliseconds(600));
+
+    // Press 'i' after timeout — should NOT navigate to issues.
+    let key_i = KeyEvent::new(KeyCode::Char('i'));
+    app.update(Msg::RawEvent(Event::Key(key_i)));
+
+    // Should still be at Dashboard (no navigation happened).
+    assert!(app.navigation.is_at(&Screen::Dashboard));
+    assert!(matches!(app.input_mode, InputMode::Normal));
+}
+
+#[test]
+fn test_show_help_toggles() {
+    let mut app = test_app();
+    assert!(!app.state.show_help);
+
+    app.update(Msg::ShowHelp);
+    assert!(app.state.show_help);
+
+    app.update(Msg::ShowHelp);
+    assert!(!app.state.show_help);
+}
+
+#[test]
+fn test_error_msg_sets_toast() {
+    let mut app = test_app();
+    app.update(Msg::Error(crate::message::AppError::DbBusy));
+    assert!(app.state.error_toast.is_some());
+    assert!(app.state.error_toast.as_ref().unwrap().contains("busy"));
+}
+
+#[test]
+fn test_resize_updates_terminal_size() {
+    let mut app = test_app();
+    app.update(Msg::Resize {
+        width: 120,
+        height: 40,
+    });
+    assert_eq!(app.state.terminal_size, (120, 40));
+}
+
+#[test]
+fn test_stale_result_dropped() {
+    use crate::message::Screen;
+    use crate::task_supervisor::TaskKey;
+
+    let mut app = test_app();
+
+    // Submit two tasks for IssueList — second supersedes first.
+    let gen1 = app
+        .supervisor
+        .submit(TaskKey::LoadScreen(Screen::IssueList))
+        .generation;
+    let gen2 = app
+        .supervisor
+        .submit(TaskKey::LoadScreen(Screen::IssueList))
+        .generation;
+
+    // Stale result with gen1 should be ignored.
+    app.update(Msg::IssueListLoaded {
+        generation: gen1,
+        page: crate::state::issue_list::IssueListPage {
+            rows: vec![crate::state::issue_list::IssueListRow {
+                project_path: "group/project".into(),
+                iid: 1,
+                title: "stale".into(),
+                state: "opened".into(),
+                author: "taylor".into(),
+                labels: vec![],
+                updated_at: 1_700_000_000_000,
+            }],
+            next_cursor: None,
+            total_count: 1,
+        },
+    });
+    assert!(app.state.issue_list.rows.is_empty());
+
+    // Current result with gen2 should be applied.
+    app.update(Msg::IssueListLoaded {
+        generation: gen2,
+        page: crate::state::issue_list::IssueListPage {
+            rows: vec![crate::state::issue_list::IssueListRow {
+                project_path: "group/project".into(),
+                iid: 2,
+                title: "fresh".into(),
+                state: "opened".into(),
+                author: "taylor".into(),
+                labels: vec![],
+                updated_at: 1_700_000_000_000,
+            }],
+            next_cursor: None,
+            total_count: 1,
+        },
+    });
+    assert_eq!(app.state.issue_list.rows.len(), 1);
+    assert_eq!(app.state.issue_list.rows[0].title, "fresh");
+}
+
+#[test]
+fn test_crash_context_records_events() {
+    let mut app = test_app();
+    app.update(Msg::Tick);
+    app.update(Msg::NavigateTo(Screen::IssueList));
+
+    // Should have recorded at least 2 events.
+    assert!(app.crash_context.len() >= 2);
+}
+
+#[test]
+fn test_navigate_sets_loading_initial_on_first_visit() {
+    use crate::state::LoadState;
+
+    let mut app = test_app();
+    app.update(Msg::NavigateTo(Screen::IssueList));
+    // First visit should show full-screen spinner (LoadingInitial).
+    assert_eq!(
+        *app.state.load_state.get(&Screen::IssueList),
+        LoadState::LoadingInitial
+    );
+}
+
+#[test]
+fn test_navigate_sets_refreshing_on_revisit() {
+    use crate::state::LoadState;
+
+    let mut app = test_app();
+    // First visit → LoadingInitial.
+    app.update(Msg::NavigateTo(Screen::IssueList));
+    // Simulate load completing.
+    app.state.set_loading(Screen::IssueList, LoadState::Idle);
+    // Go back, then revisit.
+    app.update(Msg::GoBack);
+    app.update(Msg::NavigateTo(Screen::IssueList));
+    // Second visit should show corner spinner (Refreshing).
+    assert_eq!(
+        *app.state.load_state.get(&Screen::IssueList),
+        LoadState::Refreshing
+    );
+}
+
+#[test]
+fn test_command_palette_opens_from_ctrl_p() {
+    let mut app = test_app();
+    let key = KeyEvent::new(KeyCode::Char('p')).with_modifiers(Modifiers::CTRL);
+    app.update(Msg::RawEvent(Event::Key(key)));
+    assert!(matches!(app.input_mode, InputMode::Palette));
+    assert!(app.state.command_palette.query_focused);
+}
+
+#[test]
+fn test_esc_closes_palette() {
+    let mut app = test_app();
+    app.input_mode = InputMode::Palette;
+
+    let key = KeyEvent::new(KeyCode::Escape);
+    app.update(Msg::RawEvent(Event::Key(key)));
+
+    assert!(matches!(app.input_mode, InputMode::Normal));
+}
+
+#[test]
+fn test_blur_text_input_msg() {
+    let mut app = test_app();
+    app.input_mode = InputMode::Text;
+    app.state.search.query_focused = true;
+
+    app.update(Msg::BlurTextInput);
+
+    assert!(matches!(app.input_mode, InputMode::Normal));
+    assert!(!app.state.has_text_focus());
+}
+
+#[test]
+fn test_default_is_new() {
+    let app = LoreApp::default();
+    assert!(app.navigation.is_at(&Screen::Dashboard));
+    assert!(matches!(app.input_mode, InputMode::Normal));
+}

crates/lore-tui/src/app/update.rs

@@ -0,0 +1,367 @@
+//! Model trait impl and key dispatch for LoreApp.
+
+use chrono::TimeDelta;
+use ftui::{Cmd, Event, Frame, KeyCode, KeyEvent, Model, Modifiers};
+
+use crate::crash_context::CrashEvent;
+use crate::message::{InputMode, Msg, Screen};
+use crate::state::LoadState;
+use crate::task_supervisor::TaskKey;
+
+use super::LoreApp;
+
+/// Timeout for the g-prefix key sequence.
+const GO_PREFIX_TIMEOUT: TimeDelta = TimeDelta::milliseconds(500);
+
+impl LoreApp {
+    // -----------------------------------------------------------------------
+    // Key dispatch
+    // -----------------------------------------------------------------------
+
+    /// Normalize terminal key variants for cross-terminal consistency.
+    fn normalize_key(key: &mut KeyEvent) {
+        // BackTab -> Shift+Tab canonical form.
+        if key.code == KeyCode::BackTab {
+            key.code = KeyCode::Tab;
+            key.modifiers |= Modifiers::SHIFT;
+        }
+    }
+
+    /// 5-stage key dispatch pipeline.
+    ///
+    /// Returns the Cmd to execute (Quit, None, or a task command).
+    pub(crate) fn interpret_key(&mut self, mut key: KeyEvent) -> Cmd<Msg> {
+        Self::normalize_key(&mut key);
+
+        let screen = self.navigation.current().clone();
+
+        // Record key press in crash context.
+        self.crash_context.push(CrashEvent::KeyPress {
+            key: format!("{:?}", key.code),
+            mode: format!("{:?}", self.input_mode),
+            screen: screen.label().to_string(),
+        });
+
+        // --- Stage 1: Quit check ---
+        // Ctrl+C always quits regardless of mode.
+        if key.code == KeyCode::Char('c') && key.modifiers.contains(Modifiers::CTRL) {
+            return Cmd::quit();
+        }
+
+        // --- Stage 2: InputMode routing ---
+        match &self.input_mode {
+            InputMode::Text => {
+                return self.handle_text_mode_key(&key, &screen);
+            }
+            InputMode::Palette => {
+                return self.handle_palette_mode_key(&key, &screen);
+            }
+            InputMode::GoPrefix { started_at } => {
+                let elapsed = self.clock.now().signed_duration_since(*started_at);
+                if elapsed > GO_PREFIX_TIMEOUT {
+                    // Timeout expired — cancel prefix and re-process as normal.
+                    self.input_mode = InputMode::Normal;
+                } else {
+                    return self.handle_go_prefix_key(&key, &screen);
+                }
+            }
+            InputMode::Normal => {}
+        }
+
+        // --- Stage 3: Global shortcuts (Normal mode) ---
+        // 'q' quits.
+        if key.code == KeyCode::Char('q') && key.modifiers == Modifiers::NONE {
+            return Cmd::quit();
+        }
+
+        // 'g' starts prefix sequence.
+        if self
+            .command_registry
+            .is_sequence_starter(&key.code, &key.modifiers)
+        {
+            self.input_mode = InputMode::GoPrefix {
+                started_at: self.clock.now(),
+            };
+            return Cmd::none();
+        }
+
+        // Registry-based single-key lookup.
+        if let Some(cmd_def) =
+            self.command_registry
+                .lookup_key(&key.code, &key.modifiers, &screen, &self.input_mode)
+        {
+            return self.execute_command(cmd_def.id, &screen);
+        }
+
+        // --- Stage 4: Screen-local keys ---
+        // Delegated to AppState::interpret_screen_key in future phases.
+
+        // --- Stage 5: Fallback (unhandled) ---
+        Cmd::none()
+    }
+
+    /// Handle keys in Text input mode.
+    ///
+    /// Only Esc and Ctrl+P pass through; everything else is consumed by
+    /// the focused text widget (handled in future phases).
+    fn handle_text_mode_key(&mut self, key: &KeyEvent, screen: &Screen) -> Cmd<Msg> {
+        // Esc blurs the text input.
+        if key.code == KeyCode::Escape {
+            self.state.blur_text_focus();
+            self.input_mode = InputMode::Normal;
+            return Cmd::none();
+        }
+
+        // Ctrl+P opens palette even in text mode.
+        if let Some(cmd_def) =
+            self.command_registry
+                .lookup_key(&key.code, &key.modifiers, screen, &InputMode::Text)
+        {
+            return self.execute_command(cmd_def.id, screen);
+        }
+
+        // All other keys consumed by text widget (future).
+        Cmd::none()
+    }
+
+    /// Handle keys in Palette mode.
+    fn handle_palette_mode_key(&mut self, key: &KeyEvent, _screen: &Screen) -> Cmd<Msg> {
+        if key.code == KeyCode::Escape {
+            self.input_mode = InputMode::Normal;
+            return Cmd::none();
+        }
+        // Palette key dispatch will be expanded in the palette widget phase.
+        Cmd::none()
+    }
+
+    /// Handle the second key of a g-prefix sequence.
+    fn handle_go_prefix_key(&mut self, key: &KeyEvent, screen: &Screen) -> Cmd<Msg> {
+        self.input_mode = InputMode::Normal;
+
+        if let Some(cmd_def) = self.command_registry.complete_sequence(
+            &KeyCode::Char('g'),
+            &Modifiers::NONE,
+            &key.code,
+            &key.modifiers,
+            screen,
+        ) {
+            return self.execute_command(cmd_def.id, screen);
+        }
+
+        // Invalid second key — cancel prefix silently.
+        Cmd::none()
+    }
+
+    /// Execute a command by ID.
+    fn execute_command(&mut self, id: &str, _screen: &Screen) -> Cmd<Msg> {
+        match id {
+            "quit" => Cmd::quit(),
+            "go_back" => {
+                self.navigation.pop();
+                Cmd::none()
+            }
+            "show_help" => {
+                self.state.show_help = !self.state.show_help;
+                Cmd::none()
+            }
+            "command_palette" => {
+                self.input_mode = InputMode::Palette;
+                self.state.command_palette.query_focused = true;
+                Cmd::none()
+            }
+            "open_in_browser" => {
+                // Will dispatch OpenInBrowser msg in future phase.
+                Cmd::none()
+            }
+            "show_cli" => {
+                // Will show CLI equivalent in future phase.
+                Cmd::none()
+            }
+            "go_home" => self.navigate_to(Screen::Dashboard),
+            "go_issues" => self.navigate_to(Screen::IssueList),
+            "go_mrs" => self.navigate_to(Screen::MrList),
+            "go_search" => self.navigate_to(Screen::Search),
+            "go_timeline" => self.navigate_to(Screen::Timeline),
+            "go_who" => self.navigate_to(Screen::Who),
+            "go_sync" => self.navigate_to(Screen::Sync),
+            "jump_back" => {
+                self.navigation.jump_back();
+                Cmd::none()
+            }
+            "jump_forward" => {
+                self.navigation.jump_forward();
+                Cmd::none()
+            }
+            "move_down" | "move_up" | "select_item" | "focus_filter" | "scroll_to_top" => {
+                // Screen-specific actions — delegated in future phases.
+                Cmd::none()
+            }
+            _ => Cmd::none(),
+        }
+    }
+
+    // -----------------------------------------------------------------------
+    // Navigation helpers
+    // -----------------------------------------------------------------------
+
+    /// Navigate to a screen, pushing the nav stack and starting a data load.
+    fn navigate_to(&mut self, screen: Screen) -> Cmd<Msg> {
+        let screen_label = screen.label().to_string();
+        let current_label = self.navigation.current().label().to_string();
+
+        self.crash_context.push(CrashEvent::StateTransition {
+            from: current_label,
+            to: screen_label,
+        });
+
+        self.navigation.push(screen.clone());
+
+        // First visit → full-screen spinner; revisit → corner spinner over stale data.
+        let load_state = if self.state.load_state.was_visited(&screen) {
+            LoadState::Refreshing
+        } else {
+            LoadState::LoadingInitial
+        };
+        self.state.set_loading(screen.clone(), load_state);
+
+        // Spawn supervised task for data loading (placeholder — actual DB
+        // query dispatch comes in Phase 2 screen implementations).
+        let _handle = self.supervisor.submit(TaskKey::LoadScreen(screen));
+
+        Cmd::none()
+    }
+
+    // -----------------------------------------------------------------------
+    // Message dispatch (non-key)
+    // -----------------------------------------------------------------------
+
+    /// Handle non-key messages.
+    pub(crate) fn handle_msg(&mut self, msg: Msg) -> Cmd<Msg> {
+        // Record in crash context.
+        self.crash_context.push(CrashEvent::MsgDispatched {
+            msg_name: format!("{msg:?}")
+                .split('(')
+                .next()
+                .unwrap_or("?")
+                .to_string(),
+            screen: self.navigation.current().label().to_string(),
+        });
+
+        match msg {
+            Msg::Quit => Cmd::quit(),
+
+            // --- Navigation ---
+            Msg::NavigateTo(screen) => self.navigate_to(screen),
+            Msg::GoBack => {
+                self.navigation.pop();
+                Cmd::none()
+            }
+            Msg::GoForward => {
+                self.navigation.go_forward();
+                Cmd::none()
+            }
+            Msg::GoHome => self.navigate_to(Screen::Dashboard),
+            Msg::JumpBack(_) => {
+                self.navigation.jump_back();
+                Cmd::none()
+            }
+            Msg::JumpForward(_) => {
+                self.navigation.jump_forward();
+                Cmd::none()
+            }
+
+            // --- Error ---
+            Msg::Error(err) => {
+                self.state.set_error(err.to_string());
+                Cmd::none()
+            }
+
+            // --- Help / UI ---
+            Msg::ShowHelp => {
+                self.state.show_help = !self.state.show_help;
+                Cmd::none()
+            }
+            Msg::BlurTextInput => {
+                self.state.blur_text_focus();
+                self.input_mode = InputMode::Normal;
+                Cmd::none()
+            }
+
+            // --- Terminal ---
+            Msg::Resize { width, height } => {
+                self.state.terminal_size = (width, height);
+                Cmd::none()
+            }
+            Msg::Tick => Cmd::none(),
+
+            // --- Loaded results (stale guard) ---
+            Msg::IssueListLoaded { generation, page } => {
+                if self
+                    .supervisor
+                    .is_current(&TaskKey::LoadScreen(Screen::IssueList), generation)
+                {
+                    self.state.issue_list.apply_page(page);
+                    self.state.set_loading(Screen::IssueList, LoadState::Idle);
+                    self.supervisor
+                        .complete(&TaskKey::LoadScreen(Screen::IssueList), generation);
+                }
+                Cmd::none()
+            }
+            Msg::MrListLoaded { generation, page } => {
+                if self
+                    .supervisor
+                    .is_current(&TaskKey::LoadScreen(Screen::MrList), generation)
+                {
+                    self.state.mr_list.apply_page(page);
+                    self.state.set_loading(Screen::MrList, LoadState::Idle);
+                    self.supervisor
+                        .complete(&TaskKey::LoadScreen(Screen::MrList), generation);
+                }
+                Cmd::none()
+            }
+            Msg::DashboardLoaded { generation, data } => {
+                if self
+                    .supervisor
+                    .is_current(&TaskKey::LoadScreen(Screen::Dashboard), generation)
+                {
+                    self.state.dashboard.update(*data);
+                    self.state.set_loading(Screen::Dashboard, LoadState::Idle);
+                    self.supervisor
+                        .complete(&TaskKey::LoadScreen(Screen::Dashboard), generation);
+                }
+                Cmd::none()
+            }
+
+            // All other message variants: no-op for now.
+            // Future phases will fill these in as screens are implemented.
+            _ => Cmd::none(),
+        }
+    }
+}
+
+impl Model for LoreApp {
+    type Message = Msg;
+
+    fn init(&mut self) -> Cmd<Self::Message> {
+        // Install crash context panic hook.
+        crate::crash_context::CrashContext::install_panic_hook(&self.crash_context);
+        crate::crash_context::CrashContext::prune_crash_files();
+
+        // Navigate to dashboard (will trigger data load in future phase).
+        Cmd::none()
+    }
+
+    fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
+        // Route raw key events through the 5-stage pipeline.
+        if let Msg::RawEvent(Event::Key(key)) = msg {
+            return self.interpret_key(key);
+        }
+
+        // Everything else goes through message dispatch.
+        self.handle_msg(msg)
+    }
+
+    fn view(&self, frame: &mut Frame) {
+        crate::view::render_screen(frame, self);
+    }
+}

crates/lore-tui/src/clock.rs

@@ -0,0 +1,165 @@
+//! Injected clock for deterministic time in tests and consistent frame timestamps.
+//!
+//! All relative-time rendering (e.g., "3h ago") uses [`Clock::now()`] rather
+//! than wall-clock time directly. This enables:
+//! - Deterministic snapshot tests via [`FakeClock`]
+//! - Consistent timestamps within a single frame render pass
+
+use std::sync::{Arc, Mutex};
+
+use chrono::{DateTime, TimeDelta, Utc};
+
+/// Trait for obtaining the current time.
+///
+/// Inject via `Arc<dyn Clock>` to allow swapping between real and fake clocks.
+pub trait Clock: Send + Sync {
+    /// Returns the current time.
+    fn now(&self) -> DateTime<Utc>;
+
+    /// Returns the current time as milliseconds since the Unix epoch.
+    fn now_ms(&self) -> i64 {
+        self.now().timestamp_millis()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// SystemClock
+// ---------------------------------------------------------------------------
+
+/// Real wall-clock time via `chrono::Utc::now()`.
+#[derive(Debug, Clone, Copy)]
+pub struct SystemClock;
+
+impl Clock for SystemClock {
+    fn now(&self) -> DateTime<Utc> {
+        Utc::now()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// FakeClock
+// ---------------------------------------------------------------------------
+
+/// A controllable clock for tests. Returns a frozen time that can be
+/// advanced or set explicitly.
+///
+/// `FakeClock` is `Clone` (shares the inner `Arc`) and `Send + Sync`
+/// for use across `Cmd::task` threads.
+#[derive(Debug, Clone)]
+pub struct FakeClock {
+    inner: Arc<Mutex<DateTime<Utc>>>,
+}
+
+impl FakeClock {
+    /// Create a fake clock frozen at the given time.
+    #[must_use]
+    pub fn new(time: DateTime<Utc>) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(time)),
+        }
+    }
+
+    /// Create a fake clock frozen at the given millisecond epoch timestamp.
+    ///
+    /// Convenience for action tests that work with raw epoch milliseconds.
+    #[must_use]
+    pub fn from_ms(epoch_ms: i64) -> Self {
+        let time = DateTime::from_timestamp_millis(epoch_ms).expect("valid millisecond timestamp");
+        Self::new(time)
+    }
+
+    /// Advance the clock by `duration`. Uses `checked_add` to handle overflow
+    /// gracefully — if the addition would overflow, the time is not changed.
+    pub fn advance(&self, duration: TimeDelta) {
+        let mut guard = self.inner.lock().expect("FakeClock mutex poisoned");
+        if let Some(advanced) = guard.checked_add_signed(duration) {
+            *guard = advanced;
+        }
+    }
+
+    /// Set the clock to an exact time.
+    pub fn set(&self, time: DateTime<Utc>) {
+        let mut guard = self.inner.lock().expect("FakeClock mutex poisoned");
+        *guard = time;
+    }
+}
+
+impl Clock for FakeClock {
+    fn now(&self) -> DateTime<Utc> {
+        *self.inner.lock().expect("FakeClock mutex poisoned")
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::TimeZone;
+
+    fn fixed_time() -> DateTime<Utc> {
+        Utc.with_ymd_and_hms(2026, 2, 12, 12, 0, 0).unwrap()
+    }
+
+    #[test]
+    fn test_fake_clock_frozen() {
+        let clock = FakeClock::new(fixed_time());
+        let t1 = clock.now();
+        let t2 = clock.now();
+        assert_eq!(t1, t2);
+        assert_eq!(t1, fixed_time());
+    }
+
+    #[test]
+    fn test_fake_clock_advance() {
+        let clock = FakeClock::new(fixed_time());
+        clock.advance(TimeDelta::hours(3));
+        let expected = Utc.with_ymd_and_hms(2026, 2, 12, 15, 0, 0).unwrap();
+        assert_eq!(clock.now(), expected);
+    }
+
+    #[test]
+    fn test_fake_clock_set() {
+        let clock = FakeClock::new(fixed_time());
+        let new_time = Utc.with_ymd_and_hms(2030, 1, 1, 0, 0, 0).unwrap();
+        clock.set(new_time);
+        assert_eq!(clock.now(), new_time);
+    }
+
+    #[test]
+    fn test_fake_clock_clone_shares_state() {
+        let clock1 = FakeClock::new(fixed_time());
+        let clock2 = clock1.clone();
+        clock1.advance(TimeDelta::minutes(30));
+        // Both clones see the advanced time.
+        assert_eq!(clock1.now(), clock2.now());
+    }
+
+    #[test]
+    fn test_system_clock_returns_reasonable_time() {
+        let clock = SystemClock;
+        let now = clock.now();
+        // Sanity: time should be after 2025.
+        assert!(now.year() >= 2025);
+    }
+
+    #[test]
+    fn test_fake_clock_is_send_sync() {
+        fn assert_send_sync<T: Send + Sync>() {}
+        assert_send_sync::<FakeClock>();
+        assert_send_sync::<SystemClock>();
+    }
+
+    #[test]
+    fn test_clock_trait_object_works() {
+        let fake: Arc<dyn Clock> = Arc::new(FakeClock::new(fixed_time()));
+        assert_eq!(fake.now(), fixed_time());
+
+        let real: Arc<dyn Clock> = Arc::new(SystemClock);
+        let _ = real.now(); // Just verify it doesn't panic.
+    }
+
+    use chrono::Datelike;
+}

crates/lore-tui/src/commands.rs.bak

@@ -0,0 +1,807 @@
+#![allow(dead_code)] // Phase 1: consumed by LoreApp in bd-6pmy
+
+//! Command registry — single source of truth for all TUI actions.
+//!
+//! Every keybinding, palette entry, help text, CLI equivalent, and
+//! status hint is generated from [`CommandRegistry`]. No hardcoded
+//! duplicate maps exist in view/state modules.
+//!
+//! Supports single-key and two-key sequences (g-prefix vim bindings).
+
+use std::collections::HashMap;
+
+use ftui::{KeyCode, Modifiers};
+
+use crate::message::{InputMode, Screen};
+
+// ---------------------------------------------------------------------------
+// Key formatting
+// ---------------------------------------------------------------------------
+
+/// Format a key code + modifiers as a human-readable string.
+fn format_key(code: KeyCode, modifiers: Modifiers) -> String {
+    let mut parts = Vec::new();
+    if modifiers.contains(Modifiers::CTRL) {
+        parts.push("Ctrl");
+    }
+    if modifiers.contains(Modifiers::ALT) {
+        parts.push("Alt");
+    }
+    if modifiers.contains(Modifiers::SHIFT) {
+        parts.push("Shift");
+    }
+    let key_name = match code {
+        KeyCode::Char(c) => c.to_string(),
+        KeyCode::Enter => "Enter".to_string(),
+        KeyCode::Escape => "Esc".to_string(),
+        KeyCode::Tab => "Tab".to_string(),
+        KeyCode::Backspace => "Backspace".to_string(),
+        KeyCode::Delete => "Del".to_string(),
+        KeyCode::Up => "Up".to_string(),
+        KeyCode::Down => "Down".to_string(),
+        KeyCode::Left => "Left".to_string(),
+        KeyCode::Right => "Right".to_string(),
+        KeyCode::Home => "Home".to_string(),
+        KeyCode::End => "End".to_string(),
+        KeyCode::PageUp => "PgUp".to_string(),
+        KeyCode::PageDown => "PgDn".to_string(),
+        KeyCode::F(n) => format!("F{n}"),
+        _ => "?".to_string(),
+    };
+    parts.push(&key_name);
+    // We need to own the joined string.
+    let joined: String = parts.join("+");
+    joined
+}
+
+// ---------------------------------------------------------------------------
+// KeyCombo
+// ---------------------------------------------------------------------------
+
+/// A keybinding: either a single key or a two-key sequence.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum KeyCombo {
+    /// Single key press (e.g., `q`, `Esc`, `Ctrl+P`).
+    Single { code: KeyCode, modifiers: Modifiers },
+    /// Two-key sequence (e.g., `g` then `i` for go-to-issues).
+    Sequence {
+        first_code: KeyCode,
+        first_modifiers: Modifiers,
+        second_code: KeyCode,
+        second_modifiers: Modifiers,
+    },
+}
+
+impl KeyCombo {
+    /// Convenience: single key with no modifiers.
+    #[must_use]
+    pub const fn key(code: KeyCode) -> Self {
+        Self::Single {
+            code,
+            modifiers: Modifiers::NONE,
+        }
+    }
+
+    /// Convenience: single key with Ctrl modifier.
+    #[must_use]
+    pub const fn ctrl(code: KeyCode) -> Self {
+        Self::Single {
+            code,
+            modifiers: Modifiers::CTRL,
+        }
+    }
+
+    /// Convenience: g-prefix sequence (g + char).
+    #[must_use]
+    pub const fn g_then(c: char) -> Self {
+        Self::Sequence {
+            first_code: KeyCode::Char('g'),
+            first_modifiers: Modifiers::NONE,
+            second_code: KeyCode::Char(c),
+            second_modifiers: Modifiers::NONE,
+        }
+    }
+
+    /// Human-readable display string for this key combo.
+    #[must_use]
+    pub fn display(&self) -> String {
+        match self {
+            Self::Single { code, modifiers } => format_key(*code, *modifiers),
+            Self::Sequence {
+                first_code,
+                first_modifiers,
+                second_code,
+                second_modifiers,
+            } => {
+                let first = format_key(*first_code, *first_modifiers);
+                let second = format_key(*second_code, *second_modifiers);
+                format!("{first} {second}")
+            }
+        }
+    }
+
+    /// Whether this combo starts with the given key.
+    #[must_use]
+    pub fn starts_with(&self, code: &KeyCode, modifiers: &Modifiers) -> bool {
+        match self {
+            Self::Single {
+                code: c,
+                modifiers: m,
+            } => c == code && m == modifiers,
+            Self::Sequence {
+                first_code,
+                first_modifiers,
+                ..
+            } => first_code == code && first_modifiers == modifiers,
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// ScreenFilter
+// ---------------------------------------------------------------------------
+
+/// Specifies which screens a command is available on.
+#[derive(Debug, Clone)]
+pub enum ScreenFilter {
+    /// Available on all screens.
+    Global,
+    /// Available only on specific screens.
+    Only(Vec<Screen>),
+}
+
+impl ScreenFilter {
+    /// Whether the command is available on the given screen.
+    #[must_use]
+    pub fn matches(&self, screen: &Screen) -> bool {
+        match self {
+            Self::Global => true,
+            Self::Only(screens) => screens.contains(screen),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// CommandDef
+// ---------------------------------------------------------------------------
+
+/// Unique command identifier.
+pub type CommandId = &'static str;
+
+/// A registered command with its keybinding, help text, and scope.
+#[derive(Debug, Clone)]
+pub struct CommandDef {
+    /// Unique identifier (e.g., "quit", "go_issues").
+    pub id: CommandId,
+    /// Human-readable label for palette and help overlay.
+    pub label: &'static str,
+    /// Keybinding (if any).
+    pub keybinding: Option<KeyCombo>,
+    /// Equivalent `lore` CLI command (for "Show CLI equivalent" feature).
+    pub cli_equivalent: Option<&'static str>,
+    /// Description for help overlay.
+    pub help_text: &'static str,
+    /// Short hint for status bar (e.g., "q:quit").
+    pub status_hint: &'static str,
+    /// Which screens this command is available on.
+    pub available_in: ScreenFilter,
+    /// Whether this command works in Text input mode.
+    pub available_in_text_mode: bool,
+}
+
+// ---------------------------------------------------------------------------
+// CommandRegistry
+// ---------------------------------------------------------------------------
+
+/// Single source of truth for all TUI commands.
+///
+/// Built once at startup via [`build_registry`]. Provides O(1) lookup
+/// by keybinding and per-screen filtering.
+pub struct CommandRegistry {
+    commands: Vec<CommandDef>,
+    /// Single-key -> command IDs that start with this key.
+    by_single_key: HashMap<(KeyCode, Modifiers), Vec<usize>>,
+    /// Full sequence -> command index (for two-key combos).
+    by_sequence: HashMap<KeyCombo, usize>,
+}
+
+impl CommandRegistry {
+    /// Look up a command by a single key press on a given screen and input mode.
+    ///
+    /// Returns `None` if no matching command is found. For sequence starters
+    /// (like 'g'), returns `None` — use [`is_sequence_starter`] to detect
+    /// that case.
+    #[must_use]
+    pub fn lookup_key(
+        &self,
+        code: &KeyCode,
+        modifiers: &Modifiers,
+        screen: &Screen,
+        mode: &InputMode,
+    ) -> Option<&CommandDef> {
+        let is_text = matches!(mode, InputMode::Text);
+        let key = (*code, *modifiers);
+
+        let indices = self.by_single_key.get(&key)?;
+        for &idx in indices {
+            let cmd = &self.commands[idx];
+            if !cmd.available_in.matches(screen) {
+                continue;
+            }
+            if is_text && !cmd.available_in_text_mode {
+                continue;
+            }
+            // Only match Single combos here, not sequence starters.
+            if let Some(KeyCombo::Single { .. }) = &cmd.keybinding {
+                return Some(cmd);
+            }
+        }
+        None
+    }
+
+    /// Complete a two-key sequence.
+    ///
+    /// Called after the first key of a sequence is detected (e.g., after 'g').
+    #[must_use]
+    pub fn complete_sequence(
+        &self,
+        first_code: &KeyCode,
+        first_modifiers: &Modifiers,
+        second_code: &KeyCode,
+        second_modifiers: &Modifiers,
+        screen: &Screen,
+    ) -> Option<&CommandDef> {
+        let combo = KeyCombo::Sequence {
+            first_code: *first_code,
+            first_modifiers: *first_modifiers,
+            second_code: *second_code,
+            second_modifiers: *second_modifiers,
+        };
+        let &idx = self.by_sequence.get(&combo)?;
+        let cmd = &self.commands[idx];
+        if cmd.available_in.matches(screen) {
+            Some(cmd)
+        } else {
+            None
+        }
+    }
+
+    /// Whether a key starts a multi-key sequence (e.g., 'g').
+    #[must_use]
+    pub fn is_sequence_starter(&self, code: &KeyCode, modifiers: &Modifiers) -> bool {
+        self.by_sequence
+            .keys()
+            .any(|combo| combo.starts_with(code, modifiers))
+    }
+
+    /// Commands available for the command palette on a given screen.
+    ///
+    /// Returned sorted by label.
+    #[must_use]
+    pub fn palette_entries(&self, screen: &Screen) -> Vec<&CommandDef> {
+        let mut entries: Vec<&CommandDef> = self
+            .commands
+            .iter()
+            .filter(|c| c.available_in.matches(screen))
+            .collect();
+        entries.sort_by_key(|c| c.label);
+        entries
+    }
+
+    /// Commands for the help overlay on a given screen.
+    #[must_use]
+    pub fn help_entries(&self, screen: &Screen) -> Vec<&CommandDef> {
+        self.commands
+            .iter()
+            .filter(|c| c.available_in.matches(screen))
+            .filter(|c| c.keybinding.is_some())
+            .collect()
+    }
+
+    /// Status bar hints for the current screen.
+    #[must_use]
+    pub fn status_hints(&self, screen: &Screen) -> Vec<&str> {
+        self.commands
+            .iter()
+            .filter(|c| c.available_in.matches(screen))
+            .filter(|c| !c.status_hint.is_empty())
+            .map(|c| c.status_hint)
+            .collect()
+    }
+
+    /// Total number of registered commands.
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.commands.len()
+    }
+
+    /// Whether the registry has no commands.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.commands.is_empty()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// build_registry
+// ---------------------------------------------------------------------------
+
+/// Build the command registry with all TUI commands.
+///
+/// This is the single source of truth — every keybinding, help text,
+/// and palette entry originates here.
+#[must_use]
+pub fn build_registry() -> CommandRegistry {
+    let commands = vec![
+        // --- Global commands ---
+        CommandDef {
+            id: "quit",
+            label: "Quit",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('q'))),
+            cli_equivalent: None,
+            help_text: "Exit the TUI",
+            status_hint: "q:quit",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_back",
+            label: "Go Back",
+            keybinding: Some(KeyCombo::key(KeyCode::Escape)),
+            cli_equivalent: None,
+            help_text: "Go back to previous screen",
+            status_hint: "esc:back",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: true,
+        },
+        CommandDef {
+            id: "show_help",
+            label: "Help",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('?'))),
+            cli_equivalent: None,
+            help_text: "Show keybinding help overlay",
+            status_hint: "?:help",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "command_palette",
+            label: "Command Palette",
+            keybinding: Some(KeyCombo::ctrl(KeyCode::Char('p'))),
+            cli_equivalent: None,
+            help_text: "Open command palette",
+            status_hint: "C-p:palette",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: true,
+        },
+        CommandDef {
+            id: "open_in_browser",
+            label: "Open in Browser",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('o'))),
+            cli_equivalent: None,
+            help_text: "Open current entity in browser",
+            status_hint: "o:browser",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "show_cli",
+            label: "Show CLI Equivalent",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('!'))),
+            cli_equivalent: None,
+            help_text: "Show equivalent lore CLI command",
+            status_hint: "",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        // --- Navigation: g-prefix sequences ---
+        CommandDef {
+            id: "go_home",
+            label: "Go to Dashboard",
+            keybinding: Some(KeyCombo::g_then('h')),
+            cli_equivalent: None,
+            help_text: "Jump to dashboard",
+            status_hint: "gh:home",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_issues",
+            label: "Go to Issues",
+            keybinding: Some(KeyCombo::g_then('i')),
+            cli_equivalent: Some("lore issues"),
+            help_text: "Jump to issue list",
+            status_hint: "gi:issues",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_mrs",
+            label: "Go to Merge Requests",
+            keybinding: Some(KeyCombo::g_then('m')),
+            cli_equivalent: Some("lore mrs"),
+            help_text: "Jump to MR list",
+            status_hint: "gm:mrs",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_search",
+            label: "Go to Search",
+            keybinding: Some(KeyCombo::g_then('/')),
+            cli_equivalent: Some("lore search"),
+            help_text: "Jump to search",
+            status_hint: "g/:search",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_timeline",
+            label: "Go to Timeline",
+            keybinding: Some(KeyCombo::g_then('t')),
+            cli_equivalent: Some("lore timeline"),
+            help_text: "Jump to timeline",
+            status_hint: "gt:timeline",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_who",
+            label: "Go to Who",
+            keybinding: Some(KeyCombo::g_then('w')),
+            cli_equivalent: Some("lore who"),
+            help_text: "Jump to people intelligence",
+            status_hint: "gw:who",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_sync",
+            label: "Go to Sync",
+            keybinding: Some(KeyCombo::g_then('s')),
+            cli_equivalent: Some("lore sync"),
+            help_text: "Jump to sync status",
+            status_hint: "gs:sync",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        // --- Vim-style jump list ---
+        CommandDef {
+            id: "jump_back",
+            label: "Jump Back",
+            keybinding: Some(KeyCombo::ctrl(KeyCode::Char('o'))),
+            cli_equivalent: None,
+            help_text: "Jump backward through visited detail views",
+            status_hint: "C-o:jump back",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "jump_forward",
+            label: "Jump Forward",
+            keybinding: Some(KeyCombo::ctrl(KeyCode::Char('i'))),
+            cli_equivalent: None,
+            help_text: "Jump forward through visited detail views",
+            status_hint: "",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        // --- List navigation ---
+        CommandDef {
+            id: "move_down",
+            label: "Move Down",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('j'))),
+            cli_equivalent: None,
+            help_text: "Move cursor down",
+            status_hint: "j:down",
+            available_in: ScreenFilter::Only(vec![
+                Screen::IssueList,
+                Screen::MrList,
+                Screen::Search,
+                Screen::Timeline,
+            ]),
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "move_up",
+            label: "Move Up",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('k'))),
+            cli_equivalent: None,
+            help_text: "Move cursor up",
+            status_hint: "k:up",
+            available_in: ScreenFilter::Only(vec![
+                Screen::IssueList,
+                Screen::MrList,
+                Screen::Search,
+                Screen::Timeline,
+            ]),
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "select_item",
+            label: "Select",
+            keybinding: Some(KeyCombo::key(KeyCode::Enter)),
+            cli_equivalent: None,
+            help_text: "Open selected item",
+            status_hint: "enter:open",
+            available_in: ScreenFilter::Only(vec![
+                Screen::IssueList,
+                Screen::MrList,
+                Screen::Search,
+            ]),
+            available_in_text_mode: false,
+        },
+        // --- Filter ---
+        CommandDef {
+            id: "focus_filter",
+            label: "Filter",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('/'))),
+            cli_equivalent: None,
+            help_text: "Focus the filter input",
+            status_hint: "/:filter",
+            available_in: ScreenFilter::Only(vec![Screen::IssueList, Screen::MrList]),
+            available_in_text_mode: false,
+        },
+        // --- Scroll ---
+        CommandDef {
+            id: "scroll_to_top",
+            label: "Scroll to Top",
+            keybinding: Some(KeyCombo::g_then('g')),
+            cli_equivalent: None,
+            help_text: "Scroll to the top of the current view",
+            status_hint: "",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+    ];
+
+    build_from_defs(commands)
+}
+
+/// Build index maps from a list of command definitions.
+fn build_from_defs(commands: Vec<CommandDef>) -> CommandRegistry {
+    let mut by_single_key: HashMap<(KeyCode, Modifiers), Vec<usize>> = HashMap::new();
+    let mut by_sequence: HashMap<KeyCombo, usize> = HashMap::new();
+
+    for (idx, cmd) in commands.iter().enumerate() {
+        if let Some(combo) = &cmd.keybinding {
+            match combo {
+                KeyCombo::Single { code, modifiers } => {
+                    by_single_key
+                        .entry((*code, *modifiers))
+                        .or_default()
+                        .push(idx);
+                }
+                KeyCombo::Sequence { .. } => {
+                    by_sequence.insert(combo.clone(), idx);
+                    // Also index the first key so is_sequence_starter works via by_single_key.
+                    if let KeyCombo::Sequence {
+                        first_code,
+                        first_modifiers,
+                        ..
+                    } = combo
+                    {
+                        by_single_key
+                            .entry((*first_code, *first_modifiers))
+                            .or_default()
+                            .push(idx);
+                    }
+                }
+            }
+        }
+    }
+
+    CommandRegistry {
+        commands,
+        by_single_key,
+        by_sequence,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::Utc;
+
+    #[test]
+    fn test_registry_builds_successfully() {
+        let reg = build_registry();
+        assert!(!reg.is_empty());
+        assert!(reg.len() >= 15);
+    }
+
+    #[test]
+    fn test_registry_lookup_quit() {
+        let reg = build_registry();
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('q'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+            &InputMode::Normal,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "quit");
+    }
+
+    #[test]
+    fn test_registry_lookup_quit_blocked_in_text_mode() {
+        let reg = build_registry();
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('q'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+            &InputMode::Text,
+        );
+        assert!(cmd.is_none());
+    }
+
+    #[test]
+    fn test_registry_esc_works_in_text_mode() {
+        let reg = build_registry();
+        let cmd = reg.lookup_key(
+            &KeyCode::Escape,
+            &Modifiers::NONE,
+            &Screen::IssueList,
+            &InputMode::Text,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "go_back");
+    }
+
+    #[test]
+    fn test_registry_ctrl_p_works_in_text_mode() {
+        let reg = build_registry();
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('p'),
+            &Modifiers::CTRL,
+            &Screen::Search,
+            &InputMode::Text,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "command_palette");
+    }
+
+    #[test]
+    fn test_g_is_sequence_starter() {
+        let reg = build_registry();
+        assert!(reg.is_sequence_starter(&KeyCode::Char('g'), &Modifiers::NONE));
+        assert!(!reg.is_sequence_starter(&KeyCode::Char('x'), &Modifiers::NONE));
+    }
+
+    #[test]
+    fn test_complete_sequence_gi() {
+        let reg = build_registry();
+        let cmd = reg.complete_sequence(
+            &KeyCode::Char('g'),
+            &Modifiers::NONE,
+            &KeyCode::Char('i'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "go_issues");
+    }
+
+    #[test]
+    fn test_complete_sequence_invalid_second_key() {
+        let reg = build_registry();
+        let cmd = reg.complete_sequence(
+            &KeyCode::Char('g'),
+            &Modifiers::NONE,
+            &KeyCode::Char('x'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+        );
+        assert!(cmd.is_none());
+    }
+
+    #[test]
+    fn test_screen_specific_command() {
+        let reg = build_registry();
+        // 'j' (move_down) should work on IssueList
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('j'),
+            &Modifiers::NONE,
+            &Screen::IssueList,
+            &InputMode::Normal,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "move_down");
+
+        // 'j' should NOT match on Dashboard (move_down is list-only).
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('j'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+            &InputMode::Normal,
+        );
+        assert!(cmd.is_none());
+    }
+
+    #[test]
+    fn test_palette_entries_sorted_by_label() {
+        let reg = build_registry();
+        let entries = reg.palette_entries(&Screen::Dashboard);
+        let labels: Vec<&str> = entries.iter().map(|c| c.label).collect();
+        let mut sorted = labels.clone();
+        sorted.sort();
+        assert_eq!(labels, sorted);
+    }
+
+    #[test]
+    fn test_help_entries_only_include_keybindings() {
+        let reg = build_registry();
+        let entries = reg.help_entries(&Screen::Dashboard);
+        for entry in &entries {
+            assert!(
+                entry.keybinding.is_some(),
+                "help entry without keybinding: {}",
+                entry.id
+            );
+        }
+    }
+
+    #[test]
+    fn test_status_hints_non_empty() {
+        let reg = build_registry();
+        let hints = reg.status_hints(&Screen::Dashboard);
+        assert!(!hints.is_empty());
+        // All returned hints should be non-empty strings.
+        for hint in &hints {
+            assert!(!hint.is_empty());
+        }
+    }
+
+    #[test]
+    fn test_cli_equivalents_populated() {
+        let reg = build_registry();
+        let with_cli: Vec<&CommandDef> = reg
+            .commands
+            .iter()
+            .filter(|c| c.cli_equivalent.is_some())
+            .collect();
+        assert!(
+            with_cli.len() >= 5,
+            "expected at least 5 commands with cli_equivalent, got {}",
+            with_cli.len()
+        );
+    }
+
+    #[test]
+    fn test_go_prefix_timeout_detection() {
+        let reg = build_registry();
+        // Simulate GoPrefix mode entering: 'g' detected as sequence starter.
+        assert!(reg.is_sequence_starter(&KeyCode::Char('g'), &Modifiers::NONE));
+
+        // Simulate InputMode::GoPrefix with timeout check.
+        let started = Utc::now();
+        let mode = InputMode::GoPrefix {
+            started_at: started,
+        };
+        // In GoPrefix mode, normal lookup should still work for non-sequence keys.
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('q'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+            &mode,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "quit");
+    }
+
+    #[test]
+    fn test_all_commands_have_nonempty_help() {
+        let reg = build_registry();
+        for cmd in &reg.commands {
+            assert!(
+                !cmd.help_text.is_empty(),
+                "command {} has empty help_text",
+                cmd.id
+            );
+        }
+    }
+}

crates/lore-tui/src/commands/defs.rs

@@ -0,0 +1,180 @@
+//! Command definitions — types for keybindings, screen filtering, and command metadata.
+
+use ftui::{KeyCode, Modifiers};
+
+use crate::message::Screen;
+
+// ---------------------------------------------------------------------------
+// Key formatting
+// ---------------------------------------------------------------------------
+
+/// Format a key code + modifiers as a human-readable string.
+pub(crate) fn format_key(code: KeyCode, modifiers: Modifiers) -> String {
+    let mut parts = Vec::new();
+    if modifiers.contains(Modifiers::CTRL) {
+        parts.push("Ctrl");
+    }
+    if modifiers.contains(Modifiers::ALT) {
+        parts.push("Alt");
+    }
+    if modifiers.contains(Modifiers::SHIFT) {
+        parts.push("Shift");
+    }
+    let key_name = match code {
+        KeyCode::Char(c) => c.to_string(),
+        KeyCode::Enter => "Enter".to_string(),
+        KeyCode::Escape => "Esc".to_string(),
+        KeyCode::Tab => "Tab".to_string(),
+        KeyCode::Backspace => "Backspace".to_string(),
+        KeyCode::Delete => "Del".to_string(),
+        KeyCode::Up => "Up".to_string(),
+        KeyCode::Down => "Down".to_string(),
+        KeyCode::Left => "Left".to_string(),
+        KeyCode::Right => "Right".to_string(),
+        KeyCode::Home => "Home".to_string(),
+        KeyCode::End => "End".to_string(),
+        KeyCode::PageUp => "PgUp".to_string(),
+        KeyCode::PageDown => "PgDn".to_string(),
+        KeyCode::F(n) => format!("F{n}"),
+        _ => "?".to_string(),
+    };
+    parts.push(&key_name);
+    // We need to own the joined string.
+    let joined: String = parts.join("+");
+    joined
+}
+
+// ---------------------------------------------------------------------------
+// KeyCombo
+// ---------------------------------------------------------------------------
+
+/// A keybinding: either a single key or a two-key sequence.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum KeyCombo {
+    /// Single key press (e.g., `q`, `Esc`, `Ctrl+P`).
+    Single { code: KeyCode, modifiers: Modifiers },
+    /// Two-key sequence (e.g., `g` then `i` for go-to-issues).
+    Sequence {
+        first_code: KeyCode,
+        first_modifiers: Modifiers,
+        second_code: KeyCode,
+        second_modifiers: Modifiers,
+    },
+}
+
+impl KeyCombo {
+    /// Convenience: single key with no modifiers.
+    #[must_use]
+    pub const fn key(code: KeyCode) -> Self {
+        Self::Single {
+            code,
+            modifiers: Modifiers::NONE,
+        }
+    }
+
+    /// Convenience: single key with Ctrl modifier.
+    #[must_use]
+    pub const fn ctrl(code: KeyCode) -> Self {
+        Self::Single {
+            code,
+            modifiers: Modifiers::CTRL,
+        }
+    }
+
+    /// Convenience: g-prefix sequence (g + char).
+    #[must_use]
+    pub const fn g_then(c: char) -> Self {
+        Self::Sequence {
+            first_code: KeyCode::Char('g'),
+            first_modifiers: Modifiers::NONE,
+            second_code: KeyCode::Char(c),
+            second_modifiers: Modifiers::NONE,
+        }
+    }
+
+    /// Human-readable display string for this key combo.
+    #[must_use]
+    pub fn display(&self) -> String {
+        match self {
+            Self::Single { code, modifiers } => format_key(*code, *modifiers),
+            Self::Sequence {
+                first_code,
+                first_modifiers,
+                second_code,
+                second_modifiers,
+            } => {
+                let first = format_key(*first_code, *first_modifiers);
+                let second = format_key(*second_code, *second_modifiers);
+                format!("{first} {second}")
+            }
+        }
+    }
+
+    /// Whether this combo starts with the given key.
+    #[must_use]
+    pub fn starts_with(&self, code: &KeyCode, modifiers: &Modifiers) -> bool {
+        match self {
+            Self::Single {
+                code: c,
+                modifiers: m,
+            } => c == code && m == modifiers,
+            Self::Sequence {
+                first_code,
+                first_modifiers,
+                ..
+            } => first_code == code && first_modifiers == modifiers,
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// ScreenFilter
+// ---------------------------------------------------------------------------
+
+/// Specifies which screens a command is available on.
+#[derive(Debug, Clone)]
+pub enum ScreenFilter {
+    /// Available on all screens.
+    Global,
+    /// Available only on specific screens.
+    Only(Vec<Screen>),
+}
+
+impl ScreenFilter {
+    /// Whether the command is available on the given screen.
+    #[must_use]
+    pub fn matches(&self, screen: &Screen) -> bool {
+        match self {
+            Self::Global => true,
+            Self::Only(screens) => screens.contains(screen),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// CommandDef
+// ---------------------------------------------------------------------------
+
+/// Unique command identifier.
+pub type CommandId = &'static str;
+
+/// A registered command with its keybinding, help text, and scope.
+#[derive(Debug, Clone)]
+pub struct CommandDef {
+    /// Unique identifier (e.g., "quit", "go_issues").
+    pub id: CommandId,
+    /// Human-readable label for palette and help overlay.
+    pub label: &'static str,
+    /// Keybinding (if any).
+    pub keybinding: Option<KeyCombo>,
+    /// Equivalent `lore` CLI command (for "Show CLI equivalent" feature).
+    pub cli_equivalent: Option<&'static str>,
+    /// Description for help overlay.
+    pub help_text: &'static str,
+    /// Short hint for status bar (e.g., "q:quit").
+    pub status_hint: &'static str,
+    /// Which screens this command is available on.
+    pub available_in: ScreenFilter,
+    /// Whether this command works in Text input mode.
+    pub available_in_text_mode: bool,
+}

crates/lore-tui/src/commands/mod.rs

@@ -0,0 +1,227 @@
+#![allow(dead_code)] // Phase 1: consumed by LoreApp in bd-6pmy
+
+//! Command registry — single source of truth for all TUI actions.
+//!
+//! Every keybinding, palette entry, help text, CLI equivalent, and
+//! status hint is generated from [`CommandRegistry`]. No hardcoded
+//! duplicate maps exist in view/state modules.
+//!
+//! Supports single-key and two-key sequences (g-prefix vim bindings).
+
+mod defs;
+mod registry;
+
+// Re-export public API — preserves `crate::commands::{CommandRegistry, build_registry, ...}`.
+pub use defs::{CommandDef, CommandId, KeyCombo, ScreenFilter};
+pub use registry::{CommandRegistry, build_registry};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::Utc;
+    use ftui::{KeyCode, Modifiers};
+
+    use crate::message::{InputMode, Screen};
+
+    #[test]
+    fn test_registry_builds_successfully() {
+        let reg = build_registry();
+        assert!(!reg.is_empty());
+        assert!(reg.len() >= 15);
+    }
+
+    #[test]
+    fn test_registry_lookup_quit() {
+        let reg = build_registry();
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('q'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+            &InputMode::Normal,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "quit");
+    }
+
+    #[test]
+    fn test_registry_lookup_quit_blocked_in_text_mode() {
+        let reg = build_registry();
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('q'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+            &InputMode::Text,
+        );
+        assert!(cmd.is_none());
+    }
+
+    #[test]
+    fn test_registry_esc_works_in_text_mode() {
+        let reg = build_registry();
+        let cmd = reg.lookup_key(
+            &KeyCode::Escape,
+            &Modifiers::NONE,
+            &Screen::IssueList,
+            &InputMode::Text,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "go_back");
+    }
+
+    #[test]
+    fn test_registry_ctrl_p_works_in_text_mode() {
+        let reg = build_registry();
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('p'),
+            &Modifiers::CTRL,
+            &Screen::Search,
+            &InputMode::Text,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "command_palette");
+    }
+
+    #[test]
+    fn test_g_is_sequence_starter() {
+        let reg = build_registry();
+        assert!(reg.is_sequence_starter(&KeyCode::Char('g'), &Modifiers::NONE));
+        assert!(!reg.is_sequence_starter(&KeyCode::Char('x'), &Modifiers::NONE));
+    }
+
+    #[test]
+    fn test_complete_sequence_gi() {
+        let reg = build_registry();
+        let cmd = reg.complete_sequence(
+            &KeyCode::Char('g'),
+            &Modifiers::NONE,
+            &KeyCode::Char('i'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "go_issues");
+    }
+
+    #[test]
+    fn test_complete_sequence_invalid_second_key() {
+        let reg = build_registry();
+        let cmd = reg.complete_sequence(
+            &KeyCode::Char('g'),
+            &Modifiers::NONE,
+            &KeyCode::Char('x'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+        );
+        assert!(cmd.is_none());
+    }
+
+    #[test]
+    fn test_screen_specific_command() {
+        let reg = build_registry();
+        // 'j' (move_down) should work on IssueList
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('j'),
+            &Modifiers::NONE,
+            &Screen::IssueList,
+            &InputMode::Normal,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "move_down");
+
+        // 'j' should NOT match on Dashboard (move_down is list-only).
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('j'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+            &InputMode::Normal,
+        );
+        assert!(cmd.is_none());
+    }
+
+    #[test]
+    fn test_palette_entries_sorted_by_label() {
+        let reg = build_registry();
+        let entries = reg.palette_entries(&Screen::Dashboard);
+        let labels: Vec<&str> = entries.iter().map(|c| c.label).collect();
+        let mut sorted = labels.clone();
+        sorted.sort();
+        assert_eq!(labels, sorted);
+    }
+
+    #[test]
+    fn test_help_entries_only_include_keybindings() {
+        let reg = build_registry();
+        let entries = reg.help_entries(&Screen::Dashboard);
+        for entry in &entries {
+            assert!(
+                entry.keybinding.is_some(),
+                "help entry without keybinding: {}",
+                entry.id
+            );
+        }
+    }
+
+    #[test]
+    fn test_status_hints_non_empty() {
+        let reg = build_registry();
+        let hints = reg.status_hints(&Screen::Dashboard);
+        assert!(!hints.is_empty());
+        // All returned hints should be non-empty strings.
+        for hint in &hints {
+            assert!(!hint.is_empty());
+        }
+    }
+
+    #[test]
+    fn test_cli_equivalents_populated() {
+        let reg = build_registry();
+        let with_cli: Vec<&CommandDef> = reg
+            .commands
+            .iter()
+            .filter(|c| c.cli_equivalent.is_some())
+            .collect();
+        assert!(
+            with_cli.len() >= 5,
+            "expected at least 5 commands with cli_equivalent, got {}",
+            with_cli.len()
+        );
+    }
+
+    #[test]
+    fn test_go_prefix_timeout_detection() {
+        let reg = build_registry();
+        // Simulate GoPrefix mode entering: 'g' detected as sequence starter.
+        assert!(reg.is_sequence_starter(&KeyCode::Char('g'), &Modifiers::NONE));
+
+        // Simulate InputMode::GoPrefix with timeout check.
+        let started = Utc::now();
+        let mode = InputMode::GoPrefix {
+            started_at: started,
+        };
+        // In GoPrefix mode, normal lookup should still work for non-sequence keys.
+        let cmd = reg.lookup_key(
+            &KeyCode::Char('q'),
+            &Modifiers::NONE,
+            &Screen::Dashboard,
+            &mode,
+        );
+        assert!(cmd.is_some());
+        assert_eq!(cmd.unwrap().id, "quit");
+    }
+
+    #[test]
+    fn test_all_commands_have_nonempty_help() {
+        let reg = build_registry();
+        for cmd in &reg.commands {
+            assert!(
+                !cmd.help_text.is_empty(),
+                "command {} has empty help_text",
+                cmd.id
+            );
+        }
+    }
+}

crates/lore-tui/src/commands/registry.rs

@@ -0,0 +1,418 @@
+//! Command registry — lookup, indexing, and the canonical command list.
+
+use std::collections::HashMap;
+
+use ftui::{KeyCode, Modifiers};
+
+use crate::message::{InputMode, Screen};
+
+use super::defs::{CommandDef, KeyCombo, ScreenFilter};
+
+// ---------------------------------------------------------------------------
+// CommandRegistry
+// ---------------------------------------------------------------------------
+
+/// Single source of truth for all TUI commands.
+///
+/// Built once at startup via [`build_registry`]. Provides O(1) lookup
+/// by keybinding and per-screen filtering.
+pub struct CommandRegistry {
+    pub(crate) commands: Vec<CommandDef>,
+    /// Single-key -> command IDs that start with this key.
+    by_single_key: HashMap<(KeyCode, Modifiers), Vec<usize>>,
+    /// Full sequence -> command index (for two-key combos).
+    by_sequence: HashMap<KeyCombo, usize>,
+}
+
+impl CommandRegistry {
+    /// Look up a command by a single key press on a given screen and input mode.
+    ///
+    /// Returns `None` if no matching command is found. For sequence starters
+    /// (like 'g'), returns `None` — use [`is_sequence_starter`] to detect
+    /// that case.
+    #[must_use]
+    pub fn lookup_key(
+        &self,
+        code: &KeyCode,
+        modifiers: &Modifiers,
+        screen: &Screen,
+        mode: &InputMode,
+    ) -> Option<&CommandDef> {
+        let is_text = matches!(mode, InputMode::Text);
+        let key = (*code, *modifiers);
+
+        let indices = self.by_single_key.get(&key)?;
+        for &idx in indices {
+            let cmd = &self.commands[idx];
+            if !cmd.available_in.matches(screen) {
+                continue;
+            }
+            if is_text && !cmd.available_in_text_mode {
+                continue;
+            }
+            // Only match Single combos here, not sequence starters.
+            if let Some(KeyCombo::Single { .. }) = &cmd.keybinding {
+                return Some(cmd);
+            }
+        }
+        None
+    }
+
+    /// Complete a two-key sequence.
+    ///
+    /// Called after the first key of a sequence is detected (e.g., after 'g').
+    #[must_use]
+    pub fn complete_sequence(
+        &self,
+        first_code: &KeyCode,
+        first_modifiers: &Modifiers,
+        second_code: &KeyCode,
+        second_modifiers: &Modifiers,
+        screen: &Screen,
+    ) -> Option<&CommandDef> {
+        let combo = KeyCombo::Sequence {
+            first_code: *first_code,
+            first_modifiers: *first_modifiers,
+            second_code: *second_code,
+            second_modifiers: *second_modifiers,
+        };
+        let &idx = self.by_sequence.get(&combo)?;
+        let cmd = &self.commands[idx];
+        if cmd.available_in.matches(screen) {
+            Some(cmd)
+        } else {
+            None
+        }
+    }
+
+    /// Whether a key starts a multi-key sequence (e.g., 'g').
+    #[must_use]
+    pub fn is_sequence_starter(&self, code: &KeyCode, modifiers: &Modifiers) -> bool {
+        self.by_sequence
+            .keys()
+            .any(|combo| combo.starts_with(code, modifiers))
+    }
+
+    /// Commands available for the command palette on a given screen.
+    ///
+    /// Returned sorted by label.
+    #[must_use]
+    pub fn palette_entries(&self, screen: &Screen) -> Vec<&CommandDef> {
+        let mut entries: Vec<&CommandDef> = self
+            .commands
+            .iter()
+            .filter(|c| c.available_in.matches(screen))
+            .collect();
+        entries.sort_by_key(|c| c.label);
+        entries
+    }
+
+    /// Commands for the help overlay on a given screen.
+    #[must_use]
+    pub fn help_entries(&self, screen: &Screen) -> Vec<&CommandDef> {
+        self.commands
+            .iter()
+            .filter(|c| c.available_in.matches(screen))
+            .filter(|c| c.keybinding.is_some())
+            .collect()
+    }
+
+    /// Status bar hints for the current screen.
+    #[must_use]
+    pub fn status_hints(&self, screen: &Screen) -> Vec<&str> {
+        self.commands
+            .iter()
+            .filter(|c| c.available_in.matches(screen))
+            .filter(|c| !c.status_hint.is_empty())
+            .map(|c| c.status_hint)
+            .collect()
+    }
+
+    /// Total number of registered commands.
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.commands.len()
+    }
+
+    /// Whether the registry has no commands.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.commands.is_empty()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// build_registry
+// ---------------------------------------------------------------------------
+
+/// Build the command registry with all TUI commands.
+///
+/// This is the single source of truth — every keybinding, help text,
+/// and palette entry originates here.
+#[must_use]
+pub fn build_registry() -> CommandRegistry {
+    let commands = vec![
+        // --- Global commands ---
+        CommandDef {
+            id: "quit",
+            label: "Quit",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('q'))),
+            cli_equivalent: None,
+            help_text: "Exit the TUI",
+            status_hint: "q:quit",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_back",
+            label: "Go Back",
+            keybinding: Some(KeyCombo::key(KeyCode::Escape)),
+            cli_equivalent: None,
+            help_text: "Go back to previous screen",
+            status_hint: "esc:back",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: true,
+        },
+        CommandDef {
+            id: "show_help",
+            label: "Help",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('?'))),
+            cli_equivalent: None,
+            help_text: "Show keybinding help overlay",
+            status_hint: "?:help",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "command_palette",
+            label: "Command Palette",
+            keybinding: Some(KeyCombo::ctrl(KeyCode::Char('p'))),
+            cli_equivalent: None,
+            help_text: "Open command palette",
+            status_hint: "C-p:palette",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: true,
+        },
+        CommandDef {
+            id: "open_in_browser",
+            label: "Open in Browser",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('o'))),
+            cli_equivalent: None,
+            help_text: "Open current entity in browser",
+            status_hint: "o:browser",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "show_cli",
+            label: "Show CLI Equivalent",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('!'))),
+            cli_equivalent: None,
+            help_text: "Show equivalent lore CLI command",
+            status_hint: "",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        // --- Navigation: g-prefix sequences ---
+        CommandDef {
+            id: "go_home",
+            label: "Go to Dashboard",
+            keybinding: Some(KeyCombo::g_then('h')),
+            cli_equivalent: None,
+            help_text: "Jump to dashboard",
+            status_hint: "gh:home",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_issues",
+            label: "Go to Issues",
+            keybinding: Some(KeyCombo::g_then('i')),
+            cli_equivalent: Some("lore issues"),
+            help_text: "Jump to issue list",
+            status_hint: "gi:issues",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_mrs",
+            label: "Go to Merge Requests",
+            keybinding: Some(KeyCombo::g_then('m')),
+            cli_equivalent: Some("lore mrs"),
+            help_text: "Jump to MR list",
+            status_hint: "gm:mrs",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_search",
+            label: "Go to Search",
+            keybinding: Some(KeyCombo::g_then('/')),
+            cli_equivalent: Some("lore search"),
+            help_text: "Jump to search",
+            status_hint: "g/:search",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_timeline",
+            label: "Go to Timeline",
+            keybinding: Some(KeyCombo::g_then('t')),
+            cli_equivalent: Some("lore timeline"),
+            help_text: "Jump to timeline",
+            status_hint: "gt:timeline",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_who",
+            label: "Go to Who",
+            keybinding: Some(KeyCombo::g_then('w')),
+            cli_equivalent: Some("lore who"),
+            help_text: "Jump to people intelligence",
+            status_hint: "gw:who",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "go_sync",
+            label: "Go to Sync",
+            keybinding: Some(KeyCombo::g_then('s')),
+            cli_equivalent: Some("lore sync"),
+            help_text: "Jump to sync status",
+            status_hint: "gs:sync",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        // --- Vim-style jump list ---
+        CommandDef {
+            id: "jump_back",
+            label: "Jump Back",
+            keybinding: Some(KeyCombo::ctrl(KeyCode::Char('o'))),
+            cli_equivalent: None,
+            help_text: "Jump backward through visited detail views",
+            status_hint: "C-o:jump back",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "jump_forward",
+            label: "Jump Forward",
+            keybinding: Some(KeyCombo::ctrl(KeyCode::Char('i'))),
+            cli_equivalent: None,
+            help_text: "Jump forward through visited detail views",
+            status_hint: "",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+        // --- List navigation ---
+        CommandDef {
+            id: "move_down",
+            label: "Move Down",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('j'))),
+            cli_equivalent: None,
+            help_text: "Move cursor down",
+            status_hint: "j:down",
+            available_in: ScreenFilter::Only(vec![
+                Screen::IssueList,
+                Screen::MrList,
+                Screen::Search,
+                Screen::Timeline,
+            ]),
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "move_up",
+            label: "Move Up",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('k'))),
+            cli_equivalent: None,
+            help_text: "Move cursor up",
+            status_hint: "k:up",
+            available_in: ScreenFilter::Only(vec![
+                Screen::IssueList,
+                Screen::MrList,
+                Screen::Search,
+                Screen::Timeline,
+            ]),
+            available_in_text_mode: false,
+        },
+        CommandDef {
+            id: "select_item",
+            label: "Select",
+            keybinding: Some(KeyCombo::key(KeyCode::Enter)),
+            cli_equivalent: None,
+            help_text: "Open selected item",
+            status_hint: "enter:open",
+            available_in: ScreenFilter::Only(vec![
+                Screen::IssueList,
+                Screen::MrList,
+                Screen::Search,
+            ]),
+            available_in_text_mode: false,
+        },
+        // --- Filter ---
+        CommandDef {
+            id: "focus_filter",
+            label: "Filter",
+            keybinding: Some(KeyCombo::key(KeyCode::Char('/'))),
+            cli_equivalent: None,
+            help_text: "Focus the filter input",
+            status_hint: "/:filter",
+            available_in: ScreenFilter::Only(vec![Screen::IssueList, Screen::MrList]),
+            available_in_text_mode: false,
+        },
+        // --- Scroll ---
+        CommandDef {
+            id: "scroll_to_top",
+            label: "Scroll to Top",
+            keybinding: Some(KeyCombo::g_then('g')),
+            cli_equivalent: None,
+            help_text: "Scroll to the top of the current view",
+            status_hint: "",
+            available_in: ScreenFilter::Global,
+            available_in_text_mode: false,
+        },
+    ];
+
+    build_from_defs(commands)
+}
+
+/// Build index maps from a list of command definitions.
+fn build_from_defs(commands: Vec<CommandDef>) -> CommandRegistry {
+    let mut by_single_key: HashMap<(KeyCode, Modifiers), Vec<usize>> = HashMap::new();
+    let mut by_sequence: HashMap<KeyCombo, usize> = HashMap::new();
+
+    for (idx, cmd) in commands.iter().enumerate() {
+        if let Some(combo) = &cmd.keybinding {
+            match combo {
+                KeyCombo::Single { code, modifiers } => {
+                    by_single_key
+                        .entry((*code, *modifiers))
+                        .or_default()
+                        .push(idx);
+                }
+                KeyCombo::Sequence { .. } => {
+                    by_sequence.insert(combo.clone(), idx);
+                    // Also index the first key so is_sequence_starter works via by_single_key.
+                    if let KeyCombo::Sequence {
+                        first_code,
+                        first_modifiers,
+                        ..
+                    } = combo
+                    {
+                        by_single_key
+                            .entry((*first_code, *first_modifiers))
+                            .or_default()
+                            .push(idx);
+                    }
+                }
+            }
+        }
+    }
+
+    CommandRegistry {
+        commands,
+        by_single_key,
+        by_sequence,
+    }
+}

crates/lore-tui/src/crash_context.rs

@@ -0,0 +1,450 @@
+#![allow(dead_code)] // Phase 1: consumed by LoreApp in bd-6pmy
+
+//! Ring buffer of recent app events for post-mortem crash diagnostics.
+//!
+//! The TUI pushes every key press, message dispatch, and state transition
+//! into [`CrashContext`]. On panic the installed hook dumps the last 2000
+//! events to `~/.local/share/lore/crash-<timestamp>.json` as NDJSON.
+//!
+//! Retention: only the 5 most recent crash files are kept.
+
+use std::collections::VecDeque;
+use std::io::{self, BufWriter, Write};
+use std::path::{Path, PathBuf};
+
+use serde::Serialize;
+
+/// Maximum number of events retained in the ring buffer.
+const MAX_EVENTS: usize = 2000;
+
+/// Maximum number of crash files to keep on disk.
+const MAX_CRASH_FILES: usize = 5;
+
+// ---------------------------------------------------------------------------
+// CrashEvent
+// ---------------------------------------------------------------------------
+
+/// A single event recorded for crash diagnostics.
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "type")]
+pub enum CrashEvent {
+    /// A key was pressed.
+    KeyPress {
+        key: String,
+        mode: String,
+        screen: String,
+    },
+    /// A message was dispatched through update().
+    MsgDispatched { msg_name: String, screen: String },
+    /// Navigation changed screens.
+    StateTransition { from: String, to: String },
+    /// An error occurred.
+    Error { message: String },
+    /// Catch-all for ad-hoc diagnostic breadcrumbs.
+    Custom { tag: String, detail: String },
+}
+
+// ---------------------------------------------------------------------------
+// CrashContext
+// ---------------------------------------------------------------------------
+
+/// Ring buffer of recent app events for panic diagnostics.
+///
+/// Holds at most [`MAX_EVENTS`] entries. When full, the oldest event
+/// is evicted on each push.
+pub struct CrashContext {
+    events: VecDeque<CrashEvent>,
+}
+
+impl CrashContext {
+    /// Create an empty crash context with pre-allocated capacity.
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            events: VecDeque::with_capacity(MAX_EVENTS),
+        }
+    }
+
+    /// Record an event. Evicts the oldest when the buffer is full.
+    pub fn push(&mut self, event: CrashEvent) {
+        if self.events.len() == MAX_EVENTS {
+            self.events.pop_front();
+        }
+        self.events.push_back(event);
+    }
+
+    /// Number of events currently stored.
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.events.len()
+    }
+
+    /// Whether the buffer is empty.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.events.is_empty()
+    }
+
+    /// Iterate over stored events (oldest first).
+    pub fn iter(&self) -> impl Iterator<Item = &CrashEvent> {
+        self.events.iter()
+    }
+
+    /// Dump all events to a file as newline-delimited JSON.
+    ///
+    /// Creates parent directories if they don't exist.
+    /// Returns `Ok(())` on success, `Err` on I/O failure.
+    pub fn dump_to_file(&self, path: &Path) -> io::Result<()> {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        let file = std::fs::File::create(path)?;
+        let mut writer = BufWriter::new(file);
+        for event in &self.events {
+            match serde_json::to_string(event) {
+                Ok(json) => {
+                    writeln!(writer, "{json}")?;
+                }
+                Err(_) => {
+                    // Fallback to debug format if serialization fails.
+                    writeln!(
+                        writer,
+                        "{{\"type\":\"SerializationError\",\"debug\":\"{event:?}\"}}"
+                    )?;
+                }
+            }
+        }
+        writer.flush()?;
+        Ok(())
+    }
+
+    /// Default crash directory: `~/.local/share/lore/`.
+    #[must_use]
+    pub fn crash_dir() -> Option<PathBuf> {
+        dirs::data_local_dir().map(|d| d.join("lore"))
+    }
+
+    /// Generate a timestamped crash file path.
+    #[must_use]
+    pub fn crash_file_path() -> Option<PathBuf> {
+        let dir = Self::crash_dir()?;
+        let timestamp = chrono::Utc::now().format("%Y%m%d-%H%M%S%.3f");
+        Some(dir.join(format!("crash-{timestamp}.json")))
+    }
+
+    /// Remove old crash files, keeping only the most recent [`MAX_CRASH_FILES`].
+    ///
+    /// Best-effort: silently ignores I/O errors on individual deletions.
+    pub fn prune_crash_files() {
+        let Some(dir) = Self::crash_dir() else {
+            return;
+        };
+        let Ok(entries) = std::fs::read_dir(&dir) else {
+            return;
+        };
+
+        let mut crash_files: Vec<PathBuf> = entries
+            .filter_map(Result::ok)
+            .map(|e| e.path())
+            .filter(|p| {
+                p.file_name()
+                    .and_then(|n| n.to_str())
+                    .is_some_and(|n| n.starts_with("crash-") && n.ends_with(".json"))
+            })
+            .collect();
+
+        // Sort ascending by filename (timestamps sort lexicographically).
+        crash_files.sort();
+
+        if crash_files.len() > MAX_CRASH_FILES {
+            let to_remove = crash_files.len() - MAX_CRASH_FILES;
+            for path in &crash_files[..to_remove] {
+                let _ = std::fs::remove_file(path);
+            }
+        }
+    }
+
+    /// Install a panic hook that dumps the crash context to disk.
+    ///
+    /// Captures the current events via a snapshot. The hook chains with
+    /// the default panic handler so backtraces are still printed.
+    ///
+    /// FIXME: This snapshots events at install time, which is typically
+    /// during init() when the buffer is empty. The crash dump will only
+    /// contain the panic itself, not the preceding key presses and state
+    /// transitions. Fix requires CrashContext to use interior mutability
+    /// (Arc<Mutex<VecDeque<CrashEvent>>>) so the panic hook reads live
+    /// state instead of a stale snapshot.
+    pub fn install_panic_hook(ctx: &Self) {
+        let snapshot: Vec<CrashEvent> = ctx.events.iter().cloned().collect();
+        let prev_hook = std::panic::take_hook();
+
+        std::panic::set_hook(Box::new(move |info| {
+            // Best-effort dump — never panic inside the panic hook.
+            if let Some(path) = Self::crash_file_path() {
+                let mut dump = CrashContext::new();
+                for event in &snapshot {
+                    dump.push(event.clone());
+                }
+                // Add the panic info itself as the final event.
+                dump.push(CrashEvent::Error {
+                    message: format!("{info}"),
+                });
+                let _ = dump.dump_to_file(&path);
+            }
+
+            // Chain to the previous hook (prints backtrace, etc.).
+            prev_hook(info);
+        }));
+    }
+}
+
+impl Default for CrashContext {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::BufRead;
+
+    /// Helper: create a numbered Custom event.
+    fn event(n: usize) -> CrashEvent {
+        CrashEvent::Custom {
+            tag: "test".into(),
+            detail: format!("event-{n}"),
+        }
+    }
+
+    #[test]
+    fn test_ring_buffer_evicts_oldest() {
+        let mut ctx = CrashContext::new();
+        for i in 0..2500 {
+            ctx.push(event(i));
+        }
+        assert_eq!(ctx.len(), MAX_EVENTS);
+
+        // First retained event should be #500 (0..499 evicted).
+        let first = ctx.iter().next().unwrap();
+        match first {
+            CrashEvent::Custom { detail, .. } => assert_eq!(detail, "event-500"),
+            other => panic!("unexpected variant: {other:?}"),
+        }
+
+        // Last retained event should be #2499.
+        let last = ctx.iter().last().unwrap();
+        match last {
+            CrashEvent::Custom { detail, .. } => assert_eq!(detail, "event-2499"),
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_new_is_empty() {
+        let ctx = CrashContext::new();
+        assert!(ctx.is_empty());
+        assert_eq!(ctx.len(), 0);
+    }
+
+    #[test]
+    fn test_push_increments_len() {
+        let mut ctx = CrashContext::new();
+        ctx.push(event(1));
+        ctx.push(event(2));
+        assert_eq!(ctx.len(), 2);
+    }
+
+    #[test]
+    fn test_push_does_not_evict_below_capacity() {
+        let mut ctx = CrashContext::new();
+        for i in 0..MAX_EVENTS {
+            ctx.push(event(i));
+        }
+        assert_eq!(ctx.len(), MAX_EVENTS);
+
+        // First should still be event-0.
+        match ctx.iter().next().unwrap() {
+            CrashEvent::Custom { detail, .. } => assert_eq!(detail, "event-0"),
+            other => panic!("unexpected: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_dump_to_file_writes_ndjson() {
+        let mut ctx = CrashContext::new();
+        ctx.push(CrashEvent::KeyPress {
+            key: "j".into(),
+            mode: "Normal".into(),
+            screen: "Dashboard".into(),
+        });
+        ctx.push(CrashEvent::MsgDispatched {
+            msg_name: "NavigateTo".into(),
+            screen: "Dashboard".into(),
+        });
+        ctx.push(CrashEvent::StateTransition {
+            from: "Dashboard".into(),
+            to: "IssueList".into(),
+        });
+        ctx.push(CrashEvent::Error {
+            message: "db busy".into(),
+        });
+        ctx.push(CrashEvent::Custom {
+            tag: "test".into(),
+            detail: "hello".into(),
+        });
+
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("test-crash.json");
+        ctx.dump_to_file(&path).unwrap();
+
+        // Verify: each line is valid JSON, total lines == 5.
+        let file = std::fs::File::open(&path).unwrap();
+        let reader = io::BufReader::new(file);
+        let lines: Vec<String> = reader.lines().map(Result::unwrap).collect();
+        assert_eq!(lines.len(), 5);
+
+        // Each line must parse as JSON.
+        for line in &lines {
+            let val: serde_json::Value = serde_json::from_str(line).unwrap();
+            assert!(val.get("type").is_some(), "missing 'type' field: {line}");
+        }
+
+        // Spot check first line: KeyPress with correct fields.
+        let first: serde_json::Value = serde_json::from_str(&lines[0]).unwrap();
+        assert_eq!(first["type"], "KeyPress");
+        assert_eq!(first["key"], "j");
+        assert_eq!(first["mode"], "Normal");
+        assert_eq!(first["screen"], "Dashboard");
+    }
+
+    #[test]
+    fn test_dump_creates_parent_directories() {
+        let dir = tempfile::tempdir().unwrap();
+        let nested = dir.path().join("a").join("b").join("c").join("crash.json");
+
+        let mut ctx = CrashContext::new();
+        ctx.push(event(1));
+        ctx.dump_to_file(&nested).unwrap();
+
+        assert!(nested.exists());
+    }
+
+    #[test]
+    fn test_dump_empty_context_creates_empty_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("empty.json");
+
+        let ctx = CrashContext::new();
+        ctx.dump_to_file(&path).unwrap();
+
+        let content = std::fs::read_to_string(&path).unwrap();
+        assert!(content.is_empty());
+    }
+
+    #[test]
+    fn test_prune_keeps_newest_files() {
+        let dir = tempfile::tempdir().unwrap();
+        let crash_dir = dir.path();
+
+        // Create 8 crash files with ordered timestamps.
+        let filenames: Vec<String> = (0..8)
+            .map(|i| format!("crash-2026010{i}-120000.000.json"))
+            .collect();
+        for name in &filenames {
+            std::fs::write(crash_dir.join(name), "{}").unwrap();
+        }
+
+        // Prune, pointing at our temp dir.
+        prune_crash_files_in(crash_dir);
+
+        let remaining: Vec<String> = std::fs::read_dir(crash_dir)
+            .unwrap()
+            .filter_map(Result::ok)
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .filter(|n| n.starts_with("crash-") && n.ends_with(".json"))
+            .collect();
+
+        assert_eq!(remaining.len(), MAX_CRASH_FILES);
+        // Oldest 3 should be gone.
+        for name in filenames.iter().take(3) {
+            assert!(!remaining.contains(name));
+        }
+        // Newest 5 should remain.
+        for name in filenames.iter().skip(3) {
+            assert!(remaining.contains(name));
+        }
+    }
+
+    #[test]
+    fn test_all_event_variants_serialize() {
+        let events = vec![
+            CrashEvent::KeyPress {
+                key: "q".into(),
+                mode: "Normal".into(),
+                screen: "Dashboard".into(),
+            },
+            CrashEvent::MsgDispatched {
+                msg_name: "Quit".into(),
+                screen: "Dashboard".into(),
+            },
+            CrashEvent::StateTransition {
+                from: "Dashboard".into(),
+                to: "IssueList".into(),
+            },
+            CrashEvent::Error {
+                message: "oops".into(),
+            },
+            CrashEvent::Custom {
+                tag: "debug".into(),
+                detail: "trace".into(),
+            },
+        ];
+
+        for event in events {
+            let json = serde_json::to_string(&event).unwrap();
+            let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+            assert!(parsed.get("type").is_some());
+        }
+    }
+
+    #[test]
+    fn test_default_is_new() {
+        let ctx = CrashContext::default();
+        assert!(ctx.is_empty());
+    }
+
+    // -----------------------------------------------------------------------
+    // Test helper: prune files in a specific directory (not the real path).
+    // -----------------------------------------------------------------------
+
+    fn prune_crash_files_in(dir: &Path) {
+        let Ok(entries) = std::fs::read_dir(dir) else {
+            return;
+        };
+
+        let mut crash_files: Vec<PathBuf> = entries
+            .filter_map(Result::ok)
+            .map(|e| e.path())
+            .filter(|p| {
+                p.file_name()
+                    .and_then(|n| n.to_str())
+                    .is_some_and(|n| n.starts_with("crash-") && n.ends_with(".json"))
+            })
+            .collect();
+
+        crash_files.sort();
+
+        if crash_files.len() > MAX_CRASH_FILES {
+            let to_remove = crash_files.len() - MAX_CRASH_FILES;
+            for path in &crash_files[..to_remove] {
+                let _ = std::fs::remove_file(path);
+            }
+        }
+    }
+}

crates/lore-tui/src/db.rs

@@ -0,0 +1,270 @@
+#![allow(dead_code)] // Phase 0: types defined now, consumed in Phase 1+
+
+//! Database access layer for the TUI.
+//!
+//! Provides a read pool (3 connections, round-robin) plus a dedicated writer
+//! connection. All connections use WAL mode and busy_timeout for concurrency.
+//!
+//! The TUI operates read-heavy: parallel queries for dashboard, list views,
+//! and prefetch. Writes are rare (TUI-local state: scroll positions, bookmarks).
+
+use std::path::Path;
+use std::sync::Mutex;
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use anyhow::{Context, Result};
+use rusqlite::Connection;
+
+/// Number of reader connections in the pool.
+const READER_COUNT: usize = 3;
+
+// ---------------------------------------------------------------------------
+// DbManager
+// ---------------------------------------------------------------------------
+
+/// Manages a pool of read-only connections plus a dedicated writer.
+///
+/// Designed for `Arc<DbManager>` sharing across FrankenTUI's `Cmd::task`
+/// background threads. Each reader is individually `Mutex`-protected so
+/// concurrent tasks can query different readers without blocking.
+pub struct DbManager {
+    readers: Vec<Mutex<Connection>>,
+    writer: Mutex<Connection>,
+    next_reader: AtomicUsize,
+}
+
+impl DbManager {
+    /// Open a database at `path` with 3 reader + 1 writer connections.
+    ///
+    /// All connections get WAL mode, 5000ms busy_timeout, and foreign keys.
+    /// Reader connections additionally set `query_only = ON` as a safety guard.
+    pub fn open(path: &Path) -> Result<Self> {
+        let mut readers = Vec::with_capacity(READER_COUNT);
+        for i in 0..READER_COUNT {
+            let conn =
+                open_connection(path).with_context(|| format!("opening reader connection {i}"))?;
+            conn.pragma_update(None, "query_only", "ON")
+                .context("setting query_only on reader")?;
+            readers.push(Mutex::new(conn));
+        }
+
+        let writer = open_connection(path).context("opening writer connection")?;
+
+        Ok(Self {
+            readers,
+            writer: Mutex::new(writer),
+            next_reader: AtomicUsize::new(0),
+        })
+    }
+
+    /// Execute a read-only query against the pool.
+    ///
+    /// Selects the next reader via round-robin. The connection is borrowed
+    /// for the duration of `f` and cannot leak outside.
+    pub fn with_reader<F, T>(&self, f: F) -> Result<T>
+    where
+        F: FnOnce(&Connection) -> Result<T>,
+    {
+        let idx = self.next_reader.fetch_add(1, Ordering::Relaxed) % READER_COUNT;
+        let conn = self.readers[idx].lock().expect("reader mutex poisoned");
+        f(&conn)
+    }
+
+    /// Execute a write operation against the dedicated writer.
+    ///
+    /// Serialized via a single `Mutex`. The TUI writes infrequently
+    /// (bookmarks, scroll state) so contention is negligible.
+    pub fn with_writer<F, T>(&self, f: F) -> Result<T>
+    where
+        F: FnOnce(&Connection) -> Result<T>,
+    {
+        let conn = self.writer.lock().expect("writer mutex poisoned");
+        f(&conn)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Connection setup
+// ---------------------------------------------------------------------------
+
+/// Open a single SQLite connection with TUI-appropriate pragmas.
+///
+/// Mirrors lore's `create_connection` pragmas (WAL, busy_timeout, etc.)
+/// but skips the sqlite-vec extension registration — the TUI reads standard
+/// tables only, never vec0 virtual tables.
+fn open_connection(path: &Path) -> Result<Connection> {
+    let conn = Connection::open(path).context("opening SQLite database")?;
+
+    conn.pragma_update(None, "journal_mode", "WAL")?;
+    conn.pragma_update(None, "synchronous", "NORMAL")?;
+    conn.pragma_update(None, "foreign_keys", "ON")?;
+    conn.pragma_update(None, "busy_timeout", 5000)?;
+    conn.pragma_update(None, "temp_store", "MEMORY")?;
+
+    Ok(conn)
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+
+    /// Create a temporary database file for testing.
+    ///
+    /// Uses an atomic counter + thread ID to guarantee unique paths even
+    /// when tests run in parallel.
+    fn test_db_path() -> std::path::PathBuf {
+        use std::sync::atomic::AtomicU64;
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let n = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let dir = std::env::temp_dir().join("lore-tui-tests");
+        std::fs::create_dir_all(&dir).expect("create test dir");
+        dir.join(format!(
+            "test-{}-{:?}-{n}.db",
+            std::process::id(),
+            std::thread::current().id(),
+        ))
+    }
+
+    fn create_test_table(conn: &Connection) {
+        conn.execute_batch(
+            "CREATE TABLE IF NOT EXISTS test_items (id INTEGER PRIMARY KEY, name TEXT);",
+        )
+        .expect("create test table");
+    }
+
+    #[test]
+    fn test_dbmanager_opens_successfully() {
+        let path = test_db_path();
+        let db = DbManager::open(&path).expect("open");
+        // Writer creates the test table
+        db.with_writer(|conn| {
+            create_test_table(conn);
+            Ok(())
+        })
+        .expect("create table via writer");
+    }
+
+    #[test]
+    fn test_reader_is_query_only() {
+        let path = test_db_path();
+        let db = DbManager::open(&path).expect("open");
+
+        // Create table via writer first
+        db.with_writer(|conn| {
+            create_test_table(conn);
+            Ok(())
+        })
+        .unwrap();
+
+        // Attempt INSERT via reader — should fail
+        let result = db.with_reader(|conn| {
+            conn.execute("INSERT INTO test_items (name) VALUES ('boom')", [])
+                .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(())
+        });
+        assert!(result.is_err(), "reader should reject writes");
+    }
+
+    #[test]
+    fn test_writer_allows_mutations() {
+        let path = test_db_path();
+        let db = DbManager::open(&path).expect("open");
+
+        db.with_writer(|conn| {
+            create_test_table(conn);
+            conn.execute("INSERT INTO test_items (name) VALUES ('hello')", [])?;
+            let count: i64 = conn.query_row("SELECT COUNT(*) FROM test_items", [], |r| r.get(0))?;
+            assert_eq!(count, 1);
+            Ok(())
+        })
+        .expect("writer should allow mutations");
+    }
+
+    #[test]
+    fn test_round_robin_rotates_readers() {
+        let path = test_db_path();
+        let db = DbManager::open(&path).expect("open");
+
+        // Call with_reader 6 times — should cycle through readers 0,1,2,0,1,2
+        for expected_cycle in 0..2 {
+            for expected_idx in 0..READER_COUNT {
+                let current = db.next_reader.load(Ordering::Relaxed);
+                assert_eq!(
+                    current % READER_COUNT,
+                    (expected_cycle * READER_COUNT + expected_idx) % READER_COUNT,
+                );
+                db.with_reader(|_conn| Ok(())).unwrap();
+            }
+        }
+    }
+
+    #[test]
+    fn test_reader_can_read_writer_data() {
+        let path = test_db_path();
+        let db = DbManager::open(&path).expect("open");
+
+        db.with_writer(|conn| {
+            create_test_table(conn);
+            conn.execute("INSERT INTO test_items (name) VALUES ('visible')", [])?;
+            Ok(())
+        })
+        .unwrap();
+
+        let name: String = db
+            .with_reader(|conn| {
+                let n: String =
+                    conn.query_row("SELECT name FROM test_items WHERE id = 1", [], |r| r.get(0))?;
+                Ok(n)
+            })
+            .expect("reader should see writer's data");
+
+        assert_eq!(name, "visible");
+    }
+
+    #[test]
+    fn test_dbmanager_is_send_sync() {
+        fn assert_send_sync<T: Send + Sync>() {}
+        assert_send_sync::<DbManager>();
+    }
+
+    #[test]
+    fn test_concurrent_reads() {
+        let path = test_db_path();
+        let db = Arc::new(DbManager::open(&path).expect("open"));
+
+        db.with_writer(|conn| {
+            create_test_table(conn);
+            for i in 0..10 {
+                conn.execute(
+                    "INSERT INTO test_items (name) VALUES (?1)",
+                    [format!("item-{i}")],
+                )?;
+            }
+            Ok(())
+        })
+        .unwrap();
+
+        let mut handles = Vec::new();
+        for _ in 0..6 {
+            let db = Arc::clone(&db);
+            handles.push(std::thread::spawn(move || {
+                db.with_reader(|conn| {
+                    let count: i64 =
+                        conn.query_row("SELECT COUNT(*) FROM test_items", [], |r| r.get(0))?;
+                    assert_eq!(count, 10);
+                    Ok(())
+                })
+                .expect("concurrent read should succeed");
+            }));
+        }
+
+        for h in handles {
+            h.join().expect("thread should not panic");
+        }
+    }
+}

crates/lore-tui/src/filter_dsl.rs

@@ -0,0 +1,316 @@
+#![allow(dead_code)] // Phase 2: consumed by filter_bar widget
+
+//! Filter DSL parser for entity list screens.
+//!
+//! Parses a compact filter string into structured tokens:
+//! - `field:value` — typed field filter (e.g., `state:opened`, `author:taylor`)
+//! - `-field:value` — negation filter (exclude matches)
+//! - `"quoted value"` — preserved as a single free-text token
+//! - bare words — free-text search terms
+//!
+//! The DSL is intentionally simple: no boolean operators, no nesting.
+//! Filters are AND-combined at the query layer.
+
+// ---------------------------------------------------------------------------
+// Token types
+// ---------------------------------------------------------------------------
+
+/// A single parsed filter token.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum FilterToken {
+    /// `field:value` — match entities where `field` equals `value`.
+    FieldValue { field: String, value: String },
+    /// `-field:value` — exclude entities where `field` equals `value`.
+    Negation { field: String, value: String },
+    /// Bare word(s) used as free-text search.
+    FreeText(String),
+    /// `"quoted value"` — preserved as a single search term.
+    QuotedValue(String),
+}
+
+// ---------------------------------------------------------------------------
+// Known fields per entity type
+// ---------------------------------------------------------------------------
+
+/// Known filter fields for issues.
+pub const ISSUE_FIELDS: &[&str] = &[
+    "state",
+    "author",
+    "assignee",
+    "label",
+    "milestone",
+    "status",
+];
+
+/// Known filter fields for merge requests.
+pub const MR_FIELDS: &[&str] = &[
+    "state",
+    "author",
+    "reviewer",
+    "target_branch",
+    "source_branch",
+    "label",
+    "draft",
+];
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+/// Parse a filter input string into a sequence of tokens.
+///
+/// Empty input returns an empty vec (no-op filter = show all).
+pub fn parse_filter_tokens(input: &str) -> Vec<FilterToken> {
+    let input = input.trim();
+    if input.is_empty() {
+        return Vec::new();
+    }
+
+    let mut tokens = Vec::new();
+    let mut chars = input.chars().peekable();
+
+    while chars.peek().is_some() {
+        // Skip whitespace between tokens.
+        while chars.peek().is_some_and(|c| c.is_whitespace()) {
+            chars.next();
+        }
+
+        match chars.peek() {
+            None => break,
+            Some('"') => {
+                // Quoted value — consume until closing quote or end.
+                chars.next(); // consume opening "
+                let value: String = consume_until(&mut chars, '"');
+                if chars.peek() == Some(&'"') {
+                    chars.next(); // consume closing "
+                }
+                if !value.is_empty() {
+                    tokens.push(FilterToken::QuotedValue(value));
+                }
+            }
+            Some('-') => {
+                // Could be negation prefix or just a free-text word starting with -.
+                chars.next(); // consume -
+                let word = consume_word(&mut chars);
+                if let Some((field, value)) = word.split_once(':') {
+                    tokens.push(FilterToken::Negation {
+                        field: field.to_string(),
+                        value: value.to_string(),
+                    });
+                } else if !word.is_empty() {
+                    // Bare negation without field:value — treat as free text with -.
+                    tokens.push(FilterToken::FreeText(format!("-{word}")));
+                }
+            }
+            Some(_) => {
+                let word = consume_word(&mut chars);
+                if let Some((field, value)) = word.split_once(':') {
+                    tokens.push(FilterToken::FieldValue {
+                        field: field.to_string(),
+                        value: value.to_string(),
+                    });
+                } else if !word.is_empty() {
+                    tokens.push(FilterToken::FreeText(word));
+                }
+            }
+        }
+    }
+
+    tokens
+}
+
+/// Validate that a field name is known for the given entity type.
+///
+/// Returns `true` if the field is in the known set, `false` otherwise.
+pub fn is_known_field(field: &str, known_fields: &[&str]) -> bool {
+    known_fields.contains(&field)
+}
+
+/// Extract all unknown fields from a token list.
+pub fn unknown_fields<'a>(tokens: &'a [FilterToken], known_fields: &[&str]) -> Vec<&'a str> {
+    tokens
+        .iter()
+        .filter_map(|t| match t {
+            FilterToken::FieldValue { field, .. } | FilterToken::Negation { field, .. } => {
+                if is_known_field(field, known_fields) {
+                    None
+                } else {
+                    Some(field.as_str())
+                }
+            }
+            _ => None,
+        })
+        .collect()
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// Consume characters until `delim` is found (exclusive) or end of input.
+fn consume_until(chars: &mut std::iter::Peekable<std::str::Chars<'_>>, delim: char) -> String {
+    let mut buf = String::new();
+    while let Some(&c) = chars.peek() {
+        if c == delim {
+            break;
+        }
+        buf.push(c);
+        chars.next();
+    }
+    buf
+}
+
+/// Consume a non-whitespace word.
+fn consume_word(chars: &mut std::iter::Peekable<std::str::Chars<'_>>) -> String {
+    let mut buf = String::new();
+    while let Some(&c) = chars.peek() {
+        if c.is_whitespace() {
+            break;
+        }
+        // Stop at quote boundaries so they're handled separately.
+        if c == '"' && !buf.is_empty() {
+            break;
+        }
+        buf.push(c);
+        chars.next();
+    }
+    buf
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // -- TDD Anchor: basic field:value parsing --
+
+    #[test]
+    fn test_parse_filter_basic() {
+        let tokens = parse_filter_tokens("state:opened author:taylor");
+        assert_eq!(tokens.len(), 2);
+        assert_eq!(
+            tokens[0],
+            FilterToken::FieldValue {
+                field: "state".into(),
+                value: "opened".into()
+            }
+        );
+        assert_eq!(
+            tokens[1],
+            FilterToken::FieldValue {
+                field: "author".into(),
+                value: "taylor".into()
+            }
+        );
+    }
+
+    #[test]
+    fn test_parse_quoted_value() {
+        let tokens = parse_filter_tokens("\"in progress\"");
+        assert_eq!(tokens.len(), 1);
+        assert_eq!(tokens[0], FilterToken::QuotedValue("in progress".into()));
+    }
+
+    #[test]
+    fn test_parse_negation() {
+        let tokens = parse_filter_tokens("-state:closed");
+        assert_eq!(tokens.len(), 1);
+        assert_eq!(
+            tokens[0],
+            FilterToken::Negation {
+                field: "state".into(),
+                value: "closed".into()
+            }
+        );
+    }
+
+    #[test]
+    fn test_parse_mixed() {
+        let tokens = parse_filter_tokens("state:opened \"bug fix\" -label:wontfix");
+        assert_eq!(tokens.len(), 3);
+        assert_eq!(
+            tokens[0],
+            FilterToken::FieldValue {
+                field: "state".into(),
+                value: "opened".into()
+            }
+        );
+        assert_eq!(tokens[1], FilterToken::QuotedValue("bug fix".into()));
+        assert_eq!(
+            tokens[2],
+            FilterToken::Negation {
+                field: "label".into(),
+                value: "wontfix".into()
+            }
+        );
+    }
+
+    #[test]
+    fn test_parse_empty_returns_empty() {
+        assert!(parse_filter_tokens("").is_empty());
+        assert!(parse_filter_tokens("   ").is_empty());
+    }
+
+    #[test]
+    fn test_parse_free_text() {
+        let tokens = parse_filter_tokens("authentication bug");
+        assert_eq!(tokens.len(), 2);
+        assert_eq!(tokens[0], FilterToken::FreeText("authentication".into()));
+        assert_eq!(tokens[1], FilterToken::FreeText("bug".into()));
+    }
+
+    #[test]
+    fn test_parse_bare_negation_as_free_text() {
+        let tokens = parse_filter_tokens("-wontfix");
+        assert_eq!(tokens.len(), 1);
+        assert_eq!(tokens[0], FilterToken::FreeText("-wontfix".into()));
+    }
+
+    #[test]
+    fn test_parse_unicode() {
+        let tokens = parse_filter_tokens("author:田中 \"認証バグ\"");
+        assert_eq!(tokens.len(), 2);
+        assert_eq!(
+            tokens[0],
+            FilterToken::FieldValue {
+                field: "author".into(),
+                value: "田中".into()
+            }
+        );
+        assert_eq!(tokens[1], FilterToken::QuotedValue("認証バグ".into()));
+    }
+
+    #[test]
+    fn test_parse_unclosed_quote() {
+        let tokens = parse_filter_tokens("\"open ended");
+        assert_eq!(tokens.len(), 1);
+        assert_eq!(tokens[0], FilterToken::QuotedValue("open ended".into()));
+    }
+
+    // -- Field validation --
+
+    #[test]
+    fn test_known_field_issues() {
+        assert!(is_known_field("state", ISSUE_FIELDS));
+        assert!(is_known_field("author", ISSUE_FIELDS));
+        assert!(!is_known_field("reviewer", ISSUE_FIELDS));
+        assert!(!is_known_field("bogus", ISSUE_FIELDS));
+    }
+
+    #[test]
+    fn test_known_field_mrs() {
+        assert!(is_known_field("draft", MR_FIELDS));
+        assert!(is_known_field("reviewer", MR_FIELDS));
+        assert!(!is_known_field("assignee", MR_FIELDS));
+    }
+
+    #[test]
+    fn test_unknown_fields_detection() {
+        let tokens = parse_filter_tokens("state:opened bogus:val author:taylor unknown:x");
+        let unknown = unknown_fields(&tokens, ISSUE_FIELDS);
+        assert_eq!(unknown, vec!["bogus", "unknown"]);
+    }
+}

crates/lore-tui/src/layout.rs

@@ -0,0 +1,102 @@
+#![allow(clippy::module_name_repetitions)]
+
+//! Responsive layout helpers for the Lore TUI.
+//!
+//! Wraps [`ftui::layout::Breakpoint`] and [`ftui::layout::Breakpoints`] with
+//! Lore-specific configuration: breakpoint thresholds, column counts per
+//! breakpoint, and preview-pane visibility rules.
+
+use ftui::layout::{Breakpoint, Breakpoints};
+
+/// Lore-specific breakpoint thresholds.
+///
+/// Uses the ftui defaults: Sm=60, Md=90, Lg=120, Xl=160 columns.
+pub const LORE_BREAKPOINTS: Breakpoints = Breakpoints::DEFAULT;
+
+/// Classify a terminal width into a [`Breakpoint`].
+#[inline]
+pub fn classify_width(width: u16) -> Breakpoint {
+    LORE_BREAKPOINTS.classify_width(width)
+}
+
+/// Number of dashboard columns for a given breakpoint.
+///
+/// - `Xs` / `Sm`: 1 column (narrow terminals)
+/// - `Md`: 2 columns (standard width)
+/// - `Lg` / `Xl`: 3 columns (wide terminals)
+#[inline]
+pub const fn dashboard_columns(bp: Breakpoint) -> u16 {
+    match bp {
+        Breakpoint::Xs | Breakpoint::Sm => 1,
+        Breakpoint::Md => 2,
+        Breakpoint::Lg | Breakpoint::Xl => 3,
+    }
+}
+
+/// Whether the preview pane should be visible at a given breakpoint.
+///
+/// Preview requires at least `Md` width to avoid cramping the main list.
+#[inline]
+pub const fn show_preview_pane(bp: Breakpoint) -> bool {
+    match bp {
+        Breakpoint::Md | Breakpoint::Lg | Breakpoint::Xl => true,
+        Breakpoint::Xs | Breakpoint::Sm => false,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_classify_width_boundaries() {
+        // Xs: 0..59
+        assert_eq!(classify_width(59), Breakpoint::Xs);
+        // Sm: 60..89
+        assert_eq!(classify_width(60), Breakpoint::Sm);
+        assert_eq!(classify_width(89), Breakpoint::Sm);
+        // Md: 90..119
+        assert_eq!(classify_width(90), Breakpoint::Md);
+        assert_eq!(classify_width(119), Breakpoint::Md);
+        // Lg: 120..159
+        assert_eq!(classify_width(120), Breakpoint::Lg);
+        assert_eq!(classify_width(159), Breakpoint::Lg);
+        // Xl: 160+
+        assert_eq!(classify_width(160), Breakpoint::Xl);
+    }
+
+    #[test]
+    fn test_dashboard_columns_per_breakpoint() {
+        assert_eq!(dashboard_columns(Breakpoint::Xs), 1);
+        assert_eq!(dashboard_columns(Breakpoint::Sm), 1);
+        assert_eq!(dashboard_columns(Breakpoint::Md), 2);
+        assert_eq!(dashboard_columns(Breakpoint::Lg), 3);
+        assert_eq!(dashboard_columns(Breakpoint::Xl), 3);
+    }
+
+    #[test]
+    fn test_show_preview_pane_per_breakpoint() {
+        assert!(!show_preview_pane(Breakpoint::Xs));
+        assert!(!show_preview_pane(Breakpoint::Sm));
+        assert!(show_preview_pane(Breakpoint::Md));
+        assert!(show_preview_pane(Breakpoint::Lg));
+        assert!(show_preview_pane(Breakpoint::Xl));
+    }
+
+    #[test]
+    fn test_edge_cases() {
+        // Width 0 must not panic, should classify as Xs
+        assert_eq!(classify_width(0), Breakpoint::Xs);
+        // Very wide terminal
+        assert_eq!(classify_width(300), Breakpoint::Xl);
+    }
+
+    #[test]
+    fn test_lore_breakpoints_matches_defaults() {
+        assert_eq!(LORE_BREAKPOINTS, Breakpoints::DEFAULT);
+    }
+}

crates/lore-tui/src/lib.rs

@@ -0,0 +1,71 @@
+#![forbid(unsafe_code)]
+
+//! Gitlore TUI — terminal interface for exploring GitLab data locally.
+//!
+//! Built on FrankenTUI (Elm architecture): Model, update, view.
+//! The `lore` CLI spawns `lore-tui` via PATH lookup at runtime.
+
+use anyhow::Result;
+
+// Phase 0 modules.
+pub mod clock; // Clock trait: SystemClock + FakeClock (bd-2lg6)
+pub mod message; // Msg, Screen, EntityKey, AppError, InputMode (bd-c9gk)
+
+pub mod safety; // Terminal safety: sanitize + URL policy + redact (bd-3ir1)
+
+pub mod db; // DbManager: read pool + dedicated writer (bd-2kop)
+pub mod theme; // Flexoki theme: build_theme, state_color, label_style (bd-5ofk)
+
+pub mod app; // LoreApp Model trait impl (Phase 0 proof: bd-2emv, full: bd-6pmy)
+
+// Phase 1 modules.
+pub mod commands; // CommandRegistry: keybindings, help, palette (bd-38lb)
+pub mod crash_context; // CrashContext ring buffer + panic hook (bd-2fr7)
+pub mod layout; // Responsive layout: breakpoints, columns, preview pane (bd-1pzj)
+pub mod navigation; // NavigationStack: back/forward/jump list (bd-1qpp)
+pub mod state; // AppState, LoadState, ScreenIntent, per-screen states (bd-1v9m)
+pub mod task_supervisor; // TaskSupervisor: dedup + cancel + generation IDs (bd-3le2)
+pub mod view; // View layer: render_screen + common widgets (bd-26f2)
+
+// Phase 2 modules.
+pub mod action; // Data-fetching actions for TUI screens (bd-35g5+)
+pub mod filter_dsl; // Filter DSL tokenizer for list screen filter bars (bd-18qs)
+
+/// Options controlling how the TUI launches.
+#[derive(Debug, Clone)]
+pub struct LaunchOptions {
+    /// Path to lore config file.
+    pub config_path: Option<String>,
+    /// Run a background sync before displaying data.
+    pub sync_on_start: bool,
+    /// Clear cached TUI state and start fresh.
+    pub fresh: bool,
+    /// Render backend: "crossterm" or "native".
+    pub render_mode: String,
+    /// Use ASCII-only box drawing characters.
+    pub ascii: bool,
+    /// Disable alternate screen (render inline).
+    pub no_alt_screen: bool,
+}
+
+/// Launch the TUI in browse mode (no sync).
+///
+/// Loads config from `options.config_path` (or default location),
+/// opens the database read-only, and enters the FrankenTUI event loop.
+pub fn launch_tui(options: LaunchOptions) -> Result<()> {
+    let _options = options;
+    // Phase 1 will wire this to LoreApp + App::fullscreen().run()
+    eprintln!("lore-tui: browse mode not yet implemented (Phase 1)");
+    Ok(())
+}
+
+/// Launch the TUI with an initial sync pass.
+///
+/// Runs `lore sync` in the background while displaying a progress screen,
+/// then transitions to browse mode once sync completes.
+pub fn launch_sync_tui(options: LaunchOptions) -> Result<()> {
+    let _options = options;
+    // Phase 2 will implement the sync progress screen
+    eprintln!("lore-tui: sync mode not yet implemented (Phase 2)");
+    Ok(())
+}

crates/lore-tui/src/main.rs

@@ -0,0 +1,53 @@
+#![forbid(unsafe_code)]
+
+use anyhow::Result;
+use clap::Parser;
+use lore_tui::LaunchOptions;
+
+/// Terminal UI for Gitlore — explore GitLab issues, MRs, and search locally.
+#[derive(Parser, Debug)]
+#[command(name = "lore-tui", version, about)]
+struct TuiCli {
+    /// Path to lore config file (default: ~/.config/lore/config.json).
+    #[arg(short, long, env = "LORE_CONFIG_PATH")]
+    config: Option<String>,
+
+    /// Run a sync before launching the TUI.
+    #[arg(long)]
+    sync: bool,
+
+    /// Clear cached state and start fresh.
+    #[arg(long)]
+    fresh: bool,
+
+    /// Render mode: "crossterm" (default) or "native".
+    #[arg(long, default_value = "crossterm")]
+    render_mode: String,
+
+    /// Use ASCII-only drawing characters (no Unicode box drawing).
+    #[arg(long)]
+    ascii: bool,
+
+    /// Disable alternate screen (render inline).
+    #[arg(long)]
+    no_alt_screen: bool,
+}
+
+fn main() -> Result<()> {
+    let cli = TuiCli::parse();
+
+    let options = LaunchOptions {
+        config_path: cli.config,
+        sync_on_start: cli.sync,
+        fresh: cli.fresh,
+        render_mode: cli.render_mode,
+        ascii: cli.ascii,
+        no_alt_screen: cli.no_alt_screen,
+    };
+
+    if options.sync_on_start {
+        lore_tui::launch_sync_tui(options)
+    } else {
+        lore_tui::launch_tui(options)
+    }
+}

crates/lore-tui/src/message.rs

@@ -0,0 +1,502 @@
+#![allow(dead_code)] // Phase 0: types defined now, consumed in Phase 1+
+
+//! Core types for the lore-tui Elm architecture.
+//!
+//! - [`Msg`] — every user action and async result flows through this enum.
+//! - [`Screen`] — navigation targets.
+//! - [`EntityKey`] — safe cross-project entity identity.
+//! - [`AppError`] — structured error display in the TUI.
+//! - [`InputMode`] — controls key dispatch routing.
+
+use std::fmt;
+
+use chrono::{DateTime, Utc};
+use ftui::Event;
+
+// ---------------------------------------------------------------------------
+// EntityKind
+// ---------------------------------------------------------------------------
+
+/// Distinguishes issue vs merge request in an [`EntityKey`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum EntityKind {
+    Issue,
+    MergeRequest,
+}
+
+// ---------------------------------------------------------------------------
+// EntityKey
+// ---------------------------------------------------------------------------
+
+/// Uniquely identifies an entity (issue or MR) across projects.
+///
+/// Bare `iid` is unsafe in multi-project datasets — equality requires
+/// project_id + iid + kind.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct EntityKey {
+    pub project_id: i64,
+    pub iid: i64,
+    pub kind: EntityKind,
+}
+
+impl EntityKey {
+    #[must_use]
+    pub fn issue(project_id: i64, iid: i64) -> Self {
+        Self {
+            project_id,
+            iid,
+            kind: EntityKind::Issue,
+        }
+    }
+
+    #[must_use]
+    pub fn mr(project_id: i64, iid: i64) -> Self {
+        Self {
+            project_id,
+            iid,
+            kind: EntityKind::MergeRequest,
+        }
+    }
+}
+
+impl fmt::Display for EntityKey {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let prefix = match self.kind {
+            EntityKind::Issue => "#",
+            EntityKind::MergeRequest => "!",
+        };
+        write!(f, "p{}:{}{}", self.project_id, prefix, self.iid)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Screen
+// ---------------------------------------------------------------------------
+
+/// Navigation targets within the TUI.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum Screen {
+    Dashboard,
+    IssueList,
+    IssueDetail(EntityKey),
+    MrList,
+    MrDetail(EntityKey),
+    Search,
+    Timeline,
+    Who,
+    Sync,
+    Stats,
+    Doctor,
+    Bootstrap,
+}
+
+impl Screen {
+    /// Human-readable label for breadcrumbs and status bar.
+    #[must_use]
+    pub fn label(&self) -> &str {
+        match self {
+            Self::Dashboard => "Dashboard",
+            Self::IssueList => "Issues",
+            Self::IssueDetail(_) => "Issue",
+            Self::MrList => "Merge Requests",
+            Self::MrDetail(_) => "Merge Request",
+            Self::Search => "Search",
+            Self::Timeline => "Timeline",
+            Self::Who => "Who",
+            Self::Sync => "Sync",
+            Self::Stats => "Stats",
+            Self::Doctor => "Doctor",
+            Self::Bootstrap => "Bootstrap",
+        }
+    }
+
+    /// Whether this screen shows a specific entity detail view.
+    #[must_use]
+    pub fn is_detail_or_entity(&self) -> bool {
+        matches!(self, Self::IssueDetail(_) | Self::MrDetail(_))
+    }
+}
+
+// ---------------------------------------------------------------------------
+// AppError
+// ---------------------------------------------------------------------------
+
+/// Structured error types for user-facing display in the TUI.
+#[derive(Debug, Clone)]
+pub enum AppError {
+    /// Database is busy (WAL contention).
+    DbBusy,
+    /// Database corruption detected.
+    DbCorruption(String),
+    /// GitLab rate-limited; retry after N seconds (if header present).
+    NetworkRateLimited { retry_after_secs: Option<u64> },
+    /// Network unavailable.
+    NetworkUnavailable,
+    /// GitLab authentication failed.
+    AuthFailed,
+    /// Data parsing error.
+    ParseError(String),
+    /// Internal / unexpected error.
+    Internal(String),
+}
+
+impl fmt::Display for AppError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::DbBusy => write!(f, "Database is busy — another process holds the lock"),
+            Self::DbCorruption(detail) => write!(f, "Database corruption: {detail}"),
+            Self::NetworkRateLimited {
+                retry_after_secs: Some(secs),
+            } => write!(f, "Rate limited by GitLab — retry in {secs}s"),
+            Self::NetworkRateLimited {
+                retry_after_secs: None,
+            } => write!(f, "Rate limited by GitLab — try again shortly"),
+            Self::NetworkUnavailable => write!(f, "Network unavailable — working offline"),
+            Self::AuthFailed => write!(f, "GitLab authentication failed — check your token"),
+            Self::ParseError(detail) => write!(f, "Parse error: {detail}"),
+            Self::Internal(detail) => write!(f, "Internal error: {detail}"),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// InputMode
+// ---------------------------------------------------------------------------
+
+/// Controls how keystrokes are routed through the key dispatch pipeline.
+#[derive(Debug, Clone, Default)]
+pub enum InputMode {
+    /// Standard navigation mode — keys dispatch to screen-specific handlers.
+    #[default]
+    Normal,
+    /// Text input focused (filter bar, search box).
+    Text,
+    /// Command palette is open.
+    Palette,
+    /// "g" prefix pressed — waiting for second key (500ms timeout).
+    GoPrefix { started_at: DateTime<Utc> },
+}
+
+// ---------------------------------------------------------------------------
+// Msg
+// ---------------------------------------------------------------------------
+
+/// Every user action and async result flows through this enum.
+///
+/// Generation fields (`generation: u64`) on async result variants enable
+/// stale-response detection: if the generation doesn't match the current
+/// request generation, the result is silently dropped.
+#[derive(Debug)]
+pub enum Msg {
+    // --- Terminal events ---
+    /// Raw terminal event (key, mouse, paste, focus, clipboard).
+    RawEvent(Event),
+    /// Periodic tick from runtime subscription.
+    Tick,
+    /// Terminal resized.
+    Resize {
+        width: u16,
+        height: u16,
+    },
+
+    // --- Navigation ---
+    /// Navigate to a specific screen.
+    NavigateTo(Screen),
+    /// Go back in navigation history.
+    GoBack,
+    /// Go forward in navigation history.
+    GoForward,
+    /// Jump to the dashboard.
+    GoHome,
+    /// Jump back N screens in history.
+    JumpBack(usize),
+    /// Jump forward N screens in history.
+    JumpForward(usize),
+
+    // --- Command palette ---
+    OpenCommandPalette,
+    CloseCommandPalette,
+    CommandPaletteInput(String),
+    CommandPaletteSelect(String),
+
+    // --- Issue list ---
+    IssueListLoaded {
+        generation: u64,
+        page: crate::state::issue_list::IssueListPage,
+    },
+    IssueListFilterChanged(String),
+    IssueListSortChanged,
+    IssueSelected(EntityKey),
+
+    // --- MR list ---
+    MrListLoaded {
+        generation: u64,
+        page: crate::state::mr_list::MrListPage,
+    },
+    MrListFilterChanged(String),
+    MrSelected(EntityKey),
+
+    // --- Issue detail ---
+    IssueDetailLoaded {
+        generation: u64,
+        key: EntityKey,
+        detail: Box<IssueDetail>,
+    },
+
+    // --- MR detail ---
+    MrDetailLoaded {
+        generation: u64,
+        key: EntityKey,
+        detail: Box<MrDetail>,
+    },
+
+    // --- Discussions (shared by issue + MR detail) ---
+    DiscussionsLoaded {
+        generation: u64,
+        discussions: Vec<Discussion>,
+    },
+
+    // --- Search ---
+    SearchQueryChanged(String),
+    SearchRequestStarted {
+        generation: u64,
+        query: String,
+    },
+    SearchExecuted {
+        generation: u64,
+        results: Vec<SearchResult>,
+    },
+    SearchResultSelected(EntityKey),
+    SearchModeChanged,
+    SearchCapabilitiesLoaded,
+
+    // --- Timeline ---
+    TimelineLoaded {
+        generation: u64,
+        events: Vec<TimelineEvent>,
+    },
+    TimelineEntitySelected(EntityKey),
+
+    // --- Who (people) ---
+    WhoResultLoaded {
+        generation: u64,
+        result: Box<WhoResult>,
+    },
+    WhoModeChanged,
+
+    // --- Sync ---
+    SyncStarted,
+    SyncProgress {
+        stage: String,
+        current: u64,
+        total: u64,
+    },
+    SyncProgressBatch {
+        stage: String,
+        batch_size: u64,
+    },
+    SyncLogLine(String),
+    SyncBackpressureDrop,
+    SyncCompleted {
+        elapsed_ms: u64,
+    },
+    SyncCancelled,
+    SyncFailed(String),
+    SyncStreamStats {
+        bytes: u64,
+        items: u64,
+    },
+
+    // --- Search debounce ---
+    SearchDebounceArmed {
+        generation: u64,
+    },
+    SearchDebounceFired {
+        generation: u64,
+    },
+
+    // --- Dashboard ---
+    DashboardLoaded {
+        generation: u64,
+        data: Box<crate::state::dashboard::DashboardData>,
+    },
+
+    // --- Global actions ---
+    Error(AppError),
+    ShowHelp,
+    ShowCliEquivalent,
+    OpenInBrowser,
+    BlurTextInput,
+    ScrollToTopCurrentScreen,
+    Quit,
+}
+
+/// Convert terminal events into messages.
+///
+/// FrankenTUI requires `From<Event>` on the message type so the runtime
+/// can inject terminal events into the model's update loop.
+impl From<Event> for Msg {
+    fn from(event: Event) -> Self {
+        match event {
+            Event::Resize { width, height } => Self::Resize { width, height },
+            Event::Tick => Self::Tick,
+            other => Self::RawEvent(other),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Placeholder data types (will be fleshed out in Phase 1+)
+// ---------------------------------------------------------------------------
+
+/// Placeholder for issue detail payload.
+#[derive(Debug, Clone)]
+pub struct IssueDetail {
+    pub key: EntityKey,
+    pub title: String,
+    pub description: String,
+}
+
+/// Placeholder for MR detail payload.
+#[derive(Debug, Clone)]
+pub struct MrDetail {
+    pub key: EntityKey,
+    pub title: String,
+    pub description: String,
+}
+
+/// Placeholder for a discussion thread.
+#[derive(Debug, Clone)]
+pub struct Discussion {
+    pub id: String,
+    pub notes: Vec<String>,
+}
+
+/// Placeholder for a search result.
+#[derive(Debug, Clone)]
+pub struct SearchResult {
+    pub key: EntityKey,
+    pub title: String,
+    pub score: f64,
+}
+
+/// Placeholder for a timeline event.
+#[derive(Debug, Clone)]
+pub struct TimelineEvent {
+    pub timestamp: String,
+    pub description: String,
+}
+
+/// Placeholder for who/people intelligence result.
+#[derive(Debug, Clone)]
+pub struct WhoResult {
+    pub experts: Vec<String>,
+}
+
+// DashboardData moved to crate::state::dashboard (enriched with
+// EntityCounts, ProjectSyncInfo, RecentActivityItem, LastSyncInfo).
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_entity_key_equality() {
+        assert_eq!(EntityKey::issue(1, 42), EntityKey::issue(1, 42));
+        assert_ne!(EntityKey::issue(1, 42), EntityKey::mr(1, 42));
+    }
+
+    #[test]
+    fn test_entity_key_different_projects() {
+        assert_ne!(EntityKey::issue(1, 42), EntityKey::issue(2, 42));
+    }
+
+    #[test]
+    fn test_entity_key_display() {
+        assert_eq!(EntityKey::issue(5, 123).to_string(), "p5:#123");
+        assert_eq!(EntityKey::mr(5, 456).to_string(), "p5:!456");
+    }
+
+    #[test]
+    fn test_entity_key_hash_is_usable_in_collections() {
+        use std::collections::HashSet;
+        let mut set = HashSet::new();
+        set.insert(EntityKey::issue(1, 1));
+        set.insert(EntityKey::issue(1, 1)); // duplicate
+        set.insert(EntityKey::mr(1, 1));
+        assert_eq!(set.len(), 2);
+    }
+
+    #[test]
+    fn test_screen_labels() {
+        assert_eq!(Screen::Dashboard.label(), "Dashboard");
+        assert_eq!(Screen::IssueList.label(), "Issues");
+        assert_eq!(Screen::MrList.label(), "Merge Requests");
+        assert_eq!(Screen::Search.label(), "Search");
+    }
+
+    #[test]
+    fn test_screen_is_detail_or_entity() {
+        assert!(Screen::IssueDetail(EntityKey::issue(1, 1)).is_detail_or_entity());
+        assert!(Screen::MrDetail(EntityKey::mr(1, 1)).is_detail_or_entity());
+        assert!(!Screen::Dashboard.is_detail_or_entity());
+        assert!(!Screen::IssueList.is_detail_or_entity());
+        assert!(!Screen::Search.is_detail_or_entity());
+    }
+
+    #[test]
+    fn test_app_error_display() {
+        let err = AppError::DbBusy;
+        assert!(err.to_string().contains("busy"));
+
+        let err = AppError::NetworkRateLimited {
+            retry_after_secs: Some(30),
+        };
+        assert!(err.to_string().contains("30s"));
+
+        let err = AppError::NetworkRateLimited {
+            retry_after_secs: None,
+        };
+        assert!(err.to_string().contains("shortly"));
+
+        let err = AppError::AuthFailed;
+        assert!(err.to_string().contains("token"));
+    }
+
+    #[test]
+    fn test_input_mode_default_is_normal() {
+        assert!(matches!(InputMode::default(), InputMode::Normal));
+    }
+
+    #[test]
+    fn test_msg_from_event_resize() {
+        let event = Event::Resize {
+            width: 80,
+            height: 24,
+        };
+        let msg = Msg::from(event);
+        assert!(matches!(
+            msg,
+            Msg::Resize {
+                width: 80,
+                height: 24
+            }
+        ));
+    }
+
+    #[test]
+    fn test_msg_from_event_tick() {
+        let msg = Msg::from(Event::Tick);
+        assert!(matches!(msg, Msg::Tick));
+    }
+
+    #[test]
+    fn test_msg_from_event_focus_wraps_raw() {
+        let msg = Msg::from(Event::Focus(true));
+        assert!(matches!(msg, Msg::RawEvent(Event::Focus(true))));
+    }
+}

crates/lore-tui/src/navigation.rs

@@ -0,0 +1,350 @@
+#![allow(dead_code)] // Phase 1: consumed by LoreApp in bd-6pmy
+
+//! Browser-like navigation stack with vim-style jump list.
+//!
+//! Supports back/forward (browser), jump back/forward (vim Ctrl+O/Ctrl+I),
+//! and breadcrumb generation. State is preserved when navigating away —
+//! screens are never cleared on pop.
+
+use crate::message::Screen;
+
+// ---------------------------------------------------------------------------
+// NavigationStack
+// ---------------------------------------------------------------------------
+
+/// Browser-like navigation with back/forward stacks and a vim jump list.
+///
+/// The jump list only records "significant" hops — detail views and
+/// cross-references — skipping list/dashboard screens that users
+/// visit briefly during drilling.
+pub struct NavigationStack {
+    back_stack: Vec<Screen>,
+    current: Screen,
+    forward_stack: Vec<Screen>,
+    jump_list: Vec<Screen>,
+    jump_index: usize,
+}
+
+impl NavigationStack {
+    /// Create a new stack starting at the Dashboard.
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            back_stack: Vec::new(),
+            current: Screen::Dashboard,
+            forward_stack: Vec::new(),
+            jump_list: Vec::new(),
+            jump_index: 0,
+        }
+    }
+
+    /// The currently displayed screen.
+    #[must_use]
+    pub fn current(&self) -> &Screen {
+        &self.current
+    }
+
+    /// Whether the current screen matches the given screen.
+    #[must_use]
+    pub fn is_at(&self, screen: &Screen) -> bool {
+        &self.current == screen
+    }
+
+    /// Navigate to a new screen.
+    ///
+    /// Pushes current to back_stack, clears forward_stack (browser behavior),
+    /// and records detail hops in the jump list.
+    pub fn push(&mut self, screen: Screen) {
+        let old = std::mem::replace(&mut self.current, screen);
+        self.back_stack.push(old);
+        self.forward_stack.clear();
+
+        // Record significant hops in jump list (vim behavior):
+        // Keep entries up to and including the current position, discard
+        // any forward entries beyond it, then append the new destination.
+        if self.current.is_detail_or_entity() {
+            self.jump_list.truncate(self.jump_index.saturating_add(1));
+            self.jump_list.push(self.current.clone());
+            self.jump_index = self.jump_list.len();
+        }
+    }
+
+    /// Go back to the previous screen.
+    ///
+    /// Returns `None` at root (can't pop past the initial screen).
+    pub fn pop(&mut self) -> Option<&Screen> {
+        let prev = self.back_stack.pop()?;
+        let old = std::mem::replace(&mut self.current, prev);
+        self.forward_stack.push(old);
+        Some(&self.current)
+    }
+
+    /// Go forward (redo a pop).
+    ///
+    /// Returns `None` if there's nothing to go forward to.
+    pub fn go_forward(&mut self) -> Option<&Screen> {
+        let next = self.forward_stack.pop()?;
+        let old = std::mem::replace(&mut self.current, next);
+        self.back_stack.push(old);
+        Some(&self.current)
+    }
+
+    /// Jump backward through the jump list (vim Ctrl+O).
+    ///
+    /// Only visits detail/entity screens. Skips entries matching the
+    /// current screen so the first press always produces a visible change.
+    pub fn jump_back(&mut self) -> Option<&Screen> {
+        while self.jump_index > 0 {
+            self.jump_index -= 1;
+            if let Some(target) = self.jump_list.get(self.jump_index).cloned()
+                && target != self.current
+            {
+                self.current = target;
+                return Some(&self.current);
+            }
+        }
+        None
+    }
+
+    /// Jump forward through the jump list (vim Ctrl+I).
+    ///
+    /// Skips entries matching the current screen.
+    pub fn jump_forward(&mut self) -> Option<&Screen> {
+        while self.jump_index < self.jump_list.len() {
+            if let Some(target) = self.jump_list.get(self.jump_index).cloned() {
+                self.jump_index += 1;
+                if target != self.current {
+                    self.current = target;
+                    return Some(&self.current);
+                }
+            } else {
+                break;
+            }
+        }
+        None
+    }
+
+    /// Reset to a single screen, clearing all history.
+    pub fn reset_to(&mut self, screen: Screen) {
+        self.current = screen;
+        self.back_stack.clear();
+        self.forward_stack.clear();
+        self.jump_list.clear();
+        self.jump_index = 0;
+    }
+
+    /// Breadcrumb labels for the current navigation path.
+    ///
+    /// Returns the back stack labels plus the current screen label.
+    #[must_use]
+    pub fn breadcrumbs(&self) -> Vec<&str> {
+        self.back_stack
+            .iter()
+            .chain(std::iter::once(&self.current))
+            .map(Screen::label)
+            .collect()
+    }
+
+    /// Navigation depth (1 = at root, 2 = one push deep, etc.).
+    #[must_use]
+    pub fn depth(&self) -> usize {
+        self.back_stack.len() + 1
+    }
+
+    /// Whether there's anything to go back to.
+    #[must_use]
+    pub fn can_go_back(&self) -> bool {
+        !self.back_stack.is_empty()
+    }
+
+    /// Whether there's anything to go forward to.
+    #[must_use]
+    pub fn can_go_forward(&self) -> bool {
+        !self.forward_stack.is_empty()
+    }
+}
+
+impl Default for NavigationStack {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::message::EntityKey;
+
+    #[test]
+    fn test_new_starts_at_dashboard() {
+        let nav = NavigationStack::new();
+        assert!(nav.is_at(&Screen::Dashboard));
+        assert_eq!(nav.depth(), 1);
+    }
+
+    #[test]
+    fn test_push_pop_preserves_order() {
+        let mut nav = NavigationStack::new();
+        nav.push(Screen::IssueList);
+        nav.push(Screen::IssueDetail(EntityKey::issue(1, 42)));
+
+        assert!(nav.is_at(&Screen::IssueDetail(EntityKey::issue(1, 42))));
+        assert_eq!(nav.depth(), 3);
+
+        nav.pop();
+        assert!(nav.is_at(&Screen::IssueList));
+
+        nav.pop();
+        assert!(nav.is_at(&Screen::Dashboard));
+    }
+
+    #[test]
+    fn test_pop_at_root_returns_none() {
+        let mut nav = NavigationStack::new();
+        assert!(nav.pop().is_none());
+        assert!(nav.is_at(&Screen::Dashboard));
+    }
+
+    #[test]
+    fn test_forward_stack_cleared_on_new_push() {
+        let mut nav = NavigationStack::new();
+        nav.push(Screen::IssueList);
+        nav.push(Screen::Search);
+        nav.pop(); // back to IssueList, Search in forward
+        assert!(nav.can_go_forward());
+
+        nav.push(Screen::Timeline); // new push clears forward
+        assert!(!nav.can_go_forward());
+    }
+
+    #[test]
+    fn test_go_forward_restores() {
+        let mut nav = NavigationStack::new();
+        nav.push(Screen::IssueList);
+        nav.push(Screen::Search);
+        nav.pop(); // back to IssueList
+
+        let screen = nav.go_forward();
+        assert!(screen.is_some());
+        assert!(nav.is_at(&Screen::Search));
+    }
+
+    #[test]
+    fn test_go_forward_returns_none_when_empty() {
+        let mut nav = NavigationStack::new();
+        assert!(nav.go_forward().is_none());
+    }
+
+    #[test]
+    fn test_jump_list_skips_list_screens() {
+        let mut nav = NavigationStack::new();
+        nav.push(Screen::IssueList); // not a detail — skip
+        nav.push(Screen::IssueDetail(EntityKey::issue(1, 1))); // detail — record
+        nav.push(Screen::MrList); // not a detail — skip
+        nav.push(Screen::MrDetail(EntityKey::mr(1, 2))); // detail — record
+
+        assert_eq!(nav.jump_list.len(), 2);
+    }
+
+    #[test]
+    fn test_jump_back_and_forward() {
+        let mut nav = NavigationStack::new();
+        let issue = Screen::IssueDetail(EntityKey::issue(1, 1));
+        let mr = Screen::MrDetail(EntityKey::mr(1, 2));
+
+        nav.push(Screen::IssueList);
+        nav.push(issue.clone());
+        nav.push(Screen::MrList);
+        nav.push(mr.clone());
+
+        // Current is MrDetail. jump_list = [IssueDetail, MrDetail], index = 2.
+        // First jump_back skips MrDetail (== current) and lands on IssueDetail.
+        let prev = nav.jump_back();
+        assert_eq!(prev, Some(&issue));
+        assert!(nav.is_at(&issue));
+
+        // Already at beginning of jump list.
+        assert!(nav.jump_back().is_none());
+
+        // jump_forward skips IssueDetail (== current) and lands on MrDetail.
+        let next = nav.jump_forward();
+        assert_eq!(next, Some(&mr));
+        assert!(nav.is_at(&mr));
+
+        // At end of jump list.
+        assert!(nav.jump_forward().is_none());
+    }
+
+    #[test]
+    fn test_jump_list_truncates_on_new_push() {
+        let mut nav = NavigationStack::new();
+        nav.push(Screen::IssueDetail(EntityKey::issue(1, 1)));
+        nav.push(Screen::IssueDetail(EntityKey::issue(1, 2)));
+        nav.push(Screen::IssueDetail(EntityKey::issue(1, 3)));
+
+        // jump back twice — lands on issue(1,1), jump_index = 0
+        nav.jump_back();
+        nav.jump_back();
+
+        // new detail push truncates forward entries
+        nav.push(Screen::MrDetail(EntityKey::mr(1, 99)));
+
+        // should have issue(1,1) and mr(1,99), not issue(1,2) or issue(1,3)
+        assert_eq!(nav.jump_list.len(), 2);
+        assert_eq!(nav.jump_list[1], Screen::MrDetail(EntityKey::mr(1, 99)));
+    }
+
+    #[test]
+    fn test_reset_clears_all_history() {
+        let mut nav = NavigationStack::new();
+        nav.push(Screen::IssueList);
+        nav.push(Screen::Search);
+        nav.push(Screen::IssueDetail(EntityKey::issue(1, 1)));
+
+        nav.reset_to(Screen::Dashboard);
+
+        assert!(nav.is_at(&Screen::Dashboard));
+        assert_eq!(nav.depth(), 1);
+        assert!(!nav.can_go_back());
+        assert!(!nav.can_go_forward());
+        assert!(nav.jump_list.is_empty());
+    }
+
+    #[test]
+    fn test_breadcrumbs_reflect_stack() {
+        let mut nav = NavigationStack::new();
+        assert_eq!(nav.breadcrumbs(), vec!["Dashboard"]);
+
+        nav.push(Screen::IssueList);
+        assert_eq!(nav.breadcrumbs(), vec!["Dashboard", "Issues"]);
+
+        nav.push(Screen::IssueDetail(EntityKey::issue(1, 42)));
+        assert_eq!(nav.breadcrumbs(), vec!["Dashboard", "Issues", "Issue"]);
+    }
+
+    #[test]
+    fn test_default_is_new() {
+        let nav = NavigationStack::default();
+        assert!(nav.is_at(&Screen::Dashboard));
+        assert_eq!(nav.depth(), 1);
+    }
+
+    #[test]
+    fn test_can_go_back_and_forward() {
+        let mut nav = NavigationStack::new();
+        assert!(!nav.can_go_back());
+        assert!(!nav.can_go_forward());
+
+        nav.push(Screen::IssueList);
+        assert!(nav.can_go_back());
+        assert!(!nav.can_go_forward());
+
+        nav.pop();
+        assert!(!nav.can_go_back());
+        assert!(nav.can_go_forward());
+    }
+}

crates/lore-tui/src/safety.rs

@@ -0,0 +1,587 @@
+//! Terminal safety: sanitize untrusted text, URL policy, credential redaction.
+//!
+//! GitLab content can contain ANSI escapes, bidi overrides, OSC hyperlinks,
+//! and C1 control codes that could corrupt terminal rendering. This module
+//! strips dangerous sequences while preserving a safe SGR subset for readability.
+
+use std::fmt::Write;
+
+// ---------------------------------------------------------------------------
+// UrlPolicy
+// ---------------------------------------------------------------------------
+
+/// Controls how OSC 8 hyperlinks in input are handled.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum UrlPolicy {
+    /// Remove OSC 8 hyperlinks entirely, keeping only the link text.
+    #[default]
+    Strip,
+    /// Convert hyperlinks to numbered footnotes: `text [1]` with URL list appended.
+    Footnote,
+    /// Pass hyperlinks through unchanged (only for trusted content).
+    Passthrough,
+}
+
+// ---------------------------------------------------------------------------
+// RedactPattern
+// ---------------------------------------------------------------------------
+
+/// Common patterns for PII/secret redaction.
+#[derive(Debug, Clone)]
+pub struct RedactPattern {
+    patterns: Vec<regex::Regex>,
+}
+
+impl RedactPattern {
+    /// Create a default set of redaction patterns (tokens, emails, etc.).
+    #[must_use]
+    pub fn defaults() -> Self {
+        let patterns = vec![
+            // GitLab personal access tokens
+            regex::Regex::new(r"glpat-[A-Za-z0-9_\-]{20,}").expect("valid regex"),
+            // Generic bearer/API tokens (long hex or base64-ish strings after common prefixes)
+            regex::Regex::new(r"(?i)(token|bearer|api[_-]?key)[\s:=]+\S{8,}").expect("valid regex"),
+            // Email addresses
+            regex::Regex::new(r"[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}")
+                .expect("valid regex"),
+        ];
+        Self { patterns }
+    }
+
+    /// Apply all redaction patterns to the input string.
+    #[must_use]
+    pub fn redact(&self, input: &str) -> String {
+        let mut result = input.to_string();
+        for pattern in &self.patterns {
+            result = pattern.replace_all(&result, "[REDACTED]").into_owned();
+        }
+        result
+    }
+}
+
+// ---------------------------------------------------------------------------
+// sanitize_for_terminal
+// ---------------------------------------------------------------------------
+
+/// Sanitize untrusted text for safe terminal display.
+///
+/// - Strips C1 control codes (0x80-0x9F)
+/// - Strips OSC sequences (ESC ] ... ST)
+/// - Strips cursor movement CSI sequences (CSI n A/B/C/D/E/F/G/H/J/K)
+/// - Strips bidi overrides (U+202A-U+202E, U+2066-U+2069)
+/// - Preserves safe SGR subset (bold, italic, underline, reset, standard colors)
+///
+/// `url_policy` controls handling of OSC 8 hyperlinks.
+#[must_use]
+pub fn sanitize_for_terminal(input: &str, url_policy: UrlPolicy) -> String {
+    let mut output = String::with_capacity(input.len());
+    let mut footnotes: Vec<String> = Vec::new();
+    let chars: Vec<char> = input.chars().collect();
+    let len = chars.len();
+    let mut i = 0;
+
+    while i < len {
+        let ch = chars[i];
+
+        // --- Bidi overrides ---
+        if is_bidi_override(ch) {
+            i += 1;
+            continue;
+        }
+
+        // --- C1 control codes (U+0080-U+009F) ---
+        if ('\u{0080}'..='\u{009F}').contains(&ch) {
+            i += 1;
+            continue;
+        }
+
+        // --- C0 control codes except tab, newline, carriage return ---
+        if ch.is_ascii_control() && ch != '\t' && ch != '\n' && ch != '\r' && ch != '\x1B' {
+            i += 1;
+            continue;
+        }
+
+        // --- ESC sequences ---
+        if ch == '\x1B' {
+            if i + 1 < len {
+                match chars[i + 1] {
+                    // CSI sequence: ESC [
+                    '[' => {
+                        let (consumed, safe_seq) = parse_csi(&chars, i);
+                        if let Some(seq) = safe_seq {
+                            output.push_str(&seq);
+                        }
+                        i += consumed;
+                        continue;
+                    }
+                    // OSC sequence: ESC ]
+                    ']' => {
+                        let (consumed, link_text, link_url) = parse_osc(&chars, i);
+                        match url_policy {
+                            UrlPolicy::Strip => {
+                                if let Some(text) = link_text {
+                                    output.push_str(&text);
+                                }
+                            }
+                            UrlPolicy::Footnote => {
+                                if let (Some(text), Some(url)) = (link_text, link_url) {
+                                    footnotes.push(url);
+                                    let _ = write!(output, "{text} [{n}]", n = footnotes.len());
+                                }
+                            }
+                            UrlPolicy::Passthrough => {
+                                // Reproduce the raw OSC sequence
+                                for &ch_raw in &chars[i..len.min(i + consumed)] {
+                                    output.push(ch_raw);
+                                }
+                            }
+                        }
+                        i += consumed;
+                        continue;
+                    }
+                    _ => {
+                        // Unknown ESC sequence — skip ESC + next char
+                        i += 2;
+                        continue;
+                    }
+                }
+            } else {
+                // Trailing ESC at end of input
+                i += 1;
+                continue;
+            }
+        }
+
+        // --- Normal character ---
+        output.push(ch);
+        i += 1;
+    }
+
+    // Append footnotes if any
+    if !footnotes.is_empty() {
+        output.push('\n');
+        for (idx, url) in footnotes.iter().enumerate() {
+            let _ = write!(output, "\n[{}] {url}", idx + 1);
+        }
+    }
+
+    output
+}
+
+// ---------------------------------------------------------------------------
+// Bidi check
+// ---------------------------------------------------------------------------
+
+fn is_bidi_override(ch: char) -> bool {
+    matches!(
+        ch,
+        '\u{202A}' // LRE
+        | '\u{202B}' // RLE
+        | '\u{202C}' // PDF
+        | '\u{202D}' // LRO
+        | '\u{202E}' // RLO
+        | '\u{2066}' // LRI
+        | '\u{2067}' // RLI
+        | '\u{2068}' // FSI
+        | '\u{2069}' // PDI
+    )
+}
+
+// ---------------------------------------------------------------------------
+// CSI parser
+// ---------------------------------------------------------------------------
+
+/// Parse a CSI sequence starting at `chars[start]` (which should be ESC).
+///
+/// Returns `(chars_consumed, Option<safe_sequence_string>)`.
+/// If the CSI is a safe SGR, returns the full sequence string to preserve.
+/// Otherwise returns None (strip it).
+fn parse_csi(chars: &[char], start: usize) -> (usize, Option<String>) {
+    // Minimum: ESC [ <final_byte>
+    debug_assert!(chars[start] == '\x1B');
+    debug_assert!(start + 1 < chars.len() && chars[start + 1] == '[');
+
+    let mut i = start + 2; // skip ESC [
+    let len = chars.len();
+
+    // Collect parameter bytes (0x30-0x3F) and intermediate bytes (0x20-0x2F)
+    let param_start = i;
+    while i < len && (chars[i] as u32) >= 0x20 && (chars[i] as u32) <= 0x3F {
+        i += 1;
+    }
+
+    // Collect intermediate bytes
+    while i < len && (chars[i] as u32) >= 0x20 && (chars[i] as u32) <= 0x2F {
+        i += 1;
+    }
+
+    // Final byte (0x40-0x7E)
+    if i >= len || (chars[i] as u32) < 0x40 || (chars[i] as u32) > 0x7E {
+        // Malformed — consume what we've seen and strip
+        return (i.saturating_sub(start).max(2), None);
+    }
+
+    let final_byte = chars[i];
+    let consumed = i + 1 - start;
+
+    // Only preserve SGR sequences (final byte 'm')
+    if final_byte == 'm' {
+        let param_str: String = chars[param_start..i].iter().collect();
+        if is_safe_sgr(&param_str) {
+            let full_seq: String = chars[start..start + consumed].iter().collect();
+            return (consumed, Some(full_seq));
+        }
+    }
+
+    // Anything else (cursor movement A-H, erase J/K, etc.) is stripped
+    (consumed, None)
+}
+
+/// Check if all SGR parameters in a sequence are in the safe subset.
+///
+/// Safe: 0 (reset), 1 (bold), 3 (italic), 4 (underline), 22 (normal intensity),
+/// 23 (not italic), 24 (not underline), 39 (default fg), 49 (default bg),
+/// 30-37 (standard fg), 40-47 (standard bg), 90-97 (bright fg), 100-107 (bright bg).
+fn is_safe_sgr(params: &str) -> bool {
+    if params.is_empty() {
+        return true; // ESC[m is reset
+    }
+
+    for param in params.split(';') {
+        let param = param.trim();
+        if param.is_empty() {
+            continue; // treat empty as 0
+        }
+        let Ok(n) = param.parse::<u32>() else {
+            return false;
+        };
+        if !is_safe_sgr_code(n) {
+            return false;
+        }
+    }
+    true
+}
+
+fn is_safe_sgr_code(n: u32) -> bool {
+    matches!(
+        n,
+        0  // reset
+        | 1  // bold
+        | 3  // italic
+        | 4  // underline
+        | 22 // normal intensity (turn off bold)
+        | 23 // not italic
+        | 24 // not underline
+        | 39 // default foreground
+        | 49 // default background
+        | 30..=37   // standard foreground colors
+        | 40..=47   // standard background colors
+        | 90..=97   // bright foreground colors
+        | 100..=107 // bright background colors
+    )
+}
+
+// ---------------------------------------------------------------------------
+// OSC parser
+// ---------------------------------------------------------------------------
+
+/// Parse an OSC sequence starting at `chars[start]` (ESC ]).
+///
+/// Returns `(chars_consumed, link_text, link_url)`.
+/// For OSC 8 hyperlinks: `ESC ] 8 ; params ; url ST text ESC ] 8 ; ; ST`
+/// For other OSC: consumed without extracting link data.
+fn parse_osc(chars: &[char], start: usize) -> (usize, Option<String>, Option<String>) {
+    debug_assert!(chars[start] == '\x1B');
+    debug_assert!(start + 1 < chars.len() && chars[start + 1] == ']');
+
+    let len = chars.len();
+    let i = start + 2; // skip ESC ]
+
+    // Find ST (String Terminator): ESC \ or BEL (0x07)
+    let osc_end = find_st(chars, i);
+
+    // Check if this is OSC 8 (hyperlink)
+    if i < len && chars[i] == '8' && i + 1 < len && chars[i + 1] == ';' {
+        // OSC 8 hyperlink: ESC ] 8 ; params ; url ST ... ESC ] 8 ; ; ST
+        let osc_content: String = chars[i..osc_end.0].iter().collect();
+        let first_consumed = osc_end.1;
+
+        // Extract URL from "8;params;url"
+        let url = extract_osc8_url(&osc_content);
+
+        // Now find the link text (between first ST and second OSC 8)
+        let after_first_st = start + 2 + first_consumed;
+        let mut text = String::new();
+        let mut j = after_first_st;
+
+        // Collect text until we hit the closing OSC 8 or end of input
+        while j < len {
+            if j + 1 < len && chars[j] == '\x1B' && chars[j + 1] == ']' {
+                // Found another OSC — this should be the closing OSC 8
+                let close_end = find_st(chars, j + 2);
+                return (
+                    j + close_end.1 - start + 2,
+                    Some(text),
+                    url.map(String::from),
+                );
+            }
+            text.push(chars[j]);
+            j += 1;
+        }
+
+        // Reached end without closing OSC 8
+        return (j - start, Some(text), url.map(String::from));
+    }
+
+    // Non-OSC-8: just consume and strip
+    (osc_end.1 + (start + 2 - start), None, None)
+}
+
+/// Find the String Terminator (ST) for an OSC sequence.
+/// ST is either ESC \ (two chars) or BEL (0x07).
+/// Returns (content_end_index, total_consumed_from_content_start).
+fn find_st(chars: &[char], from: usize) -> (usize, usize) {
+    let len = chars.len();
+    let mut i = from;
+    while i < len {
+        if chars[i] == '\x07' {
+            return (i, i - from + 1);
+        }
+        if i + 1 < len && chars[i] == '\x1B' && chars[i + 1] == '\\' {
+            return (i, i - from + 2);
+        }
+        i += 1;
+    }
+    // Unterminated — consume everything
+    (len, len - from)
+}
+
+/// Extract URL from OSC 8 content "8;params;url".
+fn extract_osc8_url(content: &str) -> Option<&str> {
+    // Format: "8;params;url"
+    let rest = content.strip_prefix("8;")?;
+    // Skip params (up to next ;)
+    let url_start = rest.find(';')? + 1;
+    let url = &rest[url_start..];
+    if url.is_empty() { None } else { Some(url) }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // --- CSI / cursor movement ---
+
+    #[test]
+    fn test_strips_cursor_movement() {
+        // CSI 5A = cursor up 5
+        let input = "before\x1B[5Aafter";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, "beforeafter");
+    }
+
+    #[test]
+    fn test_strips_cursor_movement_all_directions() {
+        for dir in ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'] {
+            let input = format!("x\x1B[3{dir}y");
+            let result = sanitize_for_terminal(&input, UrlPolicy::Strip);
+            assert_eq!(result, "xy", "failed for direction {dir}");
+        }
+    }
+
+    #[test]
+    fn test_strips_erase_sequences() {
+        // CSI 2J = erase display
+        let input = "before\x1B[2Jafter";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, "beforeafter");
+    }
+
+    // --- SGR preservation ---
+
+    #[test]
+    fn test_preserves_bold_italic_underline_reset() {
+        let input = "\x1B[1mbold\x1B[0m \x1B[3mitalic\x1B[0m \x1B[4munderline\x1B[0m";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, input);
+    }
+
+    #[test]
+    fn test_preserves_standard_colors() {
+        // Red foreground, green background
+        let input = "\x1B[31mred\x1B[42m on green\x1B[0m";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, input);
+    }
+
+    #[test]
+    fn test_preserves_bright_colors() {
+        let input = "\x1B[91mbright red\x1B[0m";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, input);
+    }
+
+    #[test]
+    fn test_preserves_combined_safe_sgr() {
+        // Bold + red foreground in one sequence
+        let input = "\x1B[1;31mbold red\x1B[0m";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, input);
+    }
+
+    #[test]
+    fn test_strips_unsafe_sgr() {
+        // SGR 8 = hidden text (not in safe list)
+        let input = "\x1B[8mhidden\x1B[0m";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        // SGR 8 stripped, SGR 0 preserved
+        assert_eq!(result, "hidden\x1B[0m");
+    }
+
+    // --- C1 control codes ---
+
+    #[test]
+    fn test_strips_c1_control_codes() {
+        // U+008D = Reverse Index, U+009B = CSI (8-bit)
+        let input = format!("before{}middle{}after", '\u{008D}', '\u{009B}');
+        let result = sanitize_for_terminal(&input, UrlPolicy::Strip);
+        assert_eq!(result, "beforemiddleafter");
+    }
+
+    // --- Bidi overrides ---
+
+    #[test]
+    fn test_strips_bidi_overrides() {
+        let input = format!(
+            "normal{}reversed{}end",
+            '\u{202E}', // RLO
+            '\u{202C}'  // PDF
+        );
+        let result = sanitize_for_terminal(&input, UrlPolicy::Strip);
+        assert_eq!(result, "normalreversedend");
+    }
+
+    #[test]
+    fn test_strips_all_bidi_chars() {
+        let bidi_chars = [
+            '\u{202A}', '\u{202B}', '\u{202C}', '\u{202D}', '\u{202E}', '\u{2066}', '\u{2067}',
+            '\u{2068}', '\u{2069}',
+        ];
+        for ch in bidi_chars {
+            let input = format!("a{ch}b");
+            let result = sanitize_for_terminal(&input, UrlPolicy::Strip);
+            assert_eq!(result, "ab", "failed for U+{:04X}", ch as u32);
+        }
+    }
+
+    // --- OSC sequences ---
+
+    #[test]
+    fn test_strips_osc_sequences() {
+        // OSC 0 (set title): ESC ] 0 ; title BEL
+        let input = "before\x1B]0;My Title\x07after";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, "beforeafter");
+    }
+
+    // --- OSC 8 hyperlinks ---
+
+    #[test]
+    fn test_url_policy_strip() {
+        // OSC 8 hyperlink: ESC]8;;url ST text ESC]8;; ST
+        let input = "click \x1B]8;;https://example.com\x07here\x1B]8;;\x07 done";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, "click here done");
+    }
+
+    #[test]
+    fn test_url_policy_footnote() {
+        let input = "click \x1B]8;;https://example.com\x07here\x1B]8;;\x07 done";
+        let result = sanitize_for_terminal(input, UrlPolicy::Footnote);
+        assert!(result.contains("here [1]"));
+        assert!(result.contains("[1] https://example.com"));
+    }
+
+    // --- Redaction ---
+
+    #[test]
+    fn test_redact_gitlab_token() {
+        let redactor = RedactPattern::defaults();
+        let input = "My token is glpat-AbCdEfGhIjKlMnOpQrStUvWx";
+        let result = redactor.redact(input);
+        assert_eq!(result, "My token is [REDACTED]");
+    }
+
+    #[test]
+    fn test_redact_email() {
+        let redactor = RedactPattern::defaults();
+        let input = "Contact user@example.com for details";
+        let result = redactor.redact(input);
+        assert_eq!(result, "Contact [REDACTED] for details");
+    }
+
+    #[test]
+    fn test_redact_bearer_token() {
+        let redactor = RedactPattern::defaults();
+        let input = "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI";
+        let result = redactor.redact(input);
+        assert!(result.contains("[REDACTED]"));
+        assert!(!result.contains("eyJ"));
+    }
+
+    // --- Edge cases ---
+
+    #[test]
+    fn test_empty_input() {
+        assert_eq!(sanitize_for_terminal("", UrlPolicy::Strip), "");
+    }
+
+    #[test]
+    fn test_safe_content_passthrough() {
+        let input = "Hello, world! This is normal text.\nWith newlines\tand tabs.";
+        assert_eq!(sanitize_for_terminal(input, UrlPolicy::Strip), input);
+    }
+
+    #[test]
+    fn test_trailing_esc() {
+        let input = "text\x1B";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, "text");
+    }
+
+    #[test]
+    fn test_malformed_csi_does_not_eat_text() {
+        // ESC [ without a valid final byte before next printable
+        let input = "a\x1B[b";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        // The malformed CSI is consumed but shouldn't eat "b" as text
+        // ESC[ is start, 'b' is final byte (0x62 is in 0x40-0x7E range)
+        // So this is CSI with final byte 'b' (cursor back) — gets stripped
+        assert_eq!(result, "a");
+    }
+
+    #[test]
+    fn test_utf8_adjacent_to_escapes() {
+        let input = "\x1B[1m日本語\x1B[0m text";
+        let result = sanitize_for_terminal(input, UrlPolicy::Strip);
+        assert_eq!(result, "\x1B[1m日本語\x1B[0m text");
+    }
+
+    #[test]
+    fn test_fuzz_no_panic() {
+        // 1000 random-ish byte sequences — must not panic
+        for seed in 0u16..1000 {
+            let mut bytes = Vec::new();
+            for j in 0..50 {
+                bytes.push(((seed.wrapping_mul(31).wrapping_add(j)) & 0xFF) as u8);
+            }
+            // Best-effort UTF-8
+            let input = String::from_utf8_lossy(&bytes);
+            let _ = sanitize_for_terminal(&input, UrlPolicy::Strip);
+        }
+    }
+}

crates/lore-tui/src/state/command_palette.rs

@@ -0,0 +1,11 @@
+#![allow(dead_code)]
+
+//! Command palette state.
+
+/// State for the command palette overlay.
+#[derive(Debug, Default)]
+pub struct CommandPaletteState {
+    pub query: String,
+    pub query_focused: bool,
+    pub selected_index: usize,
+}

crates/lore-tui/src/state/dashboard.rs

@@ -0,0 +1,255 @@
+#![allow(dead_code)]
+
+//! Dashboard screen state.
+//!
+//! The dashboard is the home screen — entity counts, per-project sync
+//! status, recent activity, and the last sync summary.
+
+// ---------------------------------------------------------------------------
+// EntityCounts
+// ---------------------------------------------------------------------------
+
+/// Aggregated entity counts from the local database.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct EntityCounts {
+    pub issues_open: u64,
+    pub issues_total: u64,
+    pub mrs_open: u64,
+    pub mrs_total: u64,
+    pub discussions: u64,
+    pub notes_total: u64,
+    /// Percentage of notes that are system-generated (0-100).
+    pub notes_system_pct: u8,
+    pub documents: u64,
+    pub embeddings: u64,
+}
+
+// ---------------------------------------------------------------------------
+// ProjectSyncInfo
+// ---------------------------------------------------------------------------
+
+/// Per-project sync freshness.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProjectSyncInfo {
+    pub path: String,
+    pub minutes_since_sync: u64,
+}
+
+// ---------------------------------------------------------------------------
+// RecentActivityItem
+// ---------------------------------------------------------------------------
+
+/// A recently-updated entity for the activity feed.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RecentActivityItem {
+    /// "issue" or "mr".
+    pub entity_type: String,
+    pub iid: u64,
+    pub title: String,
+    pub state: String,
+    pub minutes_ago: u64,
+}
+
+// ---------------------------------------------------------------------------
+// LastSyncInfo
+// ---------------------------------------------------------------------------
+
+/// Summary of the most recent sync run.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LastSyncInfo {
+    pub status: String,
+    /// Milliseconds epoch UTC.
+    pub finished_at: Option<i64>,
+    pub command: String,
+    pub error: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// DashboardData
+// ---------------------------------------------------------------------------
+
+/// Data returned by the `fetch_dashboard` action.
+///
+/// Pure data transfer — no rendering or display logic.
+#[derive(Debug, Clone, Default)]
+pub struct DashboardData {
+    pub counts: EntityCounts,
+    pub projects: Vec<ProjectSyncInfo>,
+    pub recent: Vec<RecentActivityItem>,
+    pub last_sync: Option<LastSyncInfo>,
+}
+
+// ---------------------------------------------------------------------------
+// DashboardState
+// ---------------------------------------------------------------------------
+
+/// State for the dashboard summary screen.
+#[derive(Debug, Default)]
+pub struct DashboardState {
+    pub counts: EntityCounts,
+    pub projects: Vec<ProjectSyncInfo>,
+    pub recent: Vec<RecentActivityItem>,
+    pub last_sync: Option<LastSyncInfo>,
+    /// Scroll offset for the recent activity list.
+    pub scroll_offset: usize,
+}
+
+impl DashboardState {
+    /// Apply fresh data from a `fetch_dashboard` result.
+    ///
+    /// Preserves scroll offset (clamped to new data bounds).
+    pub fn update(&mut self, data: DashboardData) {
+        self.counts = data.counts;
+        self.projects = data.projects;
+        self.last_sync = data.last_sync;
+        self.recent = data.recent;
+        // Clamp scroll offset if the list shrunk.
+        if !self.recent.is_empty() {
+            self.scroll_offset = self.scroll_offset.min(self.recent.len() - 1);
+        } else {
+            self.scroll_offset = 0;
+        }
+    }
+
+    /// Scroll the recent activity list down by one.
+    pub fn scroll_down(&mut self) {
+        if !self.recent.is_empty() {
+            self.scroll_offset = (self.scroll_offset + 1).min(self.recent.len() - 1);
+        }
+    }
+
+    /// Scroll the recent activity list up by one.
+    pub fn scroll_up(&mut self) {
+        self.scroll_offset = self.scroll_offset.saturating_sub(1);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_dashboard_state_default() {
+        let state = DashboardState::default();
+        assert_eq!(state.counts.issues_total, 0);
+        assert_eq!(state.scroll_offset, 0);
+        assert!(state.recent.is_empty());
+    }
+
+    #[test]
+    fn test_dashboard_state_update_applies_data() {
+        let mut state = DashboardState::default();
+        let data = DashboardData {
+            counts: EntityCounts {
+                issues_open: 3,
+                issues_total: 5,
+                ..Default::default()
+            },
+            projects: vec![ProjectSyncInfo {
+                path: "group/project".into(),
+                minutes_since_sync: 42,
+            }],
+            recent: vec![RecentActivityItem {
+                entity_type: "issue".into(),
+                iid: 1,
+                title: "Fix bug".into(),
+                state: "opened".into(),
+                minutes_ago: 10,
+            }],
+            last_sync: None,
+        };
+
+        state.update(data);
+        assert_eq!(state.counts.issues_open, 3);
+        assert_eq!(state.counts.issues_total, 5);
+        assert_eq!(state.projects.len(), 1);
+        assert_eq!(state.recent.len(), 1);
+    }
+
+    #[test]
+    fn test_dashboard_state_update_clamps_scroll() {
+        let mut state = DashboardState {
+            scroll_offset: 10,
+            ..Default::default()
+        };
+
+        let data = DashboardData {
+            recent: vec![RecentActivityItem {
+                entity_type: "issue".into(),
+                iid: 1,
+                title: "Only item".into(),
+                state: "opened".into(),
+                minutes_ago: 5,
+            }],
+            ..Default::default()
+        };
+
+        state.update(data);
+        assert_eq!(state.scroll_offset, 0); // Clamped to len-1 = 0
+    }
+
+    #[test]
+    fn test_dashboard_state_update_empty_resets_scroll() {
+        let mut state = DashboardState {
+            scroll_offset: 5,
+            ..Default::default()
+        };
+
+        state.update(DashboardData::default());
+        assert_eq!(state.scroll_offset, 0);
+    }
+
+    #[test]
+    fn test_scroll_down_and_up() {
+        let mut state = DashboardState::default();
+        state.recent = (0..5)
+            .map(|i| RecentActivityItem {
+                entity_type: "issue".into(),
+                iid: i,
+                title: format!("Item {i}"),
+                state: "opened".into(),
+                minutes_ago: i,
+            })
+            .collect();
+
+        assert_eq!(state.scroll_offset, 0);
+        state.scroll_down();
+        assert_eq!(state.scroll_offset, 1);
+        state.scroll_down();
+        assert_eq!(state.scroll_offset, 2);
+        state.scroll_up();
+        assert_eq!(state.scroll_offset, 1);
+        state.scroll_up();
+        assert_eq!(state.scroll_offset, 0);
+        state.scroll_up(); // Can't go below 0
+        assert_eq!(state.scroll_offset, 0);
+    }
+
+    #[test]
+    fn test_scroll_down_stops_at_end() {
+        let mut state = DashboardState::default();
+        state.recent = vec![RecentActivityItem {
+            entity_type: "mr".into(),
+            iid: 1,
+            title: "Only".into(),
+            state: "merged".into(),
+            minutes_ago: 0,
+        }];
+
+        state.scroll_down();
+        assert_eq!(state.scroll_offset, 0); // Can't scroll past single item
+    }
+
+    #[test]
+    fn test_scroll_on_empty_is_noop() {
+        let mut state = DashboardState::default();
+        state.scroll_down();
+        assert_eq!(state.scroll_offset, 0);
+        state.scroll_up();
+        assert_eq!(state.scroll_offset, 0);
+    }
+}

crates/lore-tui/src/state/issue_detail.rs

@@ -0,0 +1,14 @@
+#![allow(dead_code)]
+
+//! Issue detail screen state.
+
+use crate::message::{Discussion, EntityKey, IssueDetail};
+
+/// State for the issue detail screen.
+#[derive(Debug, Default)]
+pub struct IssueDetailState {
+    pub key: Option<EntityKey>,
+    pub detail: Option<IssueDetail>,
+    pub discussions: Vec<Discussion>,
+    pub scroll_offset: u16,
+}

crates/lore-tui/src/state/issue_list.rs

@@ -0,0 +1,376 @@
+#![allow(dead_code)] // Phase 2: consumed by LoreApp and view/issue_list
+
+//! Issue list screen state.
+//!
+//! Uses keyset pagination with a snapshot fence for stable ordering
+//! under concurrent sync writes. Filter changes reset the pagination
+//! cursor and snapshot fence.
+
+use std::hash::{Hash, Hasher};
+
+// ---------------------------------------------------------------------------
+// Cursor (keyset pagination boundary)
+// ---------------------------------------------------------------------------
+
+/// Keyset pagination cursor — (updated_at, iid) boundary.
+///
+/// The next page query uses `WHERE (updated_at, iid) < (cursor.updated_at, cursor.iid)`
+/// to avoid OFFSET instability.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct IssueCursor {
+    pub updated_at: i64,
+    pub iid: i64,
+}
+
+// ---------------------------------------------------------------------------
+// Filter
+// ---------------------------------------------------------------------------
+
+/// Structured filter for issue list queries.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct IssueFilter {
+    pub state: Option<String>,
+    pub author: Option<String>,
+    pub assignee: Option<String>,
+    pub label: Option<String>,
+    pub milestone: Option<String>,
+    pub status: Option<String>,
+    pub free_text: Option<String>,
+    pub project_id: Option<i64>,
+}
+
+impl IssueFilter {
+    /// Compute a hash for change detection.
+    pub fn hash_value(&self) -> u64 {
+        let mut hasher = std::collections::hash_map::DefaultHasher::new();
+        self.state.hash(&mut hasher);
+        self.author.hash(&mut hasher);
+        self.assignee.hash(&mut hasher);
+        self.label.hash(&mut hasher);
+        self.milestone.hash(&mut hasher);
+        self.status.hash(&mut hasher);
+        self.free_text.hash(&mut hasher);
+        self.project_id.hash(&mut hasher);
+        hasher.finish()
+    }
+
+    /// Whether any filter is active.
+    pub fn is_active(&self) -> bool {
+        self.state.is_some()
+            || self.author.is_some()
+            || self.assignee.is_some()
+            || self.label.is_some()
+            || self.milestone.is_some()
+            || self.status.is_some()
+            || self.free_text.is_some()
+            || self.project_id.is_some()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Row
+// ---------------------------------------------------------------------------
+
+/// A single row in the issue list.
+#[derive(Debug, Clone)]
+pub struct IssueListRow {
+    pub project_path: String,
+    pub iid: i64,
+    pub title: String,
+    pub state: String,
+    pub author: String,
+    pub labels: Vec<String>,
+    pub updated_at: i64,
+}
+
+// ---------------------------------------------------------------------------
+// Page result
+// ---------------------------------------------------------------------------
+
+/// Result from a paginated issue list query.
+#[derive(Debug, Clone)]
+pub struct IssueListPage {
+    pub rows: Vec<IssueListRow>,
+    pub next_cursor: Option<IssueCursor>,
+    pub total_count: u64,
+}
+
+// ---------------------------------------------------------------------------
+// Sort
+// ---------------------------------------------------------------------------
+
+/// Fields available for sorting.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum SortField {
+    #[default]
+    UpdatedAt,
+    Iid,
+    Title,
+    State,
+    Author,
+}
+
+/// Sort direction.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum SortOrder {
+    #[default]
+    Desc,
+    Asc,
+}
+
+// ---------------------------------------------------------------------------
+// IssueListState
+// ---------------------------------------------------------------------------
+
+/// State for the issue list screen.
+#[derive(Debug, Default)]
+pub struct IssueListState {
+    /// Current page of issue rows.
+    pub rows: Vec<IssueListRow>,
+    /// Total count of matching issues.
+    pub total_count: u64,
+    /// Selected row index (within current window).
+    pub selected_index: usize,
+    /// Scroll offset for the entity table.
+    pub scroll_offset: usize,
+    /// Cursor for the next page.
+    pub next_cursor: Option<IssueCursor>,
+    /// Whether a prefetch is in flight.
+    pub prefetch_in_flight: bool,
+    /// Current filter.
+    pub filter: IssueFilter,
+    /// Raw filter input text.
+    pub filter_input: String,
+    /// Whether the filter bar has focus.
+    pub filter_focused: bool,
+    /// Sort field.
+    pub sort_field: SortField,
+    /// Sort direction.
+    pub sort_order: SortOrder,
+    /// Snapshot fence: max updated_at from initial load.
+    pub snapshot_fence: Option<i64>,
+    /// Hash of the current filter for change detection.
+    pub filter_hash: u64,
+    /// Whether Quick Peek is visible.
+    pub peek_visible: bool,
+}
+
+impl IssueListState {
+    /// Reset pagination state (called when filter changes or on refresh).
+    pub fn reset_pagination(&mut self) {
+        self.rows.clear();
+        self.next_cursor = None;
+        self.selected_index = 0;
+        self.scroll_offset = 0;
+        self.snapshot_fence = None;
+        self.total_count = 0;
+        self.prefetch_in_flight = false;
+    }
+
+    /// Apply a new page of results.
+    pub fn apply_page(&mut self, page: IssueListPage) {
+        // Set snapshot fence on first page load.
+        if self.snapshot_fence.is_none() {
+            self.snapshot_fence = page.rows.first().map(|r| r.updated_at);
+        }
+        self.rows.extend(page.rows);
+        self.next_cursor = page.next_cursor;
+        self.total_count = page.total_count;
+        self.prefetch_in_flight = false;
+    }
+
+    /// Check if filter changed and reset if needed.
+    pub fn check_filter_change(&mut self) -> bool {
+        let new_hash = self.filter.hash_value();
+        if new_hash != self.filter_hash {
+            self.filter_hash = new_hash;
+            self.reset_pagination();
+            true
+        } else {
+            false
+        }
+    }
+
+    /// Whether the user has scrolled near the end of current data (80% threshold).
+    pub fn should_prefetch(&self) -> bool {
+        if self.prefetch_in_flight || self.next_cursor.is_none() {
+            return false;
+        }
+        if self.rows.is_empty() {
+            return false;
+        }
+        let threshold = (self.rows.len() * 4) / 5; // 80%
+        self.selected_index >= threshold
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample_page(count: usize, has_next: bool) -> IssueListPage {
+        let rows: Vec<IssueListRow> = (0..count)
+            .map(|i| IssueListRow {
+                project_path: "group/project".into(),
+                iid: (count - i) as i64,
+                title: format!("Issue {}", count - i),
+                state: "opened".into(),
+                author: "taylor".into(),
+                labels: vec![],
+                updated_at: 1_700_000_000_000 - (i as i64 * 60_000),
+            })
+            .collect();
+
+        let next_cursor = if has_next {
+            rows.last().map(|r| IssueCursor {
+                updated_at: r.updated_at,
+                iid: r.iid,
+            })
+        } else {
+            None
+        };
+
+        IssueListPage {
+            rows,
+            next_cursor,
+            total_count: if has_next {
+                (count * 2) as u64
+            } else {
+                count as u64
+            },
+        }
+    }
+
+    #[test]
+    fn test_apply_page_sets_snapshot_fence() {
+        let mut state = IssueListState::default();
+        let page = sample_page(5, false);
+        state.apply_page(page);
+
+        assert_eq!(state.rows.len(), 5);
+        assert!(state.snapshot_fence.is_some());
+        assert_eq!(state.snapshot_fence.unwrap(), 1_700_000_000_000);
+    }
+
+    #[test]
+    fn test_apply_page_appends() {
+        let mut state = IssueListState::default();
+        state.apply_page(sample_page(5, true));
+        assert_eq!(state.rows.len(), 5);
+
+        state.apply_page(sample_page(3, false));
+        assert_eq!(state.rows.len(), 8);
+    }
+
+    #[test]
+    fn test_reset_pagination_clears_state() {
+        let mut state = IssueListState::default();
+        state.apply_page(sample_page(5, true));
+        state.selected_index = 3;
+
+        state.reset_pagination();
+
+        assert!(state.rows.is_empty());
+        assert_eq!(state.selected_index, 0);
+        assert!(state.next_cursor.is_none());
+        assert!(state.snapshot_fence.is_none());
+    }
+
+    #[test]
+    fn test_check_filter_change_detects_change() {
+        let mut state = IssueListState::default();
+        state.filter_hash = state.filter.hash_value();
+
+        state.filter.state = Some("opened".into());
+        assert!(state.check_filter_change());
+    }
+
+    #[test]
+    fn test_check_filter_change_no_change() {
+        let mut state = IssueListState::default();
+        state.filter_hash = state.filter.hash_value();
+        assert!(!state.check_filter_change());
+    }
+
+    #[test]
+    fn test_should_prefetch() {
+        let mut state = IssueListState::default();
+        state.apply_page(sample_page(10, true));
+
+        state.selected_index = 4; // 40% — no prefetch
+        assert!(!state.should_prefetch());
+
+        state.selected_index = 8; // 80% — prefetch
+        assert!(state.should_prefetch());
+    }
+
+    #[test]
+    fn test_should_prefetch_no_next_page() {
+        let mut state = IssueListState::default();
+        state.apply_page(sample_page(10, false));
+        state.selected_index = 9;
+        assert!(!state.should_prefetch());
+    }
+
+    #[test]
+    fn test_should_prefetch_already_in_flight() {
+        let mut state = IssueListState::default();
+        state.apply_page(sample_page(10, true));
+        state.selected_index = 9;
+        state.prefetch_in_flight = true;
+        assert!(!state.should_prefetch());
+    }
+
+    #[test]
+    fn test_issue_filter_is_active() {
+        let empty = IssueFilter::default();
+        assert!(!empty.is_active());
+
+        let active = IssueFilter {
+            state: Some("opened".into()),
+            ..Default::default()
+        };
+        assert!(active.is_active());
+    }
+
+    #[test]
+    fn test_issue_filter_hash_deterministic() {
+        let f1 = IssueFilter {
+            state: Some("opened".into()),
+            author: Some("taylor".into()),
+            ..Default::default()
+        };
+        let f2 = f1.clone();
+        assert_eq!(f1.hash_value(), f2.hash_value());
+    }
+
+    #[test]
+    fn test_issue_filter_hash_differs() {
+        let f1 = IssueFilter {
+            state: Some("opened".into()),
+            ..Default::default()
+        };
+        let f2 = IssueFilter {
+            state: Some("closed".into()),
+            ..Default::default()
+        };
+        assert_ne!(f1.hash_value(), f2.hash_value());
+    }
+
+    #[test]
+    fn test_snapshot_fence_not_overwritten_on_second_page() {
+        let mut state = IssueListState::default();
+        state.apply_page(sample_page(5, true));
+        let fence = state.snapshot_fence;
+
+        state.apply_page(sample_page(3, false));
+        assert_eq!(
+            state.snapshot_fence, fence,
+            "Fence should not change on second page"
+        );
+    }
+}

crates/lore-tui/src/state/mod.rs

@@ -0,0 +1,344 @@
+#![allow(dead_code)] // Phase 1: consumed by LoreApp in bd-6pmy
+
+//! Top-level state composition for the TUI.
+//!
+//! Each screen has its own state struct. State is preserved when
+//! navigating away — screens are never cleared on pop.
+//!
+//! [`LoadState`] enables stale-while-revalidate: screens show the last
+//! available data during a refresh, with a spinner indicating the load.
+//!
+//! [`ScreenIntent`] is the pure return type from state handlers — they
+//! never spawn async tasks directly. The intent is interpreted by
+//! [`LoreApp`](crate::app::LoreApp) which dispatches through the
+//! [`TaskSupervisor`](crate::task_supervisor::TaskSupervisor).
+
+pub mod command_palette;
+pub mod dashboard;
+pub mod issue_detail;
+pub mod issue_list;
+pub mod mr_detail;
+pub mod mr_list;
+pub mod search;
+pub mod sync;
+pub mod timeline;
+pub mod who;
+
+use std::collections::{HashMap, HashSet};
+
+use crate::message::Screen;
+
+// Re-export screen states for convenience.
+pub use command_palette::CommandPaletteState;
+pub use dashboard::DashboardState;
+pub use issue_detail::IssueDetailState;
+pub use issue_list::IssueListState;
+pub use mr_detail::MrDetailState;
+pub use mr_list::MrListState;
+pub use search::SearchState;
+pub use sync::SyncState;
+pub use timeline::TimelineState;
+pub use who::WhoState;
+
+// ---------------------------------------------------------------------------
+// LoadState
+// ---------------------------------------------------------------------------
+
+/// Loading state for a screen's data.
+///
+/// Enables stale-while-revalidate: screens render their last data while
+/// showing a spinner when `Refreshing`.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub enum LoadState {
+    /// No load in progress, data is current (or screen was never loaded).
+    #[default]
+    Idle,
+    /// First load — no data to show yet, display a full-screen spinner.
+    LoadingInitial,
+    /// Background refresh — show existing data with a spinner indicator.
+    Refreshing,
+    /// Load failed — display the error alongside any stale data.
+    Error(String),
+}
+
+impl LoadState {
+    /// Whether data is currently being loaded.
+    #[must_use]
+    pub fn is_loading(&self) -> bool {
+        matches!(self, Self::LoadingInitial | Self::Refreshing)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// ScreenLoadStateMap
+// ---------------------------------------------------------------------------
+
+/// Tracks per-screen load state.
+///
+/// Returns [`LoadState::Idle`] for screens that haven't been tracked.
+/// Automatically removes entries set to `Idle` to prevent unbounded growth.
+#[derive(Debug, Default)]
+pub struct ScreenLoadStateMap {
+    map: HashMap<Screen, LoadState>,
+    /// Screens that have had a load state set at least once.
+    visited: HashSet<Screen>,
+}
+
+impl ScreenLoadStateMap {
+    /// Get the load state for a screen (defaults to `Idle`).
+    #[must_use]
+    pub fn get(&self, screen: &Screen) -> &LoadState {
+        static IDLE: LoadState = LoadState::Idle;
+        self.map.get(screen).unwrap_or(&IDLE)
+    }
+
+    /// Set the load state for a screen.
+    ///
+    /// Setting to `Idle` removes the entry to prevent map growth.
+    pub fn set(&mut self, screen: Screen, state: LoadState) {
+        self.visited.insert(screen.clone());
+        if state == LoadState::Idle {
+            self.map.remove(&screen);
+        } else {
+            self.map.insert(screen, state);
+        }
+    }
+
+    /// Whether this screen has ever had a load initiated.
+    #[must_use]
+    pub fn was_visited(&self, screen: &Screen) -> bool {
+        self.visited.contains(screen)
+    }
+
+    /// Whether any screen is currently loading.
+    #[must_use]
+    pub fn any_loading(&self) -> bool {
+        self.map.values().any(LoadState::is_loading)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// ScreenIntent
+// ---------------------------------------------------------------------------
+
+/// Pure return type from screen state handlers.
+///
+/// State handlers must never spawn async work directly — they return
+/// an intent that [`LoreApp`] interprets and dispatches through the
+/// [`TaskSupervisor`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ScreenIntent {
+    /// No action needed.
+    None,
+    /// Navigate to a new screen.
+    Navigate(Screen),
+    /// Screen data needs re-querying (e.g., filter changed).
+    RequeryNeeded(Screen),
+}
+
+// ---------------------------------------------------------------------------
+// ScopeContext
+// ---------------------------------------------------------------------------
+
+/// Global scope filters applied across all screens.
+///
+/// When a project filter is active, all data queries scope to that
+/// project. The TUI shows the active scope in the status bar.
+#[derive(Debug, Default)]
+pub struct ScopeContext {
+    /// Active project filter (project_id).
+    pub project_id: Option<i64>,
+    /// Human-readable project name for display.
+    pub project_name: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// AppState
+// ---------------------------------------------------------------------------
+
+/// Top-level state composition for the TUI.
+///
+/// Each field holds one screen's state. State is preserved when
+/// navigating away and restored on return.
+#[derive(Debug, Default)]
+pub struct AppState {
+    // Per-screen states.
+    pub dashboard: DashboardState,
+    pub issue_list: IssueListState,
+    pub issue_detail: IssueDetailState,
+    pub mr_list: MrListState,
+    pub mr_detail: MrDetailState,
+    pub search: SearchState,
+    pub timeline: TimelineState,
+    pub who: WhoState,
+    pub sync: SyncState,
+    pub command_palette: CommandPaletteState,
+
+    // Cross-cutting state.
+    pub global_scope: ScopeContext,
+    pub load_state: ScreenLoadStateMap,
+    pub error_toast: Option<String>,
+    pub show_help: bool,
+    pub terminal_size: (u16, u16),
+}
+
+impl AppState {
+    /// Set a screen's load state.
+    pub fn set_loading(&mut self, screen: Screen, state: LoadState) {
+        self.load_state.set(screen, state);
+    }
+
+    /// Set the global error toast.
+    pub fn set_error(&mut self, msg: String) {
+        self.error_toast = Some(msg);
+    }
+
+    /// Clear the global error toast.
+    pub fn clear_error(&mut self) {
+        self.error_toast = None;
+    }
+
+    /// Whether any text input is currently focused.
+    #[must_use]
+    pub fn has_text_focus(&self) -> bool {
+        self.issue_list.filter_focused
+            || self.mr_list.filter_focused
+            || self.search.query_focused
+            || self.command_palette.query_focused
+    }
+
+    /// Remove focus from all text inputs.
+    pub fn blur_text_focus(&mut self) {
+        self.issue_list.filter_focused = false;
+        self.mr_list.filter_focused = false;
+        self.search.query_focused = false;
+        self.command_palette.query_focused = false;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_load_state_default_idle() {
+        let map = ScreenLoadStateMap::default();
+        assert_eq!(*map.get(&Screen::Dashboard), LoadState::Idle);
+        assert_eq!(*map.get(&Screen::IssueList), LoadState::Idle);
+    }
+
+    #[test]
+    fn test_load_state_set_and_get() {
+        let mut map = ScreenLoadStateMap::default();
+        map.set(Screen::Dashboard, LoadState::LoadingInitial);
+        assert_eq!(*map.get(&Screen::Dashboard), LoadState::LoadingInitial);
+        assert_eq!(*map.get(&Screen::IssueList), LoadState::Idle);
+    }
+
+    #[test]
+    fn test_load_state_set_idle_removes_entry() {
+        let mut map = ScreenLoadStateMap::default();
+        map.set(Screen::Dashboard, LoadState::Refreshing);
+        assert_eq!(map.map.len(), 1);
+
+        map.set(Screen::Dashboard, LoadState::Idle);
+        assert_eq!(map.map.len(), 0);
+        assert_eq!(*map.get(&Screen::Dashboard), LoadState::Idle);
+    }
+
+    #[test]
+    fn test_any_loading() {
+        let mut map = ScreenLoadStateMap::default();
+        assert!(!map.any_loading());
+
+        map.set(Screen::Dashboard, LoadState::LoadingInitial);
+        assert!(map.any_loading());
+
+        map.set(Screen::Dashboard, LoadState::Error("oops".into()));
+        assert!(!map.any_loading());
+    }
+
+    #[test]
+    fn test_load_state_is_loading() {
+        assert!(!LoadState::Idle.is_loading());
+        assert!(LoadState::LoadingInitial.is_loading());
+        assert!(LoadState::Refreshing.is_loading());
+        assert!(!LoadState::Error("x".into()).is_loading());
+    }
+
+    #[test]
+    fn test_app_state_default_compiles() {
+        let state = AppState::default();
+        assert!(!state.show_help);
+        assert!(state.error_toast.is_none());
+        assert_eq!(state.terminal_size, (0, 0));
+    }
+
+    #[test]
+    fn test_app_state_set_error_and_clear() {
+        let mut state = AppState::default();
+        state.set_error("db busy".into());
+        assert_eq!(state.error_toast.as_deref(), Some("db busy"));
+
+        state.clear_error();
+        assert!(state.error_toast.is_none());
+    }
+
+    #[test]
+    fn test_app_state_has_text_focus() {
+        let mut state = AppState::default();
+        assert!(!state.has_text_focus());
+
+        state.search.query_focused = true;
+        assert!(state.has_text_focus());
+    }
+
+    #[test]
+    fn test_app_state_blur_text_focus() {
+        let mut state = AppState::default();
+        state.issue_list.filter_focused = true;
+        state.mr_list.filter_focused = true;
+        state.search.query_focused = true;
+        state.command_palette.query_focused = true;
+
+        state.blur_text_focus();
+
+        assert!(!state.has_text_focus());
+        assert!(!state.issue_list.filter_focused);
+        assert!(!state.mr_list.filter_focused);
+        assert!(!state.search.query_focused);
+        assert!(!state.command_palette.query_focused);
+    }
+
+    #[test]
+    fn test_app_state_set_loading() {
+        let mut state = AppState::default();
+        state.set_loading(Screen::IssueList, LoadState::Refreshing);
+        assert_eq!(
+            *state.load_state.get(&Screen::IssueList),
+            LoadState::Refreshing
+        );
+    }
+
+    #[test]
+    fn test_screen_intent_variants() {
+        let none = ScreenIntent::None;
+        let nav = ScreenIntent::Navigate(Screen::IssueList);
+        let requery = ScreenIntent::RequeryNeeded(Screen::Search);
+
+        assert_eq!(none, ScreenIntent::None);
+        assert_eq!(nav, ScreenIntent::Navigate(Screen::IssueList));
+        assert_eq!(requery, ScreenIntent::RequeryNeeded(Screen::Search));
+    }
+
+    #[test]
+    fn test_scope_context_default() {
+        let scope = ScopeContext::default();
+        assert!(scope.project_id.is_none());
+        assert!(scope.project_name.is_none());
+    }
+}

crates/lore-tui/src/state/mr_detail.rs

@@ -0,0 +1,14 @@
+#![allow(dead_code)]
+
+//! Merge request detail screen state.
+
+use crate::message::{Discussion, EntityKey, MrDetail};
+
+/// State for the MR detail screen.
+#[derive(Debug, Default)]
+pub struct MrDetailState {
+    pub key: Option<EntityKey>,
+    pub detail: Option<MrDetail>,
+    pub discussions: Vec<Discussion>,
+    pub scroll_offset: u16,
+}

crates/lore-tui/src/state/mr_list.rs

@@ -0,0 +1,422 @@
+#![allow(dead_code)] // Phase 2: consumed by LoreApp and view/mr_list
+
+//! Merge request list screen state.
+//!
+//! Mirrors the issue list pattern with MR-specific filter fields
+//! (draft, reviewer, target/source branch). Uses the same keyset
+//! pagination with snapshot fence for stable ordering.
+
+use std::hash::{Hash, Hasher};
+
+// ---------------------------------------------------------------------------
+// Cursor (keyset pagination boundary)
+// ---------------------------------------------------------------------------
+
+/// Keyset pagination cursor — (updated_at, iid) boundary.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MrCursor {
+    pub updated_at: i64,
+    pub iid: i64,
+}
+
+// ---------------------------------------------------------------------------
+// Filter
+// ---------------------------------------------------------------------------
+
+/// Structured filter for MR list queries.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct MrFilter {
+    pub state: Option<String>,
+    pub author: Option<String>,
+    pub reviewer: Option<String>,
+    pub target_branch: Option<String>,
+    pub source_branch: Option<String>,
+    pub label: Option<String>,
+    pub draft: Option<bool>,
+    pub free_text: Option<String>,
+    pub project_id: Option<i64>,
+}
+
+impl MrFilter {
+    /// Compute a hash for change detection.
+    pub fn hash_value(&self) -> u64 {
+        let mut hasher = std::collections::hash_map::DefaultHasher::new();
+        self.state.hash(&mut hasher);
+        self.author.hash(&mut hasher);
+        self.reviewer.hash(&mut hasher);
+        self.target_branch.hash(&mut hasher);
+        self.source_branch.hash(&mut hasher);
+        self.label.hash(&mut hasher);
+        self.draft.hash(&mut hasher);
+        self.free_text.hash(&mut hasher);
+        self.project_id.hash(&mut hasher);
+        hasher.finish()
+    }
+
+    /// Whether any filter is active.
+    pub fn is_active(&self) -> bool {
+        self.state.is_some()
+            || self.author.is_some()
+            || self.reviewer.is_some()
+            || self.target_branch.is_some()
+            || self.source_branch.is_some()
+            || self.label.is_some()
+            || self.draft.is_some()
+            || self.free_text.is_some()
+            || self.project_id.is_some()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Row
+// ---------------------------------------------------------------------------
+
+/// A single row in the MR list.
+#[derive(Debug, Clone)]
+pub struct MrListRow {
+    pub project_path: String,
+    pub iid: i64,
+    pub title: String,
+    pub state: String,
+    pub author: String,
+    pub target_branch: String,
+    pub labels: Vec<String>,
+    pub updated_at: i64,
+    pub draft: bool,
+}
+
+// ---------------------------------------------------------------------------
+// Page result
+// ---------------------------------------------------------------------------
+
+/// Result from a paginated MR list query.
+#[derive(Debug, Clone)]
+pub struct MrListPage {
+    pub rows: Vec<MrListRow>,
+    pub next_cursor: Option<MrCursor>,
+    pub total_count: u64,
+}
+
+// ---------------------------------------------------------------------------
+// Sort
+// ---------------------------------------------------------------------------
+
+/// Fields available for sorting.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum MrSortField {
+    #[default]
+    UpdatedAt,
+    Iid,
+    Title,
+    State,
+    Author,
+    TargetBranch,
+}
+
+/// Sort direction.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum MrSortOrder {
+    #[default]
+    Desc,
+    Asc,
+}
+
+// ---------------------------------------------------------------------------
+// MrListState
+// ---------------------------------------------------------------------------
+
+/// State for the MR list screen.
+#[derive(Debug, Default)]
+pub struct MrListState {
+    /// Current page of MR rows.
+    pub rows: Vec<MrListRow>,
+    /// Total count of matching MRs.
+    pub total_count: u64,
+    /// Selected row index (within current window).
+    pub selected_index: usize,
+    /// Scroll offset for the entity table.
+    pub scroll_offset: usize,
+    /// Cursor for the next page.
+    pub next_cursor: Option<MrCursor>,
+    /// Whether a prefetch is in flight.
+    pub prefetch_in_flight: bool,
+    /// Current filter.
+    pub filter: MrFilter,
+    /// Raw filter input text.
+    pub filter_input: String,
+    /// Whether the filter bar has focus.
+    pub filter_focused: bool,
+    /// Sort field.
+    pub sort_field: MrSortField,
+    /// Sort direction.
+    pub sort_order: MrSortOrder,
+    /// Snapshot fence: max updated_at from initial load.
+    pub snapshot_fence: Option<i64>,
+    /// Hash of the current filter for change detection.
+    pub filter_hash: u64,
+    /// Whether Quick Peek is visible.
+    pub peek_visible: bool,
+}
+
+impl MrListState {
+    /// Reset pagination state (called when filter changes or on refresh).
+    pub fn reset_pagination(&mut self) {
+        self.rows.clear();
+        self.next_cursor = None;
+        self.selected_index = 0;
+        self.scroll_offset = 0;
+        self.snapshot_fence = None;
+        self.total_count = 0;
+        self.prefetch_in_flight = false;
+    }
+
+    /// Apply a new page of results.
+    pub fn apply_page(&mut self, page: MrListPage) {
+        // Set snapshot fence on first page load.
+        if self.snapshot_fence.is_none() {
+            self.snapshot_fence = page.rows.first().map(|r| r.updated_at);
+        }
+        self.rows.extend(page.rows);
+        self.next_cursor = page.next_cursor;
+        self.total_count = page.total_count;
+        self.prefetch_in_flight = false;
+    }
+
+    /// Check if filter changed and reset if needed.
+    pub fn check_filter_change(&mut self) -> bool {
+        let new_hash = self.filter.hash_value();
+        if new_hash != self.filter_hash {
+            self.filter_hash = new_hash;
+            self.reset_pagination();
+            true
+        } else {
+            false
+        }
+    }
+
+    /// Whether the user has scrolled near the end of current data (80% threshold).
+    pub fn should_prefetch(&self) -> bool {
+        if self.prefetch_in_flight || self.next_cursor.is_none() {
+            return false;
+        }
+        if self.rows.is_empty() {
+            return false;
+        }
+        let threshold = (self.rows.len() * 4) / 5; // 80%
+        self.selected_index >= threshold
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample_page(count: usize, has_next: bool) -> MrListPage {
+        let rows: Vec<MrListRow> = (0..count)
+            .map(|i| MrListRow {
+                project_path: "group/project".into(),
+                iid: (count - i) as i64,
+                title: format!("MR {}", count - i),
+                state: "opened".into(),
+                author: "taylor".into(),
+                target_branch: "main".into(),
+                labels: vec![],
+                updated_at: 1_700_000_000_000 - (i as i64 * 60_000),
+                draft: i % 3 == 0,
+            })
+            .collect();
+
+        let next_cursor = if has_next {
+            rows.last().map(|r| MrCursor {
+                updated_at: r.updated_at,
+                iid: r.iid,
+            })
+        } else {
+            None
+        };
+
+        MrListPage {
+            rows,
+            next_cursor,
+            total_count: if has_next {
+                (count * 2) as u64
+            } else {
+                count as u64
+            },
+        }
+    }
+
+    #[test]
+    fn test_apply_page_sets_snapshot_fence() {
+        let mut state = MrListState::default();
+        let page = sample_page(5, false);
+        state.apply_page(page);
+
+        assert_eq!(state.rows.len(), 5);
+        assert!(state.snapshot_fence.is_some());
+        assert_eq!(state.snapshot_fence.unwrap(), 1_700_000_000_000);
+    }
+
+    #[test]
+    fn test_apply_page_appends() {
+        let mut state = MrListState::default();
+        state.apply_page(sample_page(5, true));
+        assert_eq!(state.rows.len(), 5);
+
+        state.apply_page(sample_page(3, false));
+        assert_eq!(state.rows.len(), 8);
+    }
+
+    #[test]
+    fn test_reset_pagination_clears_state() {
+        let mut state = MrListState::default();
+        state.apply_page(sample_page(5, true));
+        state.selected_index = 3;
+
+        state.reset_pagination();
+
+        assert!(state.rows.is_empty());
+        assert_eq!(state.selected_index, 0);
+        assert!(state.next_cursor.is_none());
+        assert!(state.snapshot_fence.is_none());
+    }
+
+    #[test]
+    fn test_check_filter_change_detects_change() {
+        let mut state = MrListState::default();
+        state.filter_hash = state.filter.hash_value();
+
+        state.filter.state = Some("opened".into());
+        assert!(state.check_filter_change());
+    }
+
+    #[test]
+    fn test_check_filter_change_no_change() {
+        let mut state = MrListState::default();
+        state.filter_hash = state.filter.hash_value();
+        assert!(!state.check_filter_change());
+    }
+
+    #[test]
+    fn test_should_prefetch() {
+        let mut state = MrListState::default();
+        state.apply_page(sample_page(10, true));
+
+        state.selected_index = 4; // 40% -- no prefetch
+        assert!(!state.should_prefetch());
+
+        state.selected_index = 8; // 80% -- prefetch
+        assert!(state.should_prefetch());
+    }
+
+    #[test]
+    fn test_should_prefetch_no_next_page() {
+        let mut state = MrListState::default();
+        state.apply_page(sample_page(10, false));
+        state.selected_index = 9;
+        assert!(!state.should_prefetch());
+    }
+
+    #[test]
+    fn test_should_prefetch_already_in_flight() {
+        let mut state = MrListState::default();
+        state.apply_page(sample_page(10, true));
+        state.selected_index = 9;
+        state.prefetch_in_flight = true;
+        assert!(!state.should_prefetch());
+    }
+
+    #[test]
+    fn test_mr_filter_is_active() {
+        let empty = MrFilter::default();
+        assert!(!empty.is_active());
+
+        let active = MrFilter {
+            state: Some("opened".into()),
+            ..Default::default()
+        };
+        assert!(active.is_active());
+
+        let draft_active = MrFilter {
+            draft: Some(true),
+            ..Default::default()
+        };
+        assert!(draft_active.is_active());
+    }
+
+    #[test]
+    fn test_mr_filter_hash_deterministic() {
+        let f1 = MrFilter {
+            state: Some("opened".into()),
+            author: Some("taylor".into()),
+            ..Default::default()
+        };
+        let f2 = f1.clone();
+        assert_eq!(f1.hash_value(), f2.hash_value());
+    }
+
+    #[test]
+    fn test_mr_filter_hash_differs() {
+        let f1 = MrFilter {
+            state: Some("opened".into()),
+            ..Default::default()
+        };
+        let f2 = MrFilter {
+            state: Some("merged".into()),
+            ..Default::default()
+        };
+        assert_ne!(f1.hash_value(), f2.hash_value());
+    }
+
+    #[test]
+    fn test_snapshot_fence_not_overwritten_on_second_page() {
+        let mut state = MrListState::default();
+        state.apply_page(sample_page(5, true));
+        let fence = state.snapshot_fence;
+
+        state.apply_page(sample_page(3, false));
+        assert_eq!(
+            state.snapshot_fence, fence,
+            "Fence should not change on second page"
+        );
+    }
+
+    #[test]
+    fn test_mr_filter_reviewer_field() {
+        let f = MrFilter {
+            reviewer: Some("alice".into()),
+            ..Default::default()
+        };
+        assert!(f.is_active());
+        assert_ne!(f.hash_value(), MrFilter::default().hash_value());
+    }
+
+    #[test]
+    fn test_mr_filter_target_branch_field() {
+        let f = MrFilter {
+            target_branch: Some("main".into()),
+            ..Default::default()
+        };
+        assert!(f.is_active());
+    }
+
+    #[test]
+    fn test_mr_list_row_draft_field() {
+        let row = MrListRow {
+            project_path: "g/p".into(),
+            iid: 1,
+            title: "Draft MR".into(),
+            state: "opened".into(),
+            author: "taylor".into(),
+            target_branch: "main".into(),
+            labels: vec![],
+            updated_at: 0,
+            draft: true,
+        };
+        assert!(row.draft);
+    }
+}

crates/lore-tui/src/state/search.rs

@@ -0,0 +1,14 @@
+#![allow(dead_code)]
+
+//! Search screen state.
+
+use crate::message::SearchResult;
+
+/// State for the search screen.
+#[derive(Debug, Default)]
+pub struct SearchState {
+    pub query: String,
+    pub query_focused: bool,
+    pub results: Vec<SearchResult>,
+    pub selected_index: usize,
+}

crates/lore-tui/src/state/sync.rs

@@ -0,0 +1,15 @@
+#![allow(dead_code)]
+
+//! Sync screen state.
+
+/// State for the sync progress/summary screen.
+#[derive(Debug, Default)]
+pub struct SyncState {
+    pub stage: String,
+    pub current: u64,
+    pub total: u64,
+    pub log_lines: Vec<String>,
+    pub completed: bool,
+    pub elapsed_ms: Option<u64>,
+    pub error: Option<String>,
+}

crates/lore-tui/src/state/timeline.rs

@@ -0,0 +1,12 @@
+#![allow(dead_code)]
+
+//! Timeline screen state.
+
+use crate::message::TimelineEvent;
+
+/// State for the timeline screen.
+#[derive(Debug, Default)]
+pub struct TimelineState {
+    pub events: Vec<TimelineEvent>,
+    pub scroll_offset: u16,
+}

crates/lore-tui/src/state/who.rs

@@ -0,0 +1,12 @@
+#![allow(dead_code)]
+
+//! Who (people intelligence) screen state.
+
+use crate::message::WhoResult;
+
+/// State for the who/people screen.
+#[derive(Debug, Default)]
+pub struct WhoState {
+    pub result: Option<WhoResult>,
+    pub scroll_offset: u16,
+}

crates/lore-tui/src/task_supervisor.rs

@@ -0,0 +1,380 @@
+#![allow(dead_code)] // Phase 1: consumed by LoreApp in bd-6pmy
+
+//! Centralized background task management with dedup and cancellation.
+//!
+//! All background work (DB queries, sync, search) flows through
+//! [`TaskSupervisor`]. Submitting a task with a key that already has an
+//! active handle cancels the previous task via its [`CancelToken`] and
+//! bumps the generation counter.
+//!
+//! Generation IDs enable stale-result detection: when an async result
+//! arrives, [`is_current`] checks whether the result's generation
+//! matches the latest submission for that key.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+
+use crate::message::Screen;
+
+// ---------------------------------------------------------------------------
+// TaskKey
+// ---------------------------------------------------------------------------
+
+/// Deduplication key for background tasks.
+///
+/// Two tasks with the same key cannot run concurrently — submitting a
+/// new task with an existing key cancels the previous one.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum TaskKey {
+    /// Load data for a specific screen.
+    LoadScreen(Screen),
+    /// Global search query.
+    Search,
+    /// Sync stream (only one at a time).
+    SyncStream,
+    /// Re-query after filter change on a specific screen.
+    FilterRequery(Screen),
+}
+
+// ---------------------------------------------------------------------------
+// TaskPriority
+// ---------------------------------------------------------------------------
+
+/// Priority levels for task scheduling.
+///
+/// Lower numeric value = higher priority.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum TaskPriority {
+    /// User-initiated input (highest priority).
+    Input = 0,
+    /// Navigation-triggered data load.
+    Navigation = 1,
+    /// Background refresh / prefetch (lowest priority).
+    Background = 2,
+}
+
+// ---------------------------------------------------------------------------
+// CancelToken
+// ---------------------------------------------------------------------------
+
+/// Thread-safe cooperative cancellation flag.
+///
+/// Background tasks poll [`is_cancelled`] periodically and exit early
+/// when it returns `true`.
+#[derive(Debug)]
+pub struct CancelToken {
+    cancelled: AtomicBool,
+}
+
+impl CancelToken {
+    /// Create a new, non-cancelled token.
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            cancelled: AtomicBool::new(false),
+        }
+    }
+
+    /// Signal cancellation.
+    pub fn cancel(&self) {
+        self.cancelled.store(true, Ordering::Relaxed);
+    }
+
+    /// Check whether cancellation has been requested.
+    #[must_use]
+    pub fn is_cancelled(&self) -> bool {
+        self.cancelled.load(Ordering::Relaxed)
+    }
+}
+
+impl Default for CancelToken {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// InterruptHandle
+// ---------------------------------------------------------------------------
+
+/// Opaque handle for interrupting a rusqlite operation.
+///
+/// Wraps the rusqlite `InterruptHandle` so the supervisor can cancel
+/// long-running queries. This is only set for tasks that lease a reader
+/// connection from [`DbManager`](crate::db::DbManager).
+pub struct InterruptHandle {
+    handle: rusqlite::InterruptHandle,
+}
+
+impl std::fmt::Debug for InterruptHandle {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("InterruptHandle").finish_non_exhaustive()
+    }
+}
+
+impl InterruptHandle {
+    /// Wrap a rusqlite interrupt handle.
+    #[must_use]
+    pub fn new(handle: rusqlite::InterruptHandle) -> Self {
+        Self { handle }
+    }
+
+    /// Interrupt the associated SQLite operation.
+    pub fn interrupt(&self) {
+        self.handle.interrupt();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// TaskHandle
+// ---------------------------------------------------------------------------
+
+/// Handle returned when a task is submitted.
+///
+/// Callers use this to pass the generation ID into async work so
+/// results can be tagged and checked for staleness.
+#[derive(Debug)]
+pub struct TaskHandle {
+    /// Dedup key for this task.
+    pub key: TaskKey,
+    /// Monotonically increasing generation for stale detection.
+    pub generation: u64,
+    /// Cooperative cancellation token (shared with the supervisor).
+    pub cancel: Arc<CancelToken>,
+    /// Optional SQLite interrupt handle for long queries.
+    pub interrupt: Option<InterruptHandle>,
+}
+
+// ---------------------------------------------------------------------------
+// TaskSupervisor
+// ---------------------------------------------------------------------------
+
+/// Manages background tasks with deduplication and cancellation.
+///
+/// Only one task per [`TaskKey`] can be active. Submitting a new task
+/// with an existing key cancels the previous one (via its cancel token
+/// and optional interrupt handle) before registering the new handle.
+pub struct TaskSupervisor {
+    active: HashMap<TaskKey, TaskHandle>,
+    next_generation: AtomicU64,
+}
+
+impl TaskSupervisor {
+    /// Create a new supervisor with no active tasks.
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            active: HashMap::new(),
+            next_generation: AtomicU64::new(1),
+        }
+    }
+
+    /// Submit a new task, cancelling any existing task with the same key.
+    ///
+    /// Returns a [`TaskHandle`] with a fresh generation ID and a shared
+    /// cancel token. The caller clones the `Arc<CancelToken>` and passes
+    /// it into the async work.
+    pub fn submit(&mut self, key: TaskKey) -> &TaskHandle {
+        // Cancel existing task with this key, if any.
+        if let Some(old) = self.active.remove(&key) {
+            old.cancel.cancel();
+            if let Some(interrupt) = &old.interrupt {
+                interrupt.interrupt();
+            }
+        }
+
+        let generation = self.next_generation.fetch_add(1, Ordering::Relaxed);
+        let cancel = Arc::new(CancelToken::new());
+
+        let handle = TaskHandle {
+            key: key.clone(),
+            generation,
+            cancel,
+            interrupt: None,
+        };
+
+        self.active.insert(key.clone(), handle);
+        self.active.get(&key).expect("just inserted")
+    }
+
+    /// Check whether a generation is current for a given key.
+    ///
+    /// Returns `true` only if the key has an active handle with the
+    /// specified generation.
+    #[must_use]
+    pub fn is_current(&self, key: &TaskKey, generation: u64) -> bool {
+        self.active
+            .get(key)
+            .is_some_and(|h| h.generation == generation)
+    }
+
+    /// Mark a task as complete, removing its handle.
+    ///
+    /// Only removes the handle if the generation matches the active one.
+    /// This prevents a late-arriving completion from removing a newer
+    /// task's handle.
+    pub fn complete(&mut self, key: &TaskKey, generation: u64) {
+        if self.is_current(key, generation) {
+            self.active.remove(key);
+        }
+    }
+
+    /// Cancel all active tasks.
+    ///
+    /// Used during shutdown to ensure background work stops promptly.
+    pub fn cancel_all(&mut self) {
+        for (_, handle) in self.active.drain() {
+            handle.cancel.cancel();
+            if let Some(interrupt) = &handle.interrupt {
+                interrupt.interrupt();
+            }
+        }
+    }
+
+    /// Number of currently active tasks.
+    #[must_use]
+    pub fn active_count(&self) -> usize {
+        self.active.len()
+    }
+}
+
+impl Default for TaskSupervisor {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_submit_cancels_previous() {
+        let mut sup = TaskSupervisor::new();
+
+        let gen1 = sup.submit(TaskKey::Search).generation;
+        let cancel1 = sup.active.get(&TaskKey::Search).unwrap().cancel.clone();
+
+        let gen2 = sup.submit(TaskKey::Search).generation;
+
+        // First task's token should be cancelled.
+        assert!(cancel1.is_cancelled());
+        // Second task should have a different (higher) generation.
+        assert!(gen2 > gen1);
+        // Only one active task for this key.
+        assert_eq!(sup.active_count(), 1);
+    }
+
+    #[test]
+    fn test_is_current_after_supersede() {
+        let mut sup = TaskSupervisor::new();
+
+        let gen1 = sup.submit(TaskKey::Search).generation;
+        let gen2 = sup.submit(TaskKey::Search).generation;
+
+        assert!(!sup.is_current(&TaskKey::Search, gen1));
+        assert!(sup.is_current(&TaskKey::Search, gen2));
+    }
+
+    #[test]
+    fn test_complete_removes_handle() {
+        let mut sup = TaskSupervisor::new();
+        let generation = sup.submit(TaskKey::Search).generation;
+
+        assert_eq!(sup.active_count(), 1);
+        sup.complete(&TaskKey::Search, generation);
+        assert_eq!(sup.active_count(), 0);
+    }
+
+    #[test]
+    fn test_complete_ignores_stale() {
+        let mut sup = TaskSupervisor::new();
+
+        let gen1 = sup.submit(TaskKey::Search).generation;
+        let gen2 = sup.submit(TaskKey::Search).generation;
+
+        // Completing with old generation should NOT remove the newer handle.
+        sup.complete(&TaskKey::Search, gen1);
+        assert_eq!(sup.active_count(), 1);
+        assert!(sup.is_current(&TaskKey::Search, gen2));
+    }
+
+    #[test]
+    fn test_generation_monotonic() {
+        let mut sup = TaskSupervisor::new();
+
+        let g1 = sup.submit(TaskKey::Search).generation;
+        let g2 = sup.submit(TaskKey::SyncStream).generation;
+        let g3 = sup.submit(TaskKey::Search).generation;
+
+        assert!(g1 < g2);
+        assert!(g2 < g3);
+    }
+
+    #[test]
+    fn test_different_keys_coexist() {
+        let mut sup = TaskSupervisor::new();
+
+        sup.submit(TaskKey::Search);
+        sup.submit(TaskKey::SyncStream);
+        sup.submit(TaskKey::LoadScreen(Screen::Dashboard));
+
+        assert_eq!(sup.active_count(), 3);
+    }
+
+    #[test]
+    fn test_cancel_all() {
+        let mut sup = TaskSupervisor::new();
+
+        let cancel_search = {
+            sup.submit(TaskKey::Search);
+            sup.active.get(&TaskKey::Search).unwrap().cancel.clone()
+        };
+        let cancel_sync = {
+            sup.submit(TaskKey::SyncStream);
+            sup.active.get(&TaskKey::SyncStream).unwrap().cancel.clone()
+        };
+
+        sup.cancel_all();
+
+        assert!(cancel_search.is_cancelled());
+        assert!(cancel_sync.is_cancelled());
+        assert_eq!(sup.active_count(), 0);
+    }
+
+    #[test]
+    fn test_cancel_token_default_is_not_cancelled() {
+        let token = CancelToken::new();
+        assert!(!token.is_cancelled());
+        token.cancel();
+        assert!(token.is_cancelled());
+    }
+
+    #[test]
+    fn test_cancel_token_is_send_sync() {
+        fn assert_send_sync<T: Send + Sync>() {}
+        assert_send_sync::<CancelToken>();
+        assert_send_sync::<Arc<CancelToken>>();
+    }
+
+    #[test]
+    fn test_task_supervisor_default() {
+        let sup = TaskSupervisor::default();
+        assert_eq!(sup.active_count(), 0);
+    }
+
+    #[test]
+    fn test_filter_requery_key_distinct_per_screen() {
+        let mut sup = TaskSupervisor::new();
+
+        sup.submit(TaskKey::FilterRequery(Screen::IssueList));
+        sup.submit(TaskKey::FilterRequery(Screen::MrList));
+
+        assert_eq!(sup.active_count(), 2);
+    }
+}

crates/lore-tui/src/theme.rs

@@ -0,0 +1,251 @@
+#![allow(dead_code)] // Phase 0: types defined now, consumed in Phase 1+
+
+//! Flexoki-based theme for the lore TUI.
+//!
+//! Uses FrankenTUI's `AdaptiveColor::adaptive(light, dark)` for automatic
+//! light/dark mode switching. The palette is [Flexoki](https://stephango.com/flexoki)
+//! by Steph Ango, designed in Oklab perceptual color space for balanced contrast.
+
+use ftui::{AdaptiveColor, Color, PackedRgba, Style, Theme};
+
+// ---------------------------------------------------------------------------
+// Flexoki palette constants
+// ---------------------------------------------------------------------------
+
+// Base tones
+const PAPER: Color = Color::rgb(0xFF, 0xFC, 0xF0);
+const BASE_50: Color = Color::rgb(0xF2, 0xF0, 0xE5);
+const BASE_100: Color = Color::rgb(0xE6, 0xE4, 0xD9);
+const BASE_200: Color = Color::rgb(0xCE, 0xCD, 0xC3);
+const BASE_300: Color = Color::rgb(0xB7, 0xB5, 0xAC);
+const BASE_400: Color = Color::rgb(0x9F, 0x9D, 0x96);
+const BASE_500: Color = Color::rgb(0x87, 0x85, 0x80);
+const BASE_600: Color = Color::rgb(0x6F, 0x6E, 0x69);
+const BASE_700: Color = Color::rgb(0x57, 0x56, 0x53);
+const BASE_800: Color = Color::rgb(0x40, 0x3E, 0x3C);
+const BASE_850: Color = Color::rgb(0x34, 0x33, 0x31);
+const BASE_900: Color = Color::rgb(0x28, 0x27, 0x26);
+const BLACK: Color = Color::rgb(0x10, 0x0F, 0x0F);
+
+// Accent colors — light-600 (for light mode)
+const RED_600: Color = Color::rgb(0xAF, 0x30, 0x29);
+const ORANGE_600: Color = Color::rgb(0xBC, 0x52, 0x15);
+const YELLOW_600: Color = Color::rgb(0xAD, 0x83, 0x01);
+const GREEN_600: Color = Color::rgb(0x66, 0x80, 0x0B);
+const CYAN_600: Color = Color::rgb(0x24, 0x83, 0x7B);
+const BLUE_600: Color = Color::rgb(0x20, 0x5E, 0xA6);
+const PURPLE_600: Color = Color::rgb(0x5E, 0x40, 0x9D);
+
+// Accent colors — dark-400 (for dark mode)
+const RED_400: Color = Color::rgb(0xD1, 0x4D, 0x41);
+const ORANGE_400: Color = Color::rgb(0xDA, 0x70, 0x2C);
+const YELLOW_400: Color = Color::rgb(0xD0, 0xA2, 0x15);
+const GREEN_400: Color = Color::rgb(0x87, 0x9A, 0x39);
+const CYAN_400: Color = Color::rgb(0x3A, 0xA9, 0x9F);
+const BLUE_400: Color = Color::rgb(0x43, 0x85, 0xBE);
+const PURPLE_400: Color = Color::rgb(0x8B, 0x7E, 0xC8);
+const MAGENTA_400: Color = Color::rgb(0xCE, 0x5D, 0x97);
+
+// Muted fallback as PackedRgba (for Style::fg)
+const MUTED_PACKED: PackedRgba = PackedRgba::rgb(0x87, 0x85, 0x80);
+
+// ---------------------------------------------------------------------------
+// build_theme
+// ---------------------------------------------------------------------------
+
+/// Build the lore TUI theme with Flexoki adaptive colors.
+///
+/// Each of the 19 semantic slots gets an `AdaptiveColor::adaptive(light, dark)`
+/// pair. FrankenTUI detects the terminal background and resolves accordingly.
+#[must_use]
+pub fn build_theme() -> Theme {
+    Theme::builder()
+        .primary(AdaptiveColor::adaptive(BLUE_600, BLUE_400))
+        .secondary(AdaptiveColor::adaptive(CYAN_600, CYAN_400))
+        .accent(AdaptiveColor::adaptive(PURPLE_600, PURPLE_400))
+        .background(AdaptiveColor::adaptive(PAPER, BLACK))
+        .surface(AdaptiveColor::adaptive(BASE_50, BASE_900))
+        .overlay(AdaptiveColor::adaptive(BASE_100, BASE_850))
+        .text(AdaptiveColor::adaptive(BASE_700, BASE_200))
+        .text_muted(AdaptiveColor::adaptive(BASE_500, BASE_500))
+        .text_subtle(AdaptiveColor::adaptive(BASE_400, BASE_600))
+        .success(AdaptiveColor::adaptive(GREEN_600, GREEN_400))
+        .warning(AdaptiveColor::adaptive(YELLOW_600, YELLOW_400))
+        .error(AdaptiveColor::adaptive(RED_600, RED_400))
+        .info(AdaptiveColor::adaptive(BLUE_600, BLUE_400))
+        .border(AdaptiveColor::adaptive(BASE_300, BASE_700))
+        .border_focused(AdaptiveColor::adaptive(BLUE_600, BLUE_400))
+        .selection_bg(AdaptiveColor::adaptive(BASE_100, BASE_800))
+        .selection_fg(AdaptiveColor::adaptive(BASE_700, BASE_100))
+        .scrollbar_track(AdaptiveColor::adaptive(BASE_50, BASE_900))
+        .scrollbar_thumb(AdaptiveColor::adaptive(BASE_300, BASE_700))
+        .build()
+}
+
+// ---------------------------------------------------------------------------
+// State colors
+// ---------------------------------------------------------------------------
+
+/// Map a GitLab entity state to a display color.
+///
+/// Returns fixed (non-adaptive) colors — state indicators should be
+/// consistent regardless of light/dark mode.
+#[must_use]
+pub fn state_color(state: &str) -> Color {
+    match state {
+        "opened" => GREEN_400,
+        "closed" => RED_400,
+        "merged" => PURPLE_400,
+        "locked" => YELLOW_400,
+        _ => BASE_500,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Event type colors
+// ---------------------------------------------------------------------------
+
+/// Map a timeline event type to a display color.
+#[must_use]
+pub fn event_color(event_type: &str) -> Color {
+    match event_type {
+        "created" => GREEN_400,
+        "updated" => BLUE_400,
+        "closed" => RED_400,
+        "merged" => PURPLE_400,
+        "commented" => CYAN_400,
+        "labeled" => ORANGE_400,
+        "milestoned" => YELLOW_400,
+        _ => BASE_500,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Label styling
+// ---------------------------------------------------------------------------
+
+/// Convert a GitLab label hex color (e.g., "#FF0000" or "FF0000") to a Style.
+///
+/// Falls back to muted text color if the hex string is invalid.
+#[must_use]
+pub fn label_style(hex_color: &str) -> Style {
+    let packed = parse_hex_to_packed(hex_color).unwrap_or(MUTED_PACKED);
+    Style::default().fg(packed)
+}
+
+/// Parse a hex color string like "#RRGGBB" or "RRGGBB" into a `PackedRgba`.
+fn parse_hex_to_packed(s: &str) -> Option<PackedRgba> {
+    let hex = s.strip_prefix('#').unwrap_or(s);
+    if hex.len() != 6 {
+        return None;
+    }
+    let r = u8::from_str_radix(&hex[0..2], 16).ok()?;
+    let g = u8::from_str_radix(&hex[2..4], 16).ok()?;
+    let b = u8::from_str_radix(&hex[4..6], 16).ok()?;
+    Some(PackedRgba::rgb(r, g, b))
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_build_theme_compiles() {
+        let theme = build_theme();
+        // Resolve for dark mode — primary should be Blue-400
+        let resolved = theme.resolve(true);
+        assert_eq!(resolved.primary, BLUE_400);
+    }
+
+    #[test]
+    fn test_build_theme_light_mode() {
+        let theme = build_theme();
+        let resolved = theme.resolve(false);
+        assert_eq!(resolved.primary, BLUE_600);
+    }
+
+    #[test]
+    fn test_build_theme_all_slots_differ_between_modes() {
+        let theme = build_theme();
+        let dark = theme.resolve(true);
+        let light = theme.resolve(false);
+        // Background should differ (Paper vs Black)
+        assert_ne!(dark.background, light.background);
+        // Text should differ
+        assert_ne!(dark.text, light.text);
+    }
+
+    #[test]
+    fn test_state_color_opened_is_green() {
+        assert_eq!(state_color("opened"), GREEN_400);
+    }
+
+    #[test]
+    fn test_state_color_closed_is_red() {
+        assert_eq!(state_color("closed"), RED_400);
+    }
+
+    #[test]
+    fn test_state_color_merged_is_purple() {
+        assert_eq!(state_color("merged"), PURPLE_400);
+    }
+
+    #[test]
+    fn test_state_color_unknown_returns_muted() {
+        assert_eq!(state_color("unknown"), BASE_500);
+    }
+
+    #[test]
+    fn test_event_color_created_is_green() {
+        assert_eq!(event_color("created"), GREEN_400);
+    }
+
+    #[test]
+    fn test_event_color_unknown_returns_muted() {
+        assert_eq!(event_color("whatever"), BASE_500);
+    }
+
+    #[test]
+    fn test_label_style_valid_hex_with_hash() {
+        let style = label_style("#FF0000");
+        assert_eq!(style.fg, Some(PackedRgba::rgb(0xFF, 0x00, 0x00)));
+    }
+
+    #[test]
+    fn test_label_style_valid_hex_without_hash() {
+        let style = label_style("00FF00");
+        assert_eq!(style.fg, Some(PackedRgba::rgb(0x00, 0xFF, 0x00)));
+    }
+
+    #[test]
+    fn test_label_style_lowercase_hex() {
+        let style = label_style("#ff0000");
+        assert_eq!(style.fg, Some(PackedRgba::rgb(0xFF, 0x00, 0x00)));
+    }
+
+    #[test]
+    fn test_label_style_invalid_hex_fallback() {
+        let style = label_style("invalid");
+        assert_eq!(style.fg, Some(MUTED_PACKED));
+    }
+
+    #[test]
+    fn test_label_style_empty_fallback() {
+        let style = label_style("");
+        assert_eq!(style.fg, Some(MUTED_PACKED));
+    }
+
+    #[test]
+    fn test_parse_hex_short_string() {
+        assert!(parse_hex_to_packed("#FFF").is_none());
+    }
+
+    #[test]
+    fn test_parse_hex_non_hex_chars() {
+        assert!(parse_hex_to_packed("#GGHHII").is_none());
+    }
+}

crates/lore-tui/src/view/common/breadcrumb.rs

@@ -0,0 +1,208 @@
+//! Navigation breadcrumb trail ("Dashboard > Issues > #42").
+
+use ftui::core::geometry::Rect;
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+use crate::navigation::NavigationStack;
+
+/// Render the navigation breadcrumb trail.
+///
+/// Shows "Dashboard > Issues > Issue" with " > " separators. When the
+/// trail exceeds the available width, entries are truncated from the left
+/// with a leading "...".
+pub fn render_breadcrumb(
+    frame: &mut Frame<'_>,
+    area: Rect,
+    nav: &NavigationStack,
+    text_color: PackedRgba,
+    muted_color: PackedRgba,
+) {
+    if area.height == 0 || area.width < 3 {
+        return;
+    }
+
+    let crumbs = nav.breadcrumbs();
+    let separator = " > ";
+
+    // Build the full breadcrumb string and calculate width.
+    let full: String = crumbs.join(separator);
+    let max_width = area.width as usize;
+
+    let display = if full.len() <= max_width {
+        full
+    } else {
+        // Truncate from the left: show "... > last_crumbs"
+        truncate_breadcrumb_left(&crumbs, separator, max_width)
+    };
+
+    let base = Cell {
+        fg: text_color,
+        ..Cell::default()
+    };
+    let muted = Cell {
+        fg: muted_color,
+        ..Cell::default()
+    };
+
+    // Render each segment with separators in muted color.
+    let mut x = area.x;
+    let max_x = area.x.saturating_add(area.width);
+
+    if let Some(rest) = display.strip_prefix("...") {
+        // Render ellipsis in muted, then the rest
+        x = frame.print_text_clipped(x, area.y, "...", muted, max_x);
+        if !rest.is_empty() {
+            render_crumb_segments(frame, x, area.y, rest, separator, base, muted, max_x);
+        }
+    } else {
+        render_crumb_segments(frame, x, area.y, &display, separator, base, muted, max_x);
+    }
+}
+
+/// Render breadcrumb text with separators in muted color.
+#[allow(clippy::too_many_arguments)]
+fn render_crumb_segments(
+    frame: &mut Frame<'_>,
+    start_x: u16,
+    y: u16,
+    text: &str,
+    separator: &str,
+    base: Cell,
+    muted: Cell,
+    max_x: u16,
+) {
+    let mut x = start_x;
+    let parts: Vec<&str> = text.split(separator).collect();
+
+    for (i, part) in parts.iter().enumerate() {
+        if i > 0 {
+            x = frame.print_text_clipped(x, y, separator, muted, max_x);
+        }
+        x = frame.print_text_clipped(x, y, part, base, max_x);
+        if x >= max_x {
+            break;
+        }
+    }
+}
+
+/// Truncate breadcrumb from the left to fit within max_width.
+fn truncate_breadcrumb_left(crumbs: &[&str], separator: &str, max_width: usize) -> String {
+    let ellipsis = "...";
+
+    // Try showing progressively fewer crumbs from the right.
+    for skip in 1..crumbs.len() {
+        let tail = &crumbs[skip..];
+        let tail_str: String = tail.join(separator);
+        let candidate = format!("{ellipsis}{separator}{tail_str}");
+        if candidate.len() <= max_width {
+            return candidate;
+        }
+    }
+
+    // Last resort: just the current screen truncated.
+    let last = crumbs.last().unwrap_or(&"");
+    if last.len() + ellipsis.len() <= max_width {
+        return format!("{ellipsis}{last}");
+    }
+
+    // Truly tiny terminal: just ellipsis.
+    ellipsis.to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::message::Screen;
+    use crate::navigation::NavigationStack;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn white() -> PackedRgba {
+        PackedRgba::rgb(0xFF, 0xFF, 0xFF)
+    }
+
+    fn gray() -> PackedRgba {
+        PackedRgba::rgb(0x80, 0x80, 0x80)
+    }
+
+    #[test]
+    fn test_breadcrumb_single_screen() {
+        with_frame!(80, 1, |frame| {
+            let nav = NavigationStack::new();
+            render_breadcrumb(&mut frame, Rect::new(0, 0, 80, 1), &nav, white(), gray());
+
+            let cell = frame.buffer.get(0, 0).unwrap();
+            assert!(
+                cell.content.as_char() == Some('D'),
+                "Expected 'D' at (0,0), got {:?}",
+                cell.content.as_char()
+            );
+        });
+    }
+
+    #[test]
+    fn test_breadcrumb_multi_screen() {
+        with_frame!(80, 1, |frame| {
+            let mut nav = NavigationStack::new();
+            nav.push(Screen::IssueList);
+            render_breadcrumb(&mut frame, Rect::new(0, 0, 80, 1), &nav, white(), gray());
+
+            let d = frame.buffer.get(0, 0).unwrap();
+            assert_eq!(d.content.as_char(), Some('D'));
+
+            // "Dashboard > Issues" = 'I' at 12
+            let i_cell = frame.buffer.get(12, 0).unwrap();
+            assert_eq!(i_cell.content.as_char(), Some('I'));
+        });
+    }
+
+    #[test]
+    fn test_breadcrumb_truncation() {
+        let crumbs = vec!["Dashboard", "Issues", "Issue"];
+        let result = truncate_breadcrumb_left(&crumbs, " > ", 20);
+        assert!(
+            result.starts_with("..."),
+            "Expected ellipsis prefix, got: {result}"
+        );
+        assert!(result.len() <= 20, "Result too long: {result}");
+    }
+
+    #[test]
+    fn test_breadcrumb_zero_height_noop() {
+        with_frame!(80, 1, |frame| {
+            let nav = NavigationStack::new();
+            render_breadcrumb(&mut frame, Rect::new(0, 0, 80, 0), &nav, white(), gray());
+        });
+    }
+
+    #[test]
+    fn test_truncate_breadcrumb_fits() {
+        let crumbs = vec!["A", "B"];
+        let result = truncate_breadcrumb_left(&crumbs, " > ", 100);
+        assert!(result.contains("..."), "Should always add ellipsis");
+    }
+
+    #[test]
+    fn test_truncate_breadcrumb_single_entry() {
+        let crumbs = vec!["Dashboard"];
+        let result = truncate_breadcrumb_left(&crumbs, " > ", 5);
+        assert_eq!(result, "...");
+    }
+
+    #[test]
+    fn test_truncate_breadcrumb_shows_last_entries() {
+        let crumbs = vec!["Dashboard", "Issues", "Issue Detail"];
+        let result = truncate_breadcrumb_left(&crumbs, " > ", 30);
+        assert!(result.starts_with("..."));
+        assert!(result.contains("Issue Detail"));
+    }
+}

crates/lore-tui/src/view/common/entity_table.rs

@@ -0,0 +1,676 @@
+#![allow(dead_code)] // Phase 2: consumed by Issue List + MR List screens
+
+//! Generic entity table widget for list screens.
+//!
+//! `EntityTable<R>` renders rows with sortable, responsive columns.
+//! Columns hide gracefully when the terminal is too narrow, using
+//! priority-based visibility.
+
+use ftui::core::geometry::Rect;
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+// ---------------------------------------------------------------------------
+// Column definition
+// ---------------------------------------------------------------------------
+
+/// Describes a single table column.
+#[derive(Debug, Clone)]
+pub struct ColumnDef {
+    /// Display name shown in the header.
+    pub name: &'static str,
+    /// Minimum width in characters. Column is hidden if it can't meet this.
+    pub min_width: u16,
+    /// Flex weight for distributing extra space.
+    pub flex_weight: u16,
+    /// Visibility priority (0 = always shown, higher = hidden first).
+    pub priority: u8,
+    /// Text alignment within the column.
+    pub align: Align,
+}
+
+/// Text alignment within a column.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Align {
+    #[default]
+    Left,
+    Right,
+}
+
+// ---------------------------------------------------------------------------
+// TableRow trait
+// ---------------------------------------------------------------------------
+
+/// Trait for types that can be rendered as a table row.
+pub trait TableRow {
+    /// Return the cell text for each column, in column order.
+    fn cells(&self, col_count: usize) -> Vec<String>;
+}
+
+// ---------------------------------------------------------------------------
+// EntityTable state
+// ---------------------------------------------------------------------------
+
+/// Rendering state for the entity table.
+#[derive(Debug, Clone)]
+pub struct EntityTableState {
+    /// Index of the selected row (0-based, within the full data set).
+    pub selected: usize,
+    /// Scroll offset (first visible row index).
+    pub scroll_offset: usize,
+    /// Index of the column used for sorting.
+    pub sort_column: usize,
+    /// Sort direction.
+    pub sort_ascending: bool,
+}
+
+impl Default for EntityTableState {
+    fn default() -> Self {
+        Self {
+            selected: 0,
+            scroll_offset: 0,
+            sort_column: 0,
+            sort_ascending: true,
+        }
+    }
+}
+
+impl EntityTableState {
+    /// Move selection down by 1.
+    pub fn select_next(&mut self, total_rows: usize) {
+        if total_rows == 0 {
+            return;
+        }
+        self.selected = (self.selected + 1).min(total_rows - 1);
+    }
+
+    /// Move selection up by 1.
+    pub fn select_prev(&mut self) {
+        self.selected = self.selected.saturating_sub(1);
+    }
+
+    /// Page down (move by `page_size` rows).
+    pub fn page_down(&mut self, total_rows: usize, page_size: usize) {
+        if total_rows == 0 {
+            return;
+        }
+        self.selected = (self.selected + page_size).min(total_rows - 1);
+    }
+
+    /// Page up.
+    pub fn page_up(&mut self, page_size: usize) {
+        self.selected = self.selected.saturating_sub(page_size);
+    }
+
+    /// Jump to top.
+    pub fn select_first(&mut self) {
+        self.selected = 0;
+    }
+
+    /// Jump to bottom.
+    pub fn select_last(&mut self, total_rows: usize) {
+        if total_rows > 0 {
+            self.selected = total_rows - 1;
+        }
+    }
+
+    /// Cycle sort column forward (wraps around).
+    pub fn cycle_sort(&mut self, col_count: usize) {
+        if col_count == 0 {
+            return;
+        }
+        self.sort_column = (self.sort_column + 1) % col_count;
+    }
+
+    /// Toggle sort direction on current column.
+    pub fn toggle_sort_direction(&mut self) {
+        self.sort_ascending = !self.sort_ascending;
+    }
+
+    /// Ensure scroll offset keeps selection visible.
+    fn adjust_scroll(&mut self, visible_rows: usize) {
+        if visible_rows == 0 {
+            return;
+        }
+        if self.selected < self.scroll_offset {
+            self.scroll_offset = self.selected;
+        }
+        if self.selected >= self.scroll_offset + visible_rows {
+            self.scroll_offset = self.selected - visible_rows + 1;
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Colors
+// ---------------------------------------------------------------------------
+
+/// Colors for the entity table. Will be replaced by Theme injection.
+pub struct TableColors {
+    pub header_fg: PackedRgba,
+    pub header_bg: PackedRgba,
+    pub row_fg: PackedRgba,
+    pub row_alt_bg: PackedRgba,
+    pub selected_fg: PackedRgba,
+    pub selected_bg: PackedRgba,
+    pub sort_indicator: PackedRgba,
+    pub border: PackedRgba,
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+/// Compute which columns are visible given the available width.
+///
+/// Returns indices of visible columns sorted by original order,
+/// along with their allocated widths.
+pub fn visible_columns(columns: &[ColumnDef], available_width: u16) -> Vec<(usize, u16)> {
+    // Sort by priority (lowest = most important).
+    let mut indexed: Vec<(usize, &ColumnDef)> = columns.iter().enumerate().collect();
+    indexed.sort_by_key(|(_, col)| col.priority);
+
+    let mut result: Vec<(usize, u16)> = Vec::new();
+    let mut used_width: u16 = 0;
+    let gap = 1u16; // 1-char gap between columns.
+
+    for (idx, col) in &indexed {
+        let needed = col.min_width + if result.is_empty() { 0 } else { gap };
+        if used_width + needed <= available_width {
+            result.push((*idx, col.min_width));
+            used_width += needed;
+        }
+    }
+
+    // Distribute remaining space by flex weight.
+    let remaining = available_width.saturating_sub(used_width);
+    if remaining > 0 {
+        let total_weight: u16 = result
+            .iter()
+            .map(|(idx, _)| columns[*idx].flex_weight)
+            .sum();
+
+        if total_weight > 0 {
+            for (idx, width) in &mut result {
+                let weight = columns[*idx].flex_weight;
+                let extra =
+                    (u32::from(remaining) * u32::from(weight) / u32::from(total_weight)) as u16;
+                *width += extra;
+            }
+        }
+    }
+
+    // Sort by original column order for rendering.
+    result.sort_by_key(|(idx, _)| *idx);
+    result
+}
+
+/// Render the entity table header row.
+pub fn render_header(
+    frame: &mut Frame<'_>,
+    columns: &[ColumnDef],
+    visible: &[(usize, u16)],
+    state: &EntityTableState,
+    y: u16,
+    area_x: u16,
+    colors: &TableColors,
+) {
+    let header_cell = Cell {
+        fg: colors.header_fg,
+        bg: colors.header_bg,
+        ..Cell::default()
+    };
+    let sort_cell = Cell {
+        fg: colors.sort_indicator,
+        bg: colors.header_bg,
+        ..Cell::default()
+    };
+
+    // Fill header background.
+    let total_width: u16 = visible.iter().map(|(_, w)| w + 1).sum();
+    let header_rect = Rect::new(area_x, y, total_width, 1);
+    frame.draw_rect_filled(
+        header_rect,
+        Cell {
+            bg: colors.header_bg,
+            ..Cell::default()
+        },
+    );
+
+    let mut x = area_x;
+    for (col_idx, col_width) in visible {
+        let col = &columns[*col_idx];
+        let col_max = x.saturating_add(*col_width);
+
+        let after_name = frame.print_text_clipped(x, y, col.name, header_cell, col_max);
+
+        // Sort indicator.
+        if *col_idx == state.sort_column {
+            let arrow = if state.sort_ascending { " ^" } else { " v" };
+            frame.print_text_clipped(after_name, y, arrow, sort_cell, col_max);
+        }
+
+        x = col_max.saturating_add(1); // gap
+    }
+}
+
+/// Style context for rendering a single row.
+pub struct RowContext<'a> {
+    pub columns: &'a [ColumnDef],
+    pub visible: &'a [(usize, u16)],
+    pub is_selected: bool,
+    pub is_alt: bool,
+    pub colors: &'a TableColors,
+}
+
+/// Render a data row.
+pub fn render_row<R: TableRow>(
+    frame: &mut Frame<'_>,
+    row: &R,
+    y: u16,
+    area_x: u16,
+    ctx: &RowContext<'_>,
+) {
+    let (fg, bg) = if ctx.is_selected {
+        (ctx.colors.selected_fg, ctx.colors.selected_bg)
+    } else if ctx.is_alt {
+        (ctx.colors.row_fg, ctx.colors.row_alt_bg)
+    } else {
+        (ctx.colors.row_fg, Cell::default().bg)
+    };
+
+    let cell_style = Cell {
+        fg,
+        bg,
+        ..Cell::default()
+    };
+
+    // Fill row background if selected or alt.
+    if ctx.is_selected || ctx.is_alt {
+        let total_width: u16 = ctx.visible.iter().map(|(_, w)| w + 1).sum();
+        frame.draw_rect_filled(
+            Rect::new(area_x, y, total_width, 1),
+            Cell {
+                bg,
+                ..Cell::default()
+            },
+        );
+    }
+
+    let cells = row.cells(ctx.columns.len());
+    let mut x = area_x;
+
+    for (col_idx, col_width) in ctx.visible {
+        let col_max = x.saturating_add(*col_width);
+        let text = cells.get(*col_idx).map(String::as_str).unwrap_or("");
+
+        match ctx.columns[*col_idx].align {
+            Align::Left => {
+                frame.print_text_clipped(x, y, text, cell_style, col_max);
+            }
+            Align::Right => {
+                let text_len = text.len() as u16;
+                let start = if text_len < *col_width {
+                    x + col_width - text_len
+                } else {
+                    x
+                };
+                frame.print_text_clipped(start, y, text, cell_style, col_max);
+            }
+        }
+
+        x = col_max.saturating_add(1); // gap
+    }
+}
+
+/// Render a complete entity table: header + scrollable rows.
+pub fn render_entity_table<R: TableRow>(
+    frame: &mut Frame<'_>,
+    rows: &[R],
+    columns: &[ColumnDef],
+    state: &mut EntityTableState,
+    area: Rect,
+    colors: &TableColors,
+) {
+    if area.height < 2 || area.width < 5 {
+        return;
+    }
+
+    let visible = visible_columns(columns, area.width);
+    if visible.is_empty() {
+        return;
+    }
+
+    // Header row.
+    render_header(frame, columns, &visible, state, area.y, area.x, colors);
+
+    // Separator.
+    let sep_y = area.y.saturating_add(1);
+    let sep_cell = Cell {
+        fg: colors.border,
+        ..Cell::default()
+    };
+    let rule = "─".repeat(area.width as usize);
+    frame.print_text_clipped(
+        area.x,
+        sep_y,
+        &rule,
+        sep_cell,
+        area.x.saturating_add(area.width),
+    );
+
+    // Data rows.
+    let data_start_y = area.y.saturating_add(2);
+    let visible_rows = area.height.saturating_sub(2) as usize; // minus header + separator
+
+    state.adjust_scroll(visible_rows);
+
+    let start = state.scroll_offset;
+    let end = (start + visible_rows).min(rows.len());
+
+    for (i, row) in rows[start..end].iter().enumerate() {
+        let row_y = data_start_y.saturating_add(i as u16);
+        let absolute_idx = start + i;
+        let ctx = RowContext {
+            columns,
+            visible: &visible,
+            is_selected: absolute_idx == state.selected,
+            is_alt: absolute_idx % 2 == 1,
+            colors,
+        };
+
+        render_row(frame, row, row_y, area.x, &ctx);
+    }
+
+    // Scroll indicator if more rows below.
+    if end < rows.len() {
+        let indicator_y = data_start_y.saturating_add(visible_rows as u16);
+        if indicator_y < area.y.saturating_add(area.height) {
+            let muted = Cell {
+                fg: colors.border,
+                ..Cell::default()
+            };
+            let remaining = rows.len() - end;
+            frame.print_text_clipped(
+                area.x,
+                indicator_y,
+                &format!("... {remaining} more"),
+                muted,
+                area.x.saturating_add(area.width),
+            );
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn test_columns() -> Vec<ColumnDef> {
+        vec![
+            ColumnDef {
+                name: "IID",
+                min_width: 5,
+                flex_weight: 0,
+                priority: 0,
+                align: Align::Right,
+            },
+            ColumnDef {
+                name: "Title",
+                min_width: 10,
+                flex_weight: 3,
+                priority: 0,
+                align: Align::Left,
+            },
+            ColumnDef {
+                name: "State",
+                min_width: 8,
+                flex_weight: 1,
+                priority: 1,
+                align: Align::Left,
+            },
+            ColumnDef {
+                name: "Author",
+                min_width: 8,
+                flex_weight: 1,
+                priority: 2,
+                align: Align::Left,
+            },
+            ColumnDef {
+                name: "Updated",
+                min_width: 10,
+                flex_weight: 0,
+                priority: 3,
+                align: Align::Right,
+            },
+        ]
+    }
+
+    struct TestRow {
+        cells: Vec<String>,
+    }
+
+    impl TableRow for TestRow {
+        fn cells(&self, _col_count: usize) -> Vec<String> {
+            self.cells.clone()
+        }
+    }
+
+    fn test_colors() -> TableColors {
+        TableColors {
+            header_fg: PackedRgba::rgb(0xFF, 0xFF, 0xFF),
+            header_bg: PackedRgba::rgb(0x30, 0x30, 0x30),
+            row_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+            row_alt_bg: PackedRgba::rgb(0x28, 0x28, 0x24),
+            selected_fg: PackedRgba::rgb(0xFF, 0xFF, 0xFF),
+            selected_bg: PackedRgba::rgb(0xDA, 0x70, 0x2C),
+            sort_indicator: PackedRgba::rgb(0xDA, 0x70, 0x2C),
+            border: PackedRgba::rgb(0x87, 0x87, 0x80),
+        }
+    }
+
+    #[test]
+    fn test_visible_columns_all_fit() {
+        let cols = test_columns();
+        let vis = visible_columns(&cols, 100);
+        assert_eq!(vis.len(), 5, "All 5 columns should fit at 100 cols");
+    }
+
+    #[test]
+    fn test_visible_columns_hides_low_priority() {
+        let cols = test_columns();
+        // min widths: 5 + 10 + 8 + 8 + 10 + 4 gaps = 45.
+        // At 25 cols, only priority 0 columns (IID + Title) should fit.
+        let vis = visible_columns(&cols, 25);
+        let visible_indices: Vec<usize> = vis.iter().map(|(idx, _)| *idx).collect();
+        assert!(visible_indices.contains(&0), "IID should always be visible");
+        assert!(
+            visible_indices.contains(&1),
+            "Title should always be visible"
+        );
+        assert!(
+            !visible_indices.contains(&4),
+            "Updated (priority 3) should be hidden"
+        );
+    }
+
+    #[test]
+    fn test_column_hiding_at_60_cols() {
+        let cols = test_columns();
+        let vis = visible_columns(&cols, 60);
+        // min widths for priority 0,1,2: 5+10+8+8 + 3 gaps = 34.
+        // Priority 3 (Updated, min 10 + gap) = 45 total, should still fit.
+        assert!(vis.len() >= 3, "At least 3 columns at 60 cols");
+    }
+
+    #[test]
+    fn test_state_select_next_prev() {
+        let mut state = EntityTableState::default();
+        state.select_next(5);
+        assert_eq!(state.selected, 1);
+        state.select_next(5);
+        assert_eq!(state.selected, 2);
+        state.select_prev();
+        assert_eq!(state.selected, 1);
+    }
+
+    #[test]
+    fn test_state_select_bounds() {
+        let mut state = EntityTableState::default();
+        state.select_prev(); // at 0, can't go below
+        assert_eq!(state.selected, 0);
+
+        state.select_next(3);
+        state.select_next(3);
+        state.select_next(3); // at 2, can't go above last
+        assert_eq!(state.selected, 2);
+    }
+
+    #[test]
+    fn test_state_page_up_down() {
+        let mut state = EntityTableState::default();
+        state.page_down(20, 5);
+        assert_eq!(state.selected, 5);
+        state.page_up(3);
+        assert_eq!(state.selected, 2);
+    }
+
+    #[test]
+    fn test_state_first_last() {
+        let mut state = EntityTableState {
+            selected: 5,
+            ..Default::default()
+        };
+        state.select_first();
+        assert_eq!(state.selected, 0);
+        state.select_last(10);
+        assert_eq!(state.selected, 9);
+    }
+
+    #[test]
+    fn test_state_cycle_sort() {
+        let mut state = EntityTableState::default();
+        assert_eq!(state.sort_column, 0);
+        state.cycle_sort(5);
+        assert_eq!(state.sort_column, 1);
+        state.sort_column = 4;
+        state.cycle_sort(5); // wraps to 0
+        assert_eq!(state.sort_column, 0);
+    }
+
+    #[test]
+    fn test_state_toggle_sort_direction() {
+        let mut state = EntityTableState::default();
+        assert!(state.sort_ascending);
+        state.toggle_sort_direction();
+        assert!(!state.sort_ascending);
+    }
+
+    #[test]
+    fn test_state_adjust_scroll() {
+        let mut state = EntityTableState {
+            selected: 15,
+            scroll_offset: 0,
+            ..Default::default()
+        };
+        state.adjust_scroll(10);
+        assert_eq!(state.scroll_offset, 6); // selected=15 should be at bottom of 10-row window
+    }
+
+    #[test]
+    fn test_render_entity_table_no_panic() {
+        with_frame!(80, 20, |frame| {
+            let cols = test_columns();
+            let rows = vec![
+                TestRow {
+                    cells: vec![
+                        "#42".into(),
+                        "Fix auth bug".into(),
+                        "opened".into(),
+                        "taylor".into(),
+                        "2h ago".into(),
+                    ],
+                },
+                TestRow {
+                    cells: vec![
+                        "#43".into(),
+                        "Add tests".into(),
+                        "merged".into(),
+                        "alice".into(),
+                        "1d ago".into(),
+                    ],
+                },
+            ];
+            let mut state = EntityTableState::default();
+            let colors = test_colors();
+
+            render_entity_table(
+                &mut frame,
+                &rows,
+                &cols,
+                &mut state,
+                Rect::new(0, 0, 80, 20),
+                &colors,
+            );
+        });
+    }
+
+    #[test]
+    fn test_render_entity_table_tiny_noop() {
+        with_frame!(3, 1, |frame| {
+            let cols = test_columns();
+            let rows: Vec<TestRow> = vec![];
+            let mut state = EntityTableState::default();
+            let colors = test_colors();
+
+            render_entity_table(
+                &mut frame,
+                &rows,
+                &cols,
+                &mut state,
+                Rect::new(0, 0, 3, 1),
+                &colors,
+            );
+        });
+    }
+
+    #[test]
+    fn test_render_entity_table_empty_rows() {
+        with_frame!(80, 10, |frame| {
+            let cols = test_columns();
+            let rows: Vec<TestRow> = vec![];
+            let mut state = EntityTableState::default();
+            let colors = test_colors();
+
+            render_entity_table(
+                &mut frame,
+                &rows,
+                &cols,
+                &mut state,
+                Rect::new(0, 0, 80, 10),
+                &colors,
+            );
+        });
+    }
+
+    #[test]
+    fn test_state_select_next_empty() {
+        let mut state = EntityTableState::default();
+        state.select_next(0); // no rows
+        assert_eq!(state.selected, 0);
+    }
+}

crates/lore-tui/src/view/common/error_toast.rs

@@ -0,0 +1,132 @@
+//! Floating error toast at bottom-right.
+
+use ftui::core::geometry::Rect;
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+/// Render a floating error toast at the bottom-right of the area.
+///
+/// The toast has a colored background and truncates long messages.
+pub fn render_error_toast(
+    frame: &mut Frame<'_>,
+    area: Rect,
+    msg: &str,
+    error_bg: PackedRgba,
+    error_fg: PackedRgba,
+) {
+    if area.height < 3 || area.width < 10 || msg.is_empty() {
+        return;
+    }
+
+    // Toast dimensions: message + padding, max 60 chars or half screen.
+    let max_toast_width = (area.width / 2).clamp(20, 60);
+    let toast_text = if msg.len() as u16 > max_toast_width.saturating_sub(4) {
+        let trunc_len = max_toast_width.saturating_sub(7) as usize;
+        // Find a char boundary at or before trunc_len to avoid panicking
+        // on multi-byte UTF-8 (e.g., emoji or CJK in error messages).
+        let safe_end = msg
+            .char_indices()
+            .take_while(|&(i, _)| i <= trunc_len)
+            .last()
+            .map_or(0, |(i, c)| i + c.len_utf8())
+            .min(msg.len());
+        format!(" {}... ", &msg[..safe_end])
+    } else {
+        format!(" {msg} ")
+    };
+    let toast_width = toast_text.len() as u16;
+    let toast_height: u16 = 1;
+
+    // Position: bottom-right with 1-cell margin.
+    let x = area.right().saturating_sub(toast_width + 1);
+    let y = area.bottom().saturating_sub(toast_height + 1);
+
+    let toast_rect = Rect::new(x, y, toast_width, toast_height);
+
+    // Fill background.
+    let bg_cell = Cell {
+        bg: error_bg,
+        ..Cell::default()
+    };
+    frame.draw_rect_filled(toast_rect, bg_cell);
+
+    // Render text.
+    let text_cell = Cell {
+        fg: error_fg,
+        bg: error_bg,
+        ..Cell::default()
+    };
+    frame.print_text_clipped(x, y, &toast_text, text_cell, area.right());
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn white() -> PackedRgba {
+        PackedRgba::rgb(0xFF, 0xFF, 0xFF)
+    }
+
+    fn red_bg() -> PackedRgba {
+        PackedRgba::rgb(0xFF, 0x00, 0x00)
+    }
+
+    #[test]
+    fn test_error_toast_renders() {
+        with_frame!(80, 24, |frame| {
+            render_error_toast(
+                &mut frame,
+                Rect::new(0, 0, 80, 24),
+                "Database is busy",
+                red_bg(),
+                white(),
+            );
+
+            let y = 22u16;
+            let has_content = (40..80u16).any(|x| {
+                let cell = frame.buffer.get(x, y).unwrap();
+                !cell.is_empty()
+            });
+            assert!(has_content, "Expected error toast at bottom-right");
+        });
+    }
+
+    #[test]
+    fn test_error_toast_empty_message_noop() {
+        with_frame!(80, 24, |frame| {
+            render_error_toast(&mut frame, Rect::new(0, 0, 80, 24), "", red_bg(), white());
+
+            let has_content = (0..80u16).any(|x| {
+                (0..24u16).any(|y| {
+                    let cell = frame.buffer.get(x, y).unwrap();
+                    !cell.is_empty()
+                })
+            });
+            assert!(!has_content, "Empty message should render nothing");
+        });
+    }
+
+    #[test]
+    fn test_error_toast_truncates_long_message() {
+        with_frame!(80, 24, |frame| {
+            let long_msg = "A".repeat(200);
+            render_error_toast(
+                &mut frame,
+                Rect::new(0, 0, 80, 24),
+                &long_msg,
+                red_bg(),
+                white(),
+            );
+        });
+    }
+}

crates/lore-tui/src/view/common/filter_bar.rs

@@ -0,0 +1,469 @@
+#![allow(dead_code)] // Phase 2: consumed by Issue List + MR List screens
+
+//! Filter bar widget for list screens.
+//!
+//! Wraps a text input with DSL parsing, inline diagnostics for unknown
+//! fields, and rendered filter chips below the input.
+
+use ftui::core::geometry::Rect;
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+use crate::filter_dsl::{self, FilterToken};
+
+// ---------------------------------------------------------------------------
+// Filter bar state
+// ---------------------------------------------------------------------------
+
+/// State for the filter bar widget.
+#[derive(Debug, Clone, Default)]
+pub struct FilterBarState {
+    /// Current filter input text.
+    pub input: String,
+    /// Cursor position within the input string (byte offset).
+    pub cursor: usize,
+    /// Whether the filter bar has focus.
+    pub focused: bool,
+    /// Parsed tokens from the current input.
+    pub tokens: Vec<FilterToken>,
+    /// Fields that are unknown for the current entity type.
+    pub unknown_fields: Vec<String>,
+}
+
+impl FilterBarState {
+    /// Update parsed tokens from the current input text.
+    pub fn reparse(&mut self, known_fields: &[&str]) {
+        self.tokens = filter_dsl::parse_filter_tokens(&self.input);
+        self.unknown_fields = filter_dsl::unknown_fields(&self.tokens, known_fields)
+            .into_iter()
+            .map(String::from)
+            .collect();
+    }
+
+    /// Insert a character at the cursor position.
+    pub fn insert_char(&mut self, ch: char) {
+        if self.cursor > self.input.len() {
+            self.cursor = self.input.len();
+        }
+        self.input.insert(self.cursor, ch);
+        self.cursor += ch.len_utf8();
+    }
+
+    /// Delete the character before the cursor (backspace).
+    pub fn delete_back(&mut self) {
+        if self.cursor > 0 && !self.input.is_empty() {
+            // Find the previous character boundary.
+            let prev = self.input[..self.cursor]
+                .char_indices()
+                .next_back()
+                .map(|(i, _)| i)
+                .unwrap_or(0);
+            self.input.remove(prev);
+            self.cursor = prev;
+        }
+    }
+
+    /// Delete the character at the cursor (delete key).
+    pub fn delete_forward(&mut self) {
+        if self.cursor < self.input.len() {
+            self.input.remove(self.cursor);
+        }
+    }
+
+    /// Move cursor left by one character.
+    pub fn move_left(&mut self) {
+        if self.cursor > 0 {
+            self.cursor = self.input[..self.cursor]
+                .char_indices()
+                .next_back()
+                .map(|(i, _)| i)
+                .unwrap_or(0);
+        }
+    }
+
+    /// Move cursor right by one character.
+    pub fn move_right(&mut self) {
+        if self.cursor < self.input.len() {
+            self.cursor = self.input[self.cursor..]
+                .chars()
+                .next()
+                .map(|ch| self.cursor + ch.len_utf8())
+                .unwrap_or(self.input.len());
+        }
+    }
+
+    /// Move cursor to start.
+    pub fn move_home(&mut self) {
+        self.cursor = 0;
+    }
+
+    /// Move cursor to end.
+    pub fn move_end(&mut self) {
+        self.cursor = self.input.len();
+    }
+
+    /// Clear the input.
+    pub fn clear(&mut self) {
+        self.input.clear();
+        self.cursor = 0;
+        self.tokens.clear();
+        self.unknown_fields.clear();
+    }
+
+    /// Whether the filter has any active tokens.
+    pub fn is_active(&self) -> bool {
+        !self.tokens.is_empty()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Colors
+// ---------------------------------------------------------------------------
+
+/// Colors for the filter bar.
+pub struct FilterBarColors {
+    pub input_fg: PackedRgba,
+    pub input_bg: PackedRgba,
+    pub cursor_fg: PackedRgba,
+    pub cursor_bg: PackedRgba,
+    pub chip_fg: PackedRgba,
+    pub chip_bg: PackedRgba,
+    pub error_fg: PackedRgba,
+    pub label_fg: PackedRgba,
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+/// Render the filter bar.
+///
+/// Layout:
+/// ```text
+/// Row 0: [Filter: ][input text with cursor___________]
+/// Row 1: [chip1] [chip2] [chip3]    (if tokens present)
+/// ```
+///
+/// Returns the number of rows consumed (1 or 2).
+pub fn render_filter_bar(
+    frame: &mut Frame<'_>,
+    state: &FilterBarState,
+    area: Rect,
+    colors: &FilterBarColors,
+) -> u16 {
+    if area.height == 0 || area.width < 10 {
+        return 0;
+    }
+
+    let max_x = area.x.saturating_add(area.width);
+    let y = area.y;
+
+    // Label.
+    let label = if state.focused { "Filter: " } else { "/ " };
+    let label_cell = Cell {
+        fg: colors.label_fg,
+        ..Cell::default()
+    };
+    let after_label = frame.print_text_clipped(area.x, y, label, label_cell, max_x);
+
+    // Input text.
+    let input_cell = Cell {
+        fg: colors.input_fg,
+        bg: if state.focused {
+            colors.input_bg
+        } else {
+            Cell::default().bg
+        },
+        ..Cell::default()
+    };
+
+    if state.input.is_empty() && !state.focused {
+        let muted = Cell {
+            fg: colors.label_fg,
+            ..Cell::default()
+        };
+        frame.print_text_clipped(after_label, y, "type / to filter", muted, max_x);
+    } else {
+        // Render input text with cursor highlight.
+        render_input_with_cursor(frame, state, after_label, y, max_x, input_cell, colors);
+    }
+
+    // Error indicators for unknown fields.
+    if !state.unknown_fields.is_empty() {
+        let err_cell = Cell {
+            fg: colors.error_fg,
+            ..Cell::default()
+        };
+        let err_msg = format!("Unknown: {}", state.unknown_fields.join(", "));
+        // Right-align the error.
+        let err_x = max_x.saturating_sub(err_msg.len() as u16 + 1);
+        frame.print_text_clipped(err_x, y, &err_msg, err_cell, max_x);
+    }
+
+    // Chip row (if tokens present and space available).
+    if !state.tokens.is_empty() && area.height >= 2 {
+        let chip_y = y.saturating_add(1);
+        render_chips(frame, &state.tokens, area.x, chip_y, max_x, colors);
+        return 2;
+    }
+
+    1
+}
+
+/// Render input text with cursor highlight at the correct position.
+fn render_input_with_cursor(
+    frame: &mut Frame<'_>,
+    state: &FilterBarState,
+    start_x: u16,
+    y: u16,
+    max_x: u16,
+    base_cell: Cell,
+    colors: &FilterBarColors,
+) {
+    if !state.focused {
+        frame.print_text_clipped(start_x, y, &state.input, base_cell, max_x);
+        return;
+    }
+
+    // Split at cursor position.
+    let cursor = state.cursor;
+    let input = &state.input;
+    let (before, after) = if cursor <= input.len() {
+        (&input[..cursor], &input[cursor..])
+    } else {
+        (input.as_str(), "")
+    };
+
+    let mut x = frame.print_text_clipped(start_x, y, before, base_cell, max_x);
+
+    // Cursor character (or space if at end).
+    let cursor_cell = Cell {
+        fg: colors.cursor_fg,
+        bg: colors.cursor_bg,
+        ..Cell::default()
+    };
+
+    if let Some(ch) = after.chars().next() {
+        let s = String::from(ch);
+        x = frame.print_text_clipped(x, y, &s, cursor_cell, max_x);
+        let remaining = &after[ch.len_utf8()..];
+        frame.print_text_clipped(x, y, remaining, base_cell, max_x);
+    } else {
+        // Cursor at end — render a visible block.
+        frame.print_text_clipped(x, y, " ", cursor_cell, max_x);
+    }
+}
+
+/// Render filter chips as compact tags.
+fn render_chips(
+    frame: &mut Frame<'_>,
+    tokens: &[FilterToken],
+    start_x: u16,
+    y: u16,
+    max_x: u16,
+    colors: &FilterBarColors,
+) {
+    let chip_cell = Cell {
+        fg: colors.chip_fg,
+        bg: colors.chip_bg,
+        ..Cell::default()
+    };
+
+    let mut x = start_x;
+
+    for token in tokens {
+        if x >= max_x {
+            break;
+        }
+
+        let label = match token {
+            FilterToken::FieldValue { field, value } => format!("{field}:{value}"),
+            FilterToken::Negation { field, value } => format!("-{field}:{value}"),
+            FilterToken::FreeText(text) => text.clone(),
+            FilterToken::QuotedValue(text) => format!("\"{text}\""),
+        };
+
+        let chip_text = format!("[{label}]");
+        x = frame.print_text_clipped(x, y, &chip_text, chip_cell, max_x);
+        x = x.saturating_add(1); // gap between chips
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::filter_dsl::ISSUE_FIELDS;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn test_colors() -> FilterBarColors {
+        FilterBarColors {
+            input_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+            input_bg: PackedRgba::rgb(0x28, 0x28, 0x24),
+            cursor_fg: PackedRgba::rgb(0x00, 0x00, 0x00),
+            cursor_bg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+            chip_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+            chip_bg: PackedRgba::rgb(0x40, 0x40, 0x3C),
+            error_fg: PackedRgba::rgb(0xAF, 0x3A, 0x29),
+            label_fg: PackedRgba::rgb(0x87, 0x87, 0x80),
+        }
+    }
+
+    #[test]
+    fn test_filter_bar_state_insert_char() {
+        let mut state = FilterBarState::default();
+        state.insert_char('a');
+        state.insert_char('b');
+        assert_eq!(state.input, "ab");
+        assert_eq!(state.cursor, 2);
+    }
+
+    #[test]
+    fn test_filter_bar_state_delete_back() {
+        let mut state = FilterBarState {
+            input: "abc".into(),
+            cursor: 3,
+            ..Default::default()
+        };
+        state.delete_back();
+        assert_eq!(state.input, "ab");
+        assert_eq!(state.cursor, 2);
+    }
+
+    #[test]
+    fn test_filter_bar_state_delete_back_at_start() {
+        let mut state = FilterBarState {
+            input: "abc".into(),
+            cursor: 0,
+            ..Default::default()
+        };
+        state.delete_back();
+        assert_eq!(state.input, "abc");
+        assert_eq!(state.cursor, 0);
+    }
+
+    #[test]
+    fn test_filter_bar_state_move_left_right() {
+        let mut state = FilterBarState {
+            input: "abc".into(),
+            cursor: 2,
+            ..Default::default()
+        };
+        state.move_left();
+        assert_eq!(state.cursor, 1);
+        state.move_right();
+        assert_eq!(state.cursor, 2);
+    }
+
+    #[test]
+    fn test_filter_bar_state_home_end() {
+        let mut state = FilterBarState {
+            input: "hello".into(),
+            cursor: 3,
+            ..Default::default()
+        };
+        state.move_home();
+        assert_eq!(state.cursor, 0);
+        state.move_end();
+        assert_eq!(state.cursor, 5);
+    }
+
+    #[test]
+    fn test_filter_bar_state_clear() {
+        let mut state = FilterBarState {
+            input: "state:opened".into(),
+            cursor: 12,
+            tokens: vec![FilterToken::FieldValue {
+                field: "state".into(),
+                value: "opened".into(),
+            }],
+            ..Default::default()
+        };
+        state.clear();
+        assert!(state.input.is_empty());
+        assert_eq!(state.cursor, 0);
+        assert!(state.tokens.is_empty());
+    }
+
+    #[test]
+    fn test_filter_bar_state_reparse() {
+        let mut state = FilterBarState {
+            input: "state:opened bogus:val".into(),
+            ..Default::default()
+        };
+        state.reparse(ISSUE_FIELDS);
+        assert_eq!(state.tokens.len(), 2);
+        assert_eq!(state.unknown_fields, vec!["bogus"]);
+    }
+
+    #[test]
+    fn test_filter_bar_state_is_active() {
+        let mut state = FilterBarState::default();
+        assert!(!state.is_active());
+
+        state.input = "state:opened".into();
+        state.reparse(ISSUE_FIELDS);
+        assert!(state.is_active());
+    }
+
+    #[test]
+    fn test_render_filter_bar_unfocused_no_panic() {
+        with_frame!(80, 2, |frame| {
+            let state = FilterBarState::default();
+            let colors = test_colors();
+            let rows = render_filter_bar(&mut frame, &state, Rect::new(0, 0, 80, 2), &colors);
+            assert_eq!(rows, 1);
+        });
+    }
+
+    #[test]
+    fn test_render_filter_bar_focused_no_panic() {
+        with_frame!(80, 2, |frame| {
+            let mut state = FilterBarState {
+                input: "state:opened".into(),
+                cursor: 12,
+                focused: true,
+                ..Default::default()
+            };
+            state.reparse(ISSUE_FIELDS);
+            let colors = test_colors();
+            let rows = render_filter_bar(&mut frame, &state, Rect::new(0, 0, 80, 2), &colors);
+            assert_eq!(rows, 2); // chips rendered
+        });
+    }
+
+    #[test]
+    fn test_render_filter_bar_tiny_noop() {
+        with_frame!(5, 1, |frame| {
+            let state = FilterBarState::default();
+            let colors = test_colors();
+            let rows = render_filter_bar(&mut frame, &state, Rect::new(0, 0, 5, 1), &colors);
+            assert_eq!(rows, 0);
+        });
+    }
+
+    #[test]
+    fn test_filter_bar_unicode_cursor() {
+        let mut state = FilterBarState {
+            input: "author:田中".into(),
+            cursor: 7, // points at start of 田
+            ..Default::default()
+        };
+        state.move_right();
+        assert_eq!(state.cursor, 10); // past 田 (3 bytes)
+        state.move_left();
+        assert_eq!(state.cursor, 7); // back to 田
+    }
+}

crates/lore-tui/src/view/common/help_overlay.rs

@@ -0,0 +1,173 @@
+//! Centered modal listing keybindings for the current screen.
+
+use ftui::core::geometry::Rect;
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+use crate::commands::CommandRegistry;
+use crate::message::Screen;
+
+/// Render a centered help overlay listing keybindings for the current screen.
+///
+/// The overlay is a bordered modal that lists all commands from the
+/// registry that are available on the current screen.
+#[allow(clippy::too_many_arguments)]
+pub fn render_help_overlay(
+    frame: &mut Frame<'_>,
+    area: Rect,
+    registry: &CommandRegistry,
+    screen: &Screen,
+    border_color: PackedRgba,
+    text_color: PackedRgba,
+    muted_color: PackedRgba,
+    scroll_offset: usize,
+) {
+    if area.height < 5 || area.width < 20 {
+        return;
+    }
+
+    // Overlay dimensions: 60% of screen, capped.
+    let overlay_width = (area.width * 3 / 5).clamp(30, 70);
+    let overlay_height = (area.height * 3 / 5).clamp(8, 30);
+
+    let overlay_x = area.x + (area.width.saturating_sub(overlay_width)) / 2;
+    let overlay_y = area.y + (area.height.saturating_sub(overlay_height)) / 2;
+    let overlay_rect = Rect::new(overlay_x, overlay_y, overlay_width, overlay_height);
+
+    // Draw border.
+    let border_cell = Cell {
+        fg: border_color,
+        ..Cell::default()
+    };
+    frame.draw_border(
+        overlay_rect,
+        ftui::render::drawing::BorderChars::ROUNDED,
+        border_cell,
+    );
+
+    // Title.
+    let title = " Help (? to close) ";
+    let title_x = overlay_x + (overlay_width.saturating_sub(title.len() as u16)) / 2;
+    let title_cell = Cell {
+        fg: border_color,
+        ..Cell::default()
+    };
+    frame.print_text_clipped(title_x, overlay_y, title, title_cell, overlay_rect.right());
+
+    // Inner content area (inside border).
+    let inner = Rect::new(
+        overlay_x + 2,
+        overlay_y + 1,
+        overlay_width.saturating_sub(4),
+        overlay_height.saturating_sub(2),
+    );
+
+    // Get commands for this screen.
+    let commands = registry.help_entries(screen);
+    let visible_lines = inner.height as usize;
+
+    let key_cell = Cell {
+        fg: text_color,
+        ..Cell::default()
+    };
+    let desc_cell = Cell {
+        fg: muted_color,
+        ..Cell::default()
+    };
+
+    for (i, cmd) in commands.iter().skip(scroll_offset).enumerate() {
+        if i >= visible_lines {
+            break;
+        }
+        let y = inner.y + i as u16;
+
+        // Key binding label (left).
+        let key_label = cmd
+            .keybinding
+            .as_ref()
+            .map_or_else(String::new, |kb| kb.display());
+        let label_end = frame.print_text_clipped(inner.x, y, &key_label, key_cell, inner.right());
+
+        // Spacer + description (right).
+        let desc_x = label_end.saturating_add(2);
+        if desc_x < inner.right() {
+            frame.print_text_clipped(desc_x, y, cmd.help_text, desc_cell, inner.right());
+        }
+    }
+
+    // Scroll indicator if needed.
+    if commands.len() > visible_lines + scroll_offset {
+        let indicator = format!("({}/{})", scroll_offset + visible_lines, commands.len());
+        let ind_x = inner.right().saturating_sub(indicator.len() as u16);
+        let ind_y = overlay_rect.bottom().saturating_sub(1);
+        frame.print_text_clipped(ind_x, ind_y, &indicator, desc_cell, overlay_rect.right());
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::commands::build_registry;
+    use crate::message::Screen;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn white() -> PackedRgba {
+        PackedRgba::rgb(0xFF, 0xFF, 0xFF)
+    }
+
+    fn gray() -> PackedRgba {
+        PackedRgba::rgb(0x80, 0x80, 0x80)
+    }
+
+    #[test]
+    fn test_help_overlay_renders_border() {
+        with_frame!(80, 24, |frame| {
+            let registry = build_registry();
+            render_help_overlay(
+                &mut frame,
+                Rect::new(0, 0, 80, 24),
+                &registry,
+                &Screen::Dashboard,
+                gray(),
+                white(),
+                gray(),
+                0,
+            );
+
+            // The overlay should have non-empty cells in the center area.
+            let has_content = (20..60u16).any(|x| {
+                (8..16u16).any(|y| {
+                    let cell = frame.buffer.get(x, y).unwrap();
+                    !cell.is_empty()
+                })
+            });
+            assert!(has_content, "Expected help overlay in center area");
+        });
+    }
+
+    #[test]
+    fn test_help_overlay_tiny_terminal_noop() {
+        with_frame!(15, 4, |frame| {
+            let registry = build_registry();
+            render_help_overlay(
+                &mut frame,
+                Rect::new(0, 0, 15, 4),
+                &registry,
+                &Screen::Dashboard,
+                gray(),
+                white(),
+                gray(),
+                0,
+            );
+        });
+    }
+}

crates/lore-tui/src/view/common/loading.rs

@@ -0,0 +1,179 @@
+//! Loading spinner indicators (full-screen and corner).
+
+use ftui::core::geometry::Rect;
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+use crate::state::LoadState;
+
+/// Braille spinner frames for loading animation.
+const SPINNER_FRAMES: &[char] = &['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/// Select spinner frame from tick count.
+#[must_use]
+pub(crate) fn spinner_char(tick: u64) -> char {
+    SPINNER_FRAMES[(tick as usize) % SPINNER_FRAMES.len()]
+}
+
+/// Render a loading indicator.
+///
+/// - `LoadingInitial`: centered full-screen spinner with "Loading..."
+/// - `Refreshing`: subtle spinner in top-right corner
+/// - Other states: no-op
+pub fn render_loading(
+    frame: &mut Frame<'_>,
+    area: Rect,
+    load_state: &LoadState,
+    text_color: PackedRgba,
+    muted_color: PackedRgba,
+    tick: u64,
+) {
+    match load_state {
+        LoadState::LoadingInitial => {
+            render_centered_spinner(frame, area, "Loading...", text_color, tick);
+        }
+        LoadState::Refreshing => {
+            render_corner_spinner(frame, area, muted_color, tick);
+        }
+        _ => {}
+    }
+}
+
+/// Render a centered spinner with message.
+fn render_centered_spinner(
+    frame: &mut Frame<'_>,
+    area: Rect,
+    message: &str,
+    color: PackedRgba,
+    tick: u64,
+) {
+    if area.height == 0 || area.width < 5 {
+        return;
+    }
+
+    let spinner = spinner_char(tick);
+    let text = format!("{spinner} {message}");
+    let text_len = text.len() as u16;
+
+    // Center horizontally and vertically.
+    let x = area
+        .x
+        .saturating_add(area.width.saturating_sub(text_len) / 2);
+    let y = area.y.saturating_add(area.height / 2);
+
+    let cell = Cell {
+        fg: color,
+        ..Cell::default()
+    };
+    frame.print_text_clipped(x, y, &text, cell, area.right());
+}
+
+/// Render a subtle spinner in the top-right corner.
+fn render_corner_spinner(frame: &mut Frame<'_>, area: Rect, color: PackedRgba, tick: u64) {
+    if area.width < 2 || area.height == 0 {
+        return;
+    }
+
+    let spinner = spinner_char(tick);
+    let x = area.right().saturating_sub(2);
+    let y = area.y;
+
+    let cell = Cell {
+        fg: color,
+        ..Cell::default()
+    };
+    frame.print_text_clipped(x, y, &spinner.to_string(), cell, area.right());
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn white() -> PackedRgba {
+        PackedRgba::rgb(0xFF, 0xFF, 0xFF)
+    }
+
+    fn gray() -> PackedRgba {
+        PackedRgba::rgb(0x80, 0x80, 0x80)
+    }
+
+    #[test]
+    fn test_loading_initial_renders_spinner() {
+        with_frame!(80, 24, |frame| {
+            render_loading(
+                &mut frame,
+                Rect::new(0, 0, 80, 24),
+                &LoadState::LoadingInitial,
+                white(),
+                gray(),
+                0,
+            );
+
+            let center_y = 12u16;
+            let has_content = (0..80u16).any(|x| {
+                let cell = frame.buffer.get(x, center_y).unwrap();
+                !cell.is_empty()
+            });
+            assert!(has_content, "Expected loading spinner at center row");
+        });
+    }
+
+    #[test]
+    fn test_loading_refreshing_renders_corner() {
+        with_frame!(80, 24, |frame| {
+            render_loading(
+                &mut frame,
+                Rect::new(0, 0, 80, 24),
+                &LoadState::Refreshing,
+                white(),
+                gray(),
+                0,
+            );
+
+            let cell = frame.buffer.get(78, 0).unwrap();
+            assert!(!cell.is_empty(), "Expected corner spinner");
+        });
+    }
+
+    #[test]
+    fn test_loading_idle_noop() {
+        with_frame!(80, 24, |frame| {
+            render_loading(
+                &mut frame,
+                Rect::new(0, 0, 80, 24),
+                &LoadState::Idle,
+                white(),
+                gray(),
+                0,
+            );
+
+            let has_content = (0..80u16).any(|x| {
+                (0..24u16).any(|y| {
+                    let cell = frame.buffer.get(x, y).unwrap();
+                    !cell.is_empty()
+                })
+            });
+            assert!(!has_content, "Idle state should render nothing");
+        });
+    }
+
+    #[test]
+    fn test_spinner_animation_cycles() {
+        let frame0 = spinner_char(0);
+        let frame1 = spinner_char(1);
+        let frame_wrap = spinner_char(SPINNER_FRAMES.len() as u64);
+
+        assert_ne!(frame0, frame1, "Adjacent frames should differ");
+        assert_eq!(frame0, frame_wrap, "Should wrap around");
+    }
+}

crates/lore-tui/src/view/common/mod.rs

@@ -0,0 +1,21 @@
+//! Common widgets shared across all TUI screens.
+//!
+//! Each widget is a pure rendering function — writes directly into the
+//! [`Frame`] buffer using ftui's `Draw` trait. No state mutation,
+//! no side effects.
+
+mod breadcrumb;
+pub mod entity_table;
+mod error_toast;
+pub mod filter_bar;
+mod help_overlay;
+mod loading;
+mod status_bar;
+
+pub use breadcrumb::render_breadcrumb;
+pub use entity_table::{ColumnDef, EntityTableState, TableColors, TableRow, render_entity_table};
+pub use error_toast::render_error_toast;
+pub use filter_bar::{FilterBarColors, FilterBarState, render_filter_bar};
+pub use help_overlay::render_help_overlay;
+pub use loading::render_loading;
+pub use status_bar::render_status_bar;

crates/lore-tui/src/view/common/status_bar.rs

@@ -0,0 +1,173 @@
+//! Bottom status bar with key hints and mode indicator.
+
+use ftui::core::geometry::Rect;
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+use crate::commands::CommandRegistry;
+use crate::message::{InputMode, Screen};
+
+/// Render the bottom status bar with key hints and mode indicator.
+///
+/// Layout: `[mode] ─── [key hints]`
+///
+/// Key hints are sourced from the [`CommandRegistry`] filtered to the
+/// current screen, showing only the most important bindings.
+#[allow(clippy::too_many_arguments)]
+pub fn render_status_bar(
+    frame: &mut Frame<'_>,
+    area: Rect,
+    registry: &CommandRegistry,
+    screen: &Screen,
+    mode: &InputMode,
+    bar_bg: PackedRgba,
+    text_color: PackedRgba,
+    accent_color: PackedRgba,
+) {
+    if area.height == 0 || area.width < 5 {
+        return;
+    }
+
+    // Fill the bar background.
+    let bg_cell = Cell {
+        bg: bar_bg,
+        ..Cell::default()
+    };
+    frame.draw_rect_filled(area, bg_cell);
+
+    let mode_label = match mode {
+        InputMode::Normal => "NORMAL",
+        InputMode::Text => "INPUT",
+        InputMode::Palette => "PALETTE",
+        InputMode::GoPrefix { .. } => "g...",
+    };
+
+    // Left side: mode indicator.
+    let mode_cell = Cell {
+        fg: accent_color,
+        bg: bar_bg,
+        ..Cell::default()
+    };
+    let mut x = frame.print_text_clipped(
+        area.x.saturating_add(1),
+        area.y,
+        mode_label,
+        mode_cell,
+        area.right(),
+    );
+
+    // Spacer.
+    x = x.saturating_add(2);
+
+    // Right side: key hints from registry (formatted as "key:action").
+    let hints = registry.status_hints(screen);
+    let hint_cell = Cell {
+        fg: text_color,
+        bg: bar_bg,
+        ..Cell::default()
+    };
+    let key_cell = Cell {
+        fg: accent_color,
+        bg: bar_bg,
+        ..Cell::default()
+    };
+
+    for hint in &hints {
+        if x >= area.right().saturating_sub(1) {
+            break;
+        }
+        // Split "q:quit" into key part and description part.
+        if let Some((key_part, desc_part)) = hint.split_once(':') {
+            x = frame.print_text_clipped(x, area.y, key_part, key_cell, area.right());
+            x = frame.print_text_clipped(x, area.y, ":", hint_cell, area.right());
+            x = frame.print_text_clipped(x, area.y, desc_part, hint_cell, area.right());
+        } else {
+            x = frame.print_text_clipped(x, area.y, hint, hint_cell, area.right());
+        }
+        x = x.saturating_add(2);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::commands::build_registry;
+    use crate::message::Screen;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn white() -> PackedRgba {
+        PackedRgba::rgb(0xFF, 0xFF, 0xFF)
+    }
+
+    fn gray() -> PackedRgba {
+        PackedRgba::rgb(0x80, 0x80, 0x80)
+    }
+
+    #[test]
+    fn test_status_bar_renders_mode() {
+        with_frame!(80, 1, |frame| {
+            let registry = build_registry();
+            render_status_bar(
+                &mut frame,
+                Rect::new(0, 0, 80, 1),
+                &registry,
+                &Screen::Dashboard,
+                &InputMode::Normal,
+                gray(),
+                white(),
+                white(),
+            );
+
+            let n_cell = frame.buffer.get(1, 0).unwrap();
+            assert_eq!(n_cell.content.as_char(), Some('N'));
+        });
+    }
+
+    #[test]
+    fn test_status_bar_text_mode() {
+        with_frame!(80, 1, |frame| {
+            let registry = build_registry();
+            render_status_bar(
+                &mut frame,
+                Rect::new(0, 0, 80, 1),
+                &registry,
+                &Screen::Search,
+                &InputMode::Text,
+                gray(),
+                white(),
+                white(),
+            );
+
+            let i_cell = frame.buffer.get(1, 0).unwrap();
+            assert_eq!(i_cell.content.as_char(), Some('I'));
+        });
+    }
+
+    #[test]
+    fn test_status_bar_narrow_terminal() {
+        with_frame!(4, 1, |frame| {
+            let registry = build_registry();
+            render_status_bar(
+                &mut frame,
+                Rect::new(0, 0, 4, 1),
+                &registry,
+                &Screen::Dashboard,
+                &InputMode::Normal,
+                gray(),
+                white(),
+                white(),
+            );
+            let cell = frame.buffer.get(0, 0).unwrap();
+            assert!(cell.is_empty());
+        });
+    }
+}

crates/lore-tui/src/view/dashboard.rs

@@ -0,0 +1,554 @@
+#![allow(dead_code)] // Phase 2: wired into render_screen dispatch
+
+//! Dashboard screen view — entity counts, project sync status, recent activity.
+//!
+//! Responsive layout using [`crate::layout::classify_width`]:
+//! - Wide (Lg/Xl, >=120 cols): 3-column `[Stats | Projects | Recent]`
+//! - Medium (Md, 90–119): 2-column `[Stats+Projects | Recent]`
+//! - Narrow (Xs/Sm, <90): single column stacked
+
+use ftui::core::geometry::Rect;
+use ftui::layout::{Breakpoint, Constraint, Flex};
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+use crate::layout::classify_width;
+use crate::state::dashboard::{DashboardState, EntityCounts, LastSyncInfo, RecentActivityItem};
+
+// ---------------------------------------------------------------------------
+// Colors (Flexoki palette — will use injected Theme in a later phase)
+// ---------------------------------------------------------------------------
+
+const TEXT: PackedRgba = PackedRgba::rgb(0xCE, 0xCD, 0xC3); // tx
+const TEXT_MUTED: PackedRgba = PackedRgba::rgb(0x87, 0x87, 0x80); // tx-2
+const ACCENT: PackedRgba = PackedRgba::rgb(0xDA, 0x70, 0x2C); // orange
+const GREEN: PackedRgba = PackedRgba::rgb(0x87, 0x9A, 0x39); // green
+const YELLOW: PackedRgba = PackedRgba::rgb(0xD0, 0xA2, 0x15); // yellow
+const RED: PackedRgba = PackedRgba::rgb(0xAF, 0x3A, 0x29); // red
+const CYAN: PackedRgba = PackedRgba::rgb(0x3A, 0xA9, 0x9F); // cyan
+const BORDER: PackedRgba = PackedRgba::rgb(0x87, 0x87, 0x80); // tx-2
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+/// Render the full dashboard screen into `area`.
+pub fn render_dashboard(frame: &mut Frame<'_>, state: &DashboardState, area: Rect) {
+    if area.height < 2 || area.width < 10 {
+        return; // Too small to render.
+    }
+
+    let bp = classify_width(area.width);
+
+    match bp {
+        Breakpoint::Lg | Breakpoint::Xl => render_wide(frame, state, area),
+        Breakpoint::Md => render_medium(frame, state, area),
+        Breakpoint::Xs | Breakpoint::Sm => render_narrow(frame, state, area),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Layout variants
+// ---------------------------------------------------------------------------
+
+/// Wide: 3-column [Stats | Projects | Recent Activity].
+fn render_wide(frame: &mut Frame<'_>, state: &DashboardState, area: Rect) {
+    let cols = Flex::horizontal()
+        .constraints([
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+            Constraint::Ratio(1, 3),
+        ])
+        .split(area);
+
+    render_stat_panel(frame, &state.counts, cols[0]);
+    render_project_list(frame, state, cols[1]);
+    render_recent_activity(frame, state, cols[2]);
+}
+
+/// Medium: 2-column [Stats+Projects stacked | Recent Activity].
+fn render_medium(frame: &mut Frame<'_>, state: &DashboardState, area: Rect) {
+    let cols = Flex::horizontal()
+        .constraints([Constraint::Ratio(2, 5), Constraint::Ratio(3, 5)])
+        .split(area);
+
+    // Left column: stats on top, projects below.
+    let left_rows = Flex::vertical()
+        .constraints([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)])
+        .split(cols[0]);
+
+    render_stat_panel(frame, &state.counts, left_rows[0]);
+    render_project_list(frame, state, left_rows[1]);
+
+    render_recent_activity(frame, state, cols[1]);
+}
+
+/// Narrow: single column stacked.
+fn render_narrow(frame: &mut Frame<'_>, state: &DashboardState, area: Rect) {
+    let rows = Flex::vertical()
+        .constraints([
+            Constraint::Fixed(8), // stats
+            Constraint::Fixed(4), // projects (compact)
+            Constraint::Fill,     // recent
+        ])
+        .split(area);
+
+    render_stat_panel(frame, &state.counts, rows[0]);
+    render_project_list(frame, state, rows[1]);
+    render_recent_activity(frame, state, rows[2]);
+}
+
+// ---------------------------------------------------------------------------
+// Panels
+// ---------------------------------------------------------------------------
+
+/// Entity counts panel.
+fn render_stat_panel(frame: &mut Frame<'_>, counts: &EntityCounts, area: Rect) {
+    if area.height == 0 || area.width < 5 {
+        return;
+    }
+
+    let title_cell = Cell {
+        fg: ACCENT,
+        ..Cell::default()
+    };
+    let label_cell = Cell {
+        fg: TEXT_MUTED,
+        ..Cell::default()
+    };
+    let value_cell = Cell {
+        fg: TEXT,
+        ..Cell::default()
+    };
+
+    let max_x = area.x.saturating_add(area.width);
+    let mut y = area.y;
+    let x = area.x.saturating_add(1); // 1-char left padding
+
+    // Title
+    frame.print_text_clipped(x, y, "Entity Counts", title_cell, max_x);
+    y = y.saturating_add(1);
+
+    // Separator
+    render_horizontal_rule(frame, area.x, y, area.width, BORDER);
+    y = y.saturating_add(1);
+
+    // Stats rows
+    let stats: &[(&str, String)] = &[
+        (
+            "Issues",
+            format!("{} open / {}", counts.issues_open, counts.issues_total),
+        ),
+        (
+            "MRs",
+            format!("{} open / {}", counts.mrs_open, counts.mrs_total),
+        ),
+        ("Discussions", counts.discussions.to_string()),
+        (
+            "Notes",
+            format!(
+                "{} ({}% system)",
+                counts.notes_total, counts.notes_system_pct
+            ),
+        ),
+        ("Documents", counts.documents.to_string()),
+        ("Embeddings", counts.embeddings.to_string()),
+    ];
+
+    for (label, value) in stats {
+        if y >= area.y.saturating_add(area.height) {
+            break;
+        }
+        let after_label = frame.print_text_clipped(x, y, label, label_cell, max_x);
+        let after_colon = frame.print_text_clipped(after_label, y, ": ", label_cell, max_x);
+        frame.print_text_clipped(after_colon, y, value, value_cell, max_x);
+        y = y.saturating_add(1);
+    }
+}
+
+/// Per-project sync freshness list.
+fn render_project_list(frame: &mut Frame<'_>, state: &DashboardState, area: Rect) {
+    if area.height == 0 || area.width < 5 {
+        return;
+    }
+
+    let title_cell = Cell {
+        fg: ACCENT,
+        ..Cell::default()
+    };
+    let label_cell = Cell {
+        fg: TEXT,
+        ..Cell::default()
+    };
+
+    let max_x = area.x.saturating_add(area.width);
+    let mut y = area.y;
+    let x = area.x.saturating_add(1);
+
+    frame.print_text_clipped(x, y, "Projects", title_cell, max_x);
+    y = y.saturating_add(1);
+    render_horizontal_rule(frame, area.x, y, area.width, BORDER);
+    y = y.saturating_add(1);
+
+    if state.projects.is_empty() {
+        let muted = Cell {
+            fg: TEXT_MUTED,
+            ..Cell::default()
+        };
+        frame.print_text_clipped(x, y, "No projects synced", muted, max_x);
+        return;
+    }
+
+    for proj in &state.projects {
+        if y >= area.y.saturating_add(area.height) {
+            break;
+        }
+
+        let freshness_color = staleness_color(proj.minutes_since_sync);
+        let freshness_cell = Cell {
+            fg: freshness_color,
+            ..Cell::default()
+        };
+
+        let indicator = staleness_indicator(proj.minutes_since_sync);
+        let after_dot = frame.print_text_clipped(x, y, &indicator, freshness_cell, max_x);
+        let after_space = frame.print_text_clipped(after_dot, y, " ", label_cell, max_x);
+        frame.print_text_clipped(after_space, y, &proj.path, label_cell, max_x);
+        y = y.saturating_add(1);
+    }
+
+    // Last sync summary if available.
+    if let Some(ref sync) = state.last_sync
+        && y < area.y.saturating_add(area.height)
+    {
+        y = y.saturating_add(1); // blank line
+        render_sync_summary(frame, sync, x, y, max_x);
+    }
+}
+
+/// Scrollable recent activity list.
+fn render_recent_activity(frame: &mut Frame<'_>, state: &DashboardState, area: Rect) {
+    if area.height == 0 || area.width < 5 {
+        return;
+    }
+
+    let title_cell = Cell {
+        fg: ACCENT,
+        ..Cell::default()
+    };
+
+    let max_x = area.x.saturating_add(area.width);
+    let mut y = area.y;
+    let x = area.x.saturating_add(1);
+
+    frame.print_text_clipped(x, y, "Recent Activity", title_cell, max_x);
+    y = y.saturating_add(1);
+    render_horizontal_rule(frame, area.x, y, area.width, BORDER);
+    y = y.saturating_add(1);
+
+    if state.recent.is_empty() {
+        let muted = Cell {
+            fg: TEXT_MUTED,
+            ..Cell::default()
+        };
+        frame.print_text_clipped(x, y, "No recent activity", muted, max_x);
+        return;
+    }
+
+    let visible_rows = (area.y.saturating_add(area.height)).saturating_sub(y) as usize;
+    let items = &state.recent;
+    let start = state.scroll_offset.min(items.len().saturating_sub(1));
+    let end = (start + visible_rows).min(items.len());
+
+    for item in &items[start..end] {
+        if y >= area.y.saturating_add(area.height) {
+            break;
+        }
+        render_activity_row(frame, item, x, y, max_x);
+        y = y.saturating_add(1);
+    }
+
+    // Scroll indicator if there's more content.
+    if end < items.len() && y < area.y.saturating_add(area.height) {
+        let muted = Cell {
+            fg: TEXT_MUTED,
+            ..Cell::default()
+        };
+        let remaining = items.len() - end;
+        frame.print_text_clipped(x, y, &format!("... {remaining} more"), muted, max_x);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// Render a single recent activity row.
+fn render_activity_row(
+    frame: &mut Frame<'_>,
+    item: &RecentActivityItem,
+    x: u16,
+    y: u16,
+    max_x: u16,
+) {
+    let type_color = if item.entity_type == "issue" {
+        CYAN
+    } else {
+        ACCENT
+    };
+    let type_cell = Cell {
+        fg: type_color,
+        ..Cell::default()
+    };
+    let text_cell = Cell {
+        fg: TEXT,
+        ..Cell::default()
+    };
+    let muted_cell = Cell {
+        fg: TEXT_MUTED,
+        ..Cell::default()
+    };
+
+    let type_label = if item.entity_type == "issue" {
+        format!("#{}", item.iid)
+    } else {
+        format!("!{}", item.iid)
+    };
+
+    let after_type = frame.print_text_clipped(x, y, &type_label, type_cell, max_x);
+    let after_space = frame.print_text_clipped(after_type, y, " ", text_cell, max_x);
+
+    // Truncate title to leave room for time.
+    let time_str = format_relative_time(item.minutes_ago);
+    let time_width = time_str.len() as u16 + 2; // " " + time
+    let title_max = max_x.saturating_sub(time_width);
+
+    let after_title = frame.print_text_clipped(after_space, y, &item.title, text_cell, title_max);
+
+    // Right-align time string.
+    let time_x = max_x.saturating_sub(time_str.len() as u16 + 1);
+    if time_x > after_title {
+        frame.print_text_clipped(time_x, y, &time_str, muted_cell, max_x);
+    }
+}
+
+/// Render a last-sync summary line.
+fn render_sync_summary(frame: &mut Frame<'_>, sync: &LastSyncInfo, x: u16, y: u16, max_x: u16) {
+    let status_color = if sync.status == "succeeded" {
+        GREEN
+    } else {
+        RED
+    };
+    let cell = Cell {
+        fg: status_color,
+        ..Cell::default()
+    };
+    let muted = Cell {
+        fg: TEXT_MUTED,
+        ..Cell::default()
+    };
+
+    let label_end = frame.print_text_clipped(x, y, "Last sync: ", muted, max_x);
+    let status_end = frame.print_text_clipped(label_end, y, &sync.status, cell, max_x);
+
+    if let Some(ref err) = sync.error {
+        let err_cell = Cell {
+            fg: RED,
+            ..Cell::default()
+        };
+        let after_space = frame.print_text_clipped(status_end, y, " — ", muted, max_x);
+        frame.print_text_clipped(after_space, y, err, err_cell, max_x);
+    }
+}
+
+/// Draw a horizontal rule across a row.
+fn render_horizontal_rule(frame: &mut Frame<'_>, x: u16, y: u16, width: u16, color: PackedRgba) {
+    let cell = Cell {
+        fg: color,
+        ..Cell::default()
+    };
+    let rule = "─".repeat(width as usize);
+    frame.print_text_clipped(x, y, &rule, cell, x.saturating_add(width));
+}
+
+/// Staleness color: green <60min, yellow <360min, red >360min.
+const fn staleness_color(minutes: u64) -> PackedRgba {
+    if minutes == u64::MAX {
+        RED // Never synced.
+    } else if minutes < 60 {
+        GREEN
+    } else if minutes < 360 {
+        YELLOW
+    } else {
+        RED
+    }
+}
+
+/// Staleness dot indicator.
+fn staleness_indicator(minutes: u64) -> String {
+    if minutes == u64::MAX {
+        "● never".to_string()
+    } else if minutes < 60 {
+        format!("● {minutes}m ago")
+    } else if minutes < 1440 {
+        format!("● {}h ago", minutes / 60)
+    } else {
+        format!("● {}d ago", minutes / 1440)
+    }
+}
+
+/// Format relative time for activity feed.
+fn format_relative_time(minutes: u64) -> String {
+    if minutes == 0 {
+        "just now".to_string()
+    } else if minutes < 60 {
+        format!("{minutes}m ago")
+    } else if minutes < 1440 {
+        format!("{}h ago", minutes / 60)
+    } else {
+        format!("{}d ago", minutes / 1440)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::state::dashboard::{DashboardData, EntityCounts, ProjectSyncInfo};
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn sample_state() -> DashboardState {
+        let mut state = DashboardState::default();
+        state.update(DashboardData {
+            counts: EntityCounts {
+                issues_open: 42,
+                issues_total: 100,
+                mrs_open: 10,
+                mrs_total: 50,
+                discussions: 200,
+                notes_total: 500,
+                notes_system_pct: 30,
+                documents: 80,
+                embeddings: 75,
+            },
+            projects: vec![
+                ProjectSyncInfo {
+                    path: "group/alpha".into(),
+                    minutes_since_sync: 15,
+                },
+                ProjectSyncInfo {
+                    path: "group/beta".into(),
+                    minutes_since_sync: 120,
+                },
+            ],
+            recent: vec![RecentActivityItem {
+                entity_type: "issue".into(),
+                iid: 42,
+                title: "Fix authentication bug".into(),
+                state: "opened".into(),
+                minutes_ago: 5,
+            }],
+            last_sync: None,
+        });
+        state
+    }
+
+    #[test]
+    fn test_render_dashboard_wide_no_panic() {
+        with_frame!(140, 30, |frame| {
+            let state = sample_state();
+            let area = Rect::new(0, 0, 140, 30);
+            render_dashboard(&mut frame, &state, area);
+        });
+    }
+
+    #[test]
+    fn test_render_dashboard_medium_no_panic() {
+        with_frame!(100, 24, |frame| {
+            let state = sample_state();
+            let area = Rect::new(0, 0, 100, 24);
+            render_dashboard(&mut frame, &state, area);
+        });
+    }
+
+    #[test]
+    fn test_render_dashboard_narrow_no_panic() {
+        with_frame!(60, 20, |frame| {
+            let state = sample_state();
+            let area = Rect::new(0, 0, 60, 20);
+            render_dashboard(&mut frame, &state, area);
+        });
+    }
+
+    #[test]
+    fn test_render_dashboard_tiny_noop() {
+        with_frame!(5, 1, |frame| {
+            let state = DashboardState::default();
+            let area = Rect::new(0, 0, 5, 1);
+            render_dashboard(&mut frame, &state, area);
+        });
+    }
+
+    #[test]
+    fn test_render_dashboard_empty_state_no_panic() {
+        with_frame!(120, 24, |frame| {
+            let state = DashboardState::default();
+            let area = Rect::new(0, 0, 120, 24);
+            render_dashboard(&mut frame, &state, area);
+        });
+    }
+
+    #[test]
+    fn test_staleness_color_thresholds() {
+        assert_eq!(staleness_color(0), GREEN);
+        assert_eq!(staleness_color(59), GREEN);
+        assert_eq!(staleness_color(60), YELLOW);
+        assert_eq!(staleness_color(359), YELLOW);
+        assert_eq!(staleness_color(360), RED);
+        assert_eq!(staleness_color(u64::MAX), RED);
+    }
+
+    #[test]
+    fn test_staleness_indicator() {
+        assert_eq!(staleness_indicator(15), "● 15m ago");
+        assert_eq!(staleness_indicator(120), "● 2h ago");
+        assert_eq!(staleness_indicator(2880), "● 2d ago");
+        assert_eq!(staleness_indicator(u64::MAX), "● never");
+    }
+
+    #[test]
+    fn test_format_relative_time() {
+        assert_eq!(format_relative_time(0), "just now");
+        assert_eq!(format_relative_time(5), "5m ago");
+        assert_eq!(format_relative_time(90), "1h ago");
+        assert_eq!(format_relative_time(1500), "1d ago");
+    }
+
+    #[test]
+    fn test_stat_panel_renders_title() {
+        with_frame!(40, 10, |frame| {
+            let counts = EntityCounts {
+                issues_open: 3,
+                issues_total: 10,
+                ..Default::default()
+            };
+            render_stat_panel(&mut frame, &counts, Rect::new(0, 0, 40, 10));
+
+            // Check that 'E' from "Entity Counts" is rendered at x=1, y=0.
+            let cell = frame.buffer.get(1, 0).unwrap();
+            assert_eq!(cell.content.as_char(), Some('E'), "Expected 'E' at (1,0)");
+        });
+    }
+}

crates/lore-tui/src/view/issue_list.rs

@@ -0,0 +1,353 @@
+#![allow(dead_code)] // Phase 2: consumed by view/mod.rs screen dispatch
+
+//! Issue list screen view.
+//!
+//! Composes the reusable [`EntityTable`] and [`FilterBar`] widgets
+//! with issue-specific column definitions and [`TableRow`] implementation.
+
+use ftui::core::geometry::Rect;
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+use crate::state::issue_list::{IssueListRow, IssueListState, SortField, SortOrder};
+use crate::view::common::entity_table::{
+    Align, ColumnDef, EntityTableState, TableColors, TableRow, render_entity_table,
+};
+use crate::view::common::filter_bar::{FilterBarColors, FilterBarState, render_filter_bar};
+
+// ---------------------------------------------------------------------------
+// TableRow implementation for IssueListRow
+// ---------------------------------------------------------------------------
+
+impl TableRow for IssueListRow {
+    fn cells(&self, col_count: usize) -> Vec<String> {
+        let mut cells = Vec::with_capacity(col_count);
+
+        // Column order must match ISSUE_COLUMNS definition.
+        // 0: IID
+        cells.push(format!("#{}", self.iid));
+        // 1: Title
+        cells.push(self.title.clone());
+        // 2: State
+        cells.push(self.state.clone());
+        // 3: Author
+        cells.push(self.author.clone());
+        // 4: Labels
+        cells.push(self.labels.join(", "));
+        // 5: Project
+        cells.push(self.project_path.clone());
+
+        cells.truncate(col_count);
+        cells
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Column definitions
+// ---------------------------------------------------------------------------
+
+/// Column definitions for the issue list table.
+const ISSUE_COLUMNS: &[ColumnDef] = &[
+    ColumnDef {
+        name: "IID",
+        min_width: 5,
+        flex_weight: 0,
+        priority: 0,
+        align: Align::Right,
+    },
+    ColumnDef {
+        name: "Title",
+        min_width: 15,
+        flex_weight: 4,
+        priority: 0,
+        align: Align::Left,
+    },
+    ColumnDef {
+        name: "State",
+        min_width: 7,
+        flex_weight: 0,
+        priority: 0,
+        align: Align::Left,
+    },
+    ColumnDef {
+        name: "Author",
+        min_width: 8,
+        flex_weight: 1,
+        priority: 1,
+        align: Align::Left,
+    },
+    ColumnDef {
+        name: "Labels",
+        min_width: 10,
+        flex_weight: 2,
+        priority: 2,
+        align: Align::Left,
+    },
+    ColumnDef {
+        name: "Project",
+        min_width: 12,
+        flex_weight: 1,
+        priority: 3,
+        align: Align::Left,
+    },
+];
+
+// ---------------------------------------------------------------------------
+// Colors
+// ---------------------------------------------------------------------------
+
+fn table_colors() -> TableColors {
+    TableColors {
+        header_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        header_bg: PackedRgba::rgb(0x34, 0x34, 0x31),
+        row_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        row_alt_bg: PackedRgba::rgb(0x1C, 0x1B, 0x1A),
+        selected_fg: PackedRgba::rgb(0x10, 0x0F, 0x0F),
+        selected_bg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        sort_indicator: PackedRgba::rgb(0x87, 0x96, 0x6B),
+        border: PackedRgba::rgb(0x40, 0x40, 0x3C),
+    }
+}
+
+fn filter_colors() -> FilterBarColors {
+    FilterBarColors {
+        input_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        input_bg: PackedRgba::rgb(0x28, 0x28, 0x24),
+        cursor_fg: PackedRgba::rgb(0x00, 0x00, 0x00),
+        cursor_bg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        chip_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        chip_bg: PackedRgba::rgb(0x40, 0x40, 0x3C),
+        error_fg: PackedRgba::rgb(0xAF, 0x3A, 0x29),
+        label_fg: PackedRgba::rgb(0x87, 0x87, 0x80),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+/// Render the full issue list screen.
+///
+/// Layout:
+/// ```text
+/// Row 0:     [Filter bar: / filter input_________]
+/// Row 1:     [chip1] [chip2]   (if filter active)
+/// Row 2:     ─────────────────────────────────────
+/// Row 3..N:  IID  Title          State  Author  ...
+///            ───────────────────────────────────────
+///            #42  Fix login bug  open   alice   ...
+///            #41  Add tests      open   bob     ...
+/// Bottom:    Showing 42 of 128 issues
+/// ```
+pub fn render_issue_list(frame: &mut Frame<'_>, state: &IssueListState, area: Rect) {
+    if area.height < 3 || area.width < 10 {
+        return;
+    }
+
+    let mut y = area.y;
+    let max_x = area.x.saturating_add(area.width);
+
+    // -- Filter bar ---------------------------------------------------------
+    let filter_area = Rect::new(area.x, y, area.width, 2.min(area.height));
+    let fb_state = FilterBarState {
+        input: state.filter_input.clone(),
+        cursor: state.filter_input.len(),
+        focused: state.filter_focused,
+        tokens: crate::filter_dsl::parse_filter_tokens(&state.filter_input),
+        unknown_fields: Vec::new(),
+    };
+    let filter_rows = render_filter_bar(frame, &fb_state, filter_area, &filter_colors());
+    y = y.saturating_add(filter_rows);
+
+    // -- Status line (total count) ------------------------------------------
+    let remaining_height = area.height.saturating_sub(y - area.y);
+    if remaining_height < 2 {
+        return;
+    }
+
+    // Reserve bottom row for status.
+    let table_height = remaining_height.saturating_sub(1);
+    let status_y = y.saturating_add(table_height);
+
+    // -- Entity table -------------------------------------------------------
+    let sort_col = match state.sort_field {
+        SortField::UpdatedAt => 0, // Map to IID column (closest visual proxy)
+        SortField::Iid => 0,
+        SortField::Title => 1,
+        SortField::State => 2,
+        SortField::Author => 3,
+    };
+
+    let mut table_state = EntityTableState {
+        selected: state.selected_index,
+        scroll_offset: state.scroll_offset,
+        sort_column: sort_col,
+        sort_ascending: matches!(state.sort_order, SortOrder::Asc),
+    };
+
+    let table_area = Rect::new(area.x, y, area.width, table_height);
+    render_entity_table(
+        frame,
+        &state.rows,
+        ISSUE_COLUMNS,
+        &mut table_state,
+        table_area,
+        &table_colors(),
+    );
+
+    // -- Bottom status ------------------------------------------------------
+    if status_y < area.y.saturating_add(area.height) {
+        render_status_line(frame, state, area.x, status_y, max_x);
+    }
+}
+
+/// Render the bottom status line showing row count and pagination info.
+fn render_status_line(frame: &mut Frame<'_>, state: &IssueListState, x: u16, y: u16, max_x: u16) {
+    let muted = Cell {
+        fg: PackedRgba::rgb(0x87, 0x87, 0x80),
+        ..Cell::default()
+    };
+
+    let status = if state.rows.is_empty() {
+        "No issues found".to_string()
+    } else {
+        let showing = state.rows.len();
+        let total = state.total_count;
+        if state.next_cursor.is_some() {
+            format!("Showing {showing} of {total} issues (more available)")
+        } else {
+            format!("Showing {showing} of {total} issues")
+        }
+    };
+
+    frame.print_text_clipped(x, y, &status, muted, max_x);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn sample_state(row_count: usize) -> IssueListState {
+        let rows: Vec<IssueListRow> = (0..row_count)
+            .map(|i| IssueListRow {
+                project_path: "group/project".into(),
+                iid: (i + 1) as i64,
+                title: format!("Issue {}", i + 1),
+                state: if i % 2 == 0 { "opened" } else { "closed" }.into(),
+                author: "taylor".into(),
+                labels: if i == 0 {
+                    vec!["bug".into(), "critical".into()]
+                } else {
+                    vec![]
+                },
+                updated_at: 1_700_000_000_000 - (i as i64 * 60_000),
+            })
+            .collect();
+
+        IssueListState {
+            total_count: row_count as u64,
+            rows,
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn test_render_issue_list_no_panic() {
+        with_frame!(120, 30, |frame| {
+            let state = sample_state(10);
+            render_issue_list(&mut frame, &state, Rect::new(0, 0, 120, 30));
+        });
+    }
+
+    #[test]
+    fn test_render_issue_list_empty_no_panic() {
+        with_frame!(80, 20, |frame| {
+            let state = IssueListState::default();
+            render_issue_list(&mut frame, &state, Rect::new(0, 0, 80, 20));
+        });
+    }
+
+    #[test]
+    fn test_render_issue_list_tiny_noop() {
+        with_frame!(5, 2, |frame| {
+            let state = sample_state(5);
+            render_issue_list(&mut frame, &state, Rect::new(0, 0, 5, 2));
+            // Should not panic with too-small area.
+        });
+    }
+
+    #[test]
+    fn test_render_issue_list_narrow_no_panic() {
+        with_frame!(40, 15, |frame| {
+            let state = sample_state(5);
+            render_issue_list(&mut frame, &state, Rect::new(0, 0, 40, 15));
+        });
+    }
+
+    #[test]
+    fn test_render_issue_list_with_filter_no_panic() {
+        with_frame!(100, 25, |frame| {
+            let mut state = sample_state(5);
+            state.filter_input = "state:opened".into();
+            state.filter_focused = true;
+            render_issue_list(&mut frame, &state, Rect::new(0, 0, 100, 25));
+        });
+    }
+
+    #[test]
+    fn test_issue_list_row_cells() {
+        let row = IssueListRow {
+            project_path: "group/proj".into(),
+            iid: 42,
+            title: "Fix bug".into(),
+            state: "opened".into(),
+            author: "alice".into(),
+            labels: vec!["bug".into(), "urgent".into()],
+            updated_at: 1_700_000_000_000,
+        };
+
+        let cells = row.cells(6);
+        assert_eq!(cells[0], "#42");
+        assert_eq!(cells[1], "Fix bug");
+        assert_eq!(cells[2], "opened");
+        assert_eq!(cells[3], "alice");
+        assert_eq!(cells[4], "bug, urgent");
+        assert_eq!(cells[5], "group/proj");
+    }
+
+    #[test]
+    fn test_issue_list_row_cells_truncated() {
+        let row = IssueListRow {
+            project_path: "g/p".into(),
+            iid: 1,
+            title: "t".into(),
+            state: "opened".into(),
+            author: "a".into(),
+            labels: vec![],
+            updated_at: 0,
+        };
+
+        // Request fewer columns than available.
+        let cells = row.cells(3);
+        assert_eq!(cells.len(), 3);
+    }
+
+    #[test]
+    fn test_column_count() {
+        assert_eq!(ISSUE_COLUMNS.len(), 6);
+    }
+}

crates/lore-tui/src/view/mod.rs

@@ -0,0 +1,194 @@
+#![allow(dead_code)] // Phase 1: screen content renders added in Phase 2+
+
+//! Top-level view dispatch for the lore TUI.
+//!
+//! [`render_screen`] is the entry point called from `LoreApp::view()`.
+//! It composes the layout: breadcrumb bar, screen content area, status
+//! bar, and optional overlays (help, error toast).
+
+pub mod common;
+pub mod dashboard;
+pub mod issue_list;
+pub mod mr_list;
+
+use ftui::layout::{Constraint, Flex};
+use ftui::render::cell::PackedRgba;
+use ftui::render::frame::Frame;
+
+use crate::app::LoreApp;
+use crate::message::Screen;
+
+use common::{
+    render_breadcrumb, render_error_toast, render_help_overlay, render_loading, render_status_bar,
+};
+use dashboard::render_dashboard;
+use issue_list::render_issue_list;
+use mr_list::render_mr_list;
+
+// ---------------------------------------------------------------------------
+// Colors (hardcoded Flexoki palette — will use Theme in Phase 2)
+// ---------------------------------------------------------------------------
+
+const TEXT: PackedRgba = PackedRgba::rgb(0xCE, 0xCD, 0xC3); // tx
+const TEXT_MUTED: PackedRgba = PackedRgba::rgb(0x87, 0x87, 0x80); // tx-2
+const BG_SURFACE: PackedRgba = PackedRgba::rgb(0x28, 0x28, 0x24); // bg-2
+const ACCENT: PackedRgba = PackedRgba::rgb(0xDA, 0x70, 0x2C); // orange
+const ERROR_BG: PackedRgba = PackedRgba::rgb(0xAF, 0x3A, 0x29); // red
+const ERROR_FG: PackedRgba = PackedRgba::rgb(0xCE, 0xCD, 0xC3); // tx
+const BORDER: PackedRgba = PackedRgba::rgb(0x87, 0x87, 0x80); // tx-2
+
+// ---------------------------------------------------------------------------
+// render_screen
+// ---------------------------------------------------------------------------
+
+/// Top-level view dispatch: composes breadcrumb + content + status bar + overlays.
+///
+/// Called from `LoreApp::view()`. The layout is:
+/// ```text
+/// +-----------------------------------+
+/// | Breadcrumb (1 row)                |
+/// +-----------------------------------+
+/// |                                   |
+/// | Screen content (fill)             |
+/// |                                   |
+/// +-----------------------------------+
+/// | Status bar (1 row)                |
+/// +-----------------------------------+
+/// ```
+///
+/// Overlays (help, error toast) render on top of existing content.
+pub fn render_screen(frame: &mut Frame<'_>, app: &LoreApp) {
+    let bounds = frame.bounds();
+    if bounds.width < 3 || bounds.height < 3 {
+        return; // Terminal too small to render anything useful.
+    }
+
+    // Split vertically: breadcrumb (1) | content (fill) | status bar (1).
+    let regions = Flex::vertical()
+        .constraints([
+            Constraint::Fixed(1), // breadcrumb
+            Constraint::Fill,     // content
+            Constraint::Fixed(1), // status bar
+        ])
+        .split(bounds);
+
+    let breadcrumb_area = regions[0];
+    let content_area = regions[1];
+    let status_area = regions[2];
+
+    let screen = app.navigation.current();
+
+    // --- Breadcrumb ---
+    render_breadcrumb(frame, breadcrumb_area, &app.navigation, TEXT, TEXT_MUTED);
+
+    // --- Screen content ---
+    let load_state = app.state.load_state.get(screen);
+    // tick=0 placeholder — animation wired up when Msg::Tick increments a counter.
+    render_loading(frame, content_area, load_state, TEXT, TEXT_MUTED, 0);
+
+    // Per-screen content dispatch (other screens wired in later phases).
+    if screen == &Screen::Dashboard {
+        render_dashboard(frame, &app.state.dashboard, content_area);
+    } else if screen == &Screen::IssueList {
+        render_issue_list(frame, &app.state.issue_list, content_area);
+    } else if screen == &Screen::MrList {
+        render_mr_list(frame, &app.state.mr_list, content_area);
+    }
+
+    // --- Status bar ---
+    render_status_bar(
+        frame,
+        status_area,
+        &app.command_registry,
+        screen,
+        &app.input_mode,
+        BG_SURFACE,
+        TEXT,
+        ACCENT,
+    );
+
+    // --- Overlays (render last, on top of everything) ---
+
+    // Error toast.
+    if let Some(ref error_msg) = app.state.error_toast {
+        render_error_toast(frame, bounds, error_msg, ERROR_BG, ERROR_FG);
+    }
+
+    // Help overlay.
+    if app.state.show_help {
+        render_help_overlay(
+            frame,
+            bounds,
+            &app.command_registry,
+            screen,
+            BORDER,
+            TEXT,
+            TEXT_MUTED,
+            0, // scroll_offset — tracked in future phase
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::app::LoreApp;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    #[test]
+    fn test_render_screen_does_not_panic() {
+        with_frame!(80, 24, |frame| {
+            let app = LoreApp::new();
+            render_screen(&mut frame, &app);
+        });
+    }
+
+    #[test]
+    fn test_render_screen_tiny_terminal_noop() {
+        with_frame!(2, 2, |frame| {
+            let app = LoreApp::new();
+            render_screen(&mut frame, &app);
+            // Should not panic — early return for tiny terminals.
+        });
+    }
+
+    #[test]
+    fn test_render_screen_with_error_toast() {
+        with_frame!(80, 24, |frame| {
+            let mut app = LoreApp::new();
+            app.state.set_error("test error".into());
+            render_screen(&mut frame, &app);
+            // Should render without panicking.
+        });
+    }
+
+    #[test]
+    fn test_render_screen_with_help_overlay() {
+        with_frame!(80, 24, |frame| {
+            let mut app = LoreApp::new();
+            app.state.show_help = true;
+            render_screen(&mut frame, &app);
+            // Should render without panicking.
+        });
+    }
+
+    #[test]
+    fn test_render_screen_narrow_terminal() {
+        with_frame!(20, 5, |frame| {
+            let app = LoreApp::new();
+            render_screen(&mut frame, &app);
+        });
+    }
+}

crates/lore-tui/src/view/mr_list.rs

@@ -0,0 +1,390 @@
+#![allow(dead_code)] // Phase 2: consumed by view/mod.rs screen dispatch
+
+//! MR list screen view.
+//!
+//! Composes the reusable [`EntityTable`] and [`FilterBar`] widgets
+//! with MR-specific column definitions and [`TableRow`] implementation.
+
+use ftui::core::geometry::Rect;
+use ftui::render::cell::{Cell, PackedRgba};
+use ftui::render::drawing::Draw;
+use ftui::render::frame::Frame;
+
+use crate::state::mr_list::{MrListRow, MrListState, MrSortField, MrSortOrder};
+use crate::view::common::entity_table::{
+    Align, ColumnDef, EntityTableState, TableColors, TableRow, render_entity_table,
+};
+use crate::view::common::filter_bar::{FilterBarColors, FilterBarState, render_filter_bar};
+
+// ---------------------------------------------------------------------------
+// TableRow implementation for MrListRow
+// ---------------------------------------------------------------------------
+
+impl TableRow for MrListRow {
+    fn cells(&self, col_count: usize) -> Vec<String> {
+        let mut cells = Vec::with_capacity(col_count);
+
+        // Column order must match MR_COLUMNS definition.
+        // 0: IID (with draft indicator)
+        let iid_text = if self.draft {
+            format!("!{} [WIP]", self.iid)
+        } else {
+            format!("!{}", self.iid)
+        };
+        cells.push(iid_text);
+        // 1: Title
+        cells.push(self.title.clone());
+        // 2: State
+        cells.push(self.state.clone());
+        // 3: Author
+        cells.push(self.author.clone());
+        // 4: Target Branch
+        cells.push(self.target_branch.clone());
+        // 5: Labels
+        cells.push(self.labels.join(", "));
+        // 6: Project
+        cells.push(self.project_path.clone());
+
+        cells.truncate(col_count);
+        cells
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Column definitions
+// ---------------------------------------------------------------------------
+
+/// Column definitions for the MR list table.
+const MR_COLUMNS: &[ColumnDef] = &[
+    ColumnDef {
+        name: "IID",
+        min_width: 6,
+        flex_weight: 0,
+        priority: 0,
+        align: Align::Right,
+    },
+    ColumnDef {
+        name: "Title",
+        min_width: 15,
+        flex_weight: 4,
+        priority: 0,
+        align: Align::Left,
+    },
+    ColumnDef {
+        name: "State",
+        min_width: 7,
+        flex_weight: 0,
+        priority: 0,
+        align: Align::Left,
+    },
+    ColumnDef {
+        name: "Author",
+        min_width: 8,
+        flex_weight: 1,
+        priority: 1,
+        align: Align::Left,
+    },
+    ColumnDef {
+        name: "Target",
+        min_width: 8,
+        flex_weight: 1,
+        priority: 1,
+        align: Align::Left,
+    },
+    ColumnDef {
+        name: "Labels",
+        min_width: 10,
+        flex_weight: 2,
+        priority: 2,
+        align: Align::Left,
+    },
+    ColumnDef {
+        name: "Project",
+        min_width: 12,
+        flex_weight: 1,
+        priority: 3,
+        align: Align::Left,
+    },
+];
+
+// ---------------------------------------------------------------------------
+// Colors
+// ---------------------------------------------------------------------------
+
+fn table_colors() -> TableColors {
+    TableColors {
+        header_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        header_bg: PackedRgba::rgb(0x34, 0x34, 0x31),
+        row_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        row_alt_bg: PackedRgba::rgb(0x1C, 0x1B, 0x1A),
+        selected_fg: PackedRgba::rgb(0x10, 0x0F, 0x0F),
+        selected_bg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        sort_indicator: PackedRgba::rgb(0x87, 0x96, 0x6B),
+        border: PackedRgba::rgb(0x40, 0x40, 0x3C),
+    }
+}
+
+fn filter_colors() -> FilterBarColors {
+    FilterBarColors {
+        input_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        input_bg: PackedRgba::rgb(0x28, 0x28, 0x24),
+        cursor_fg: PackedRgba::rgb(0x00, 0x00, 0x00),
+        cursor_bg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        chip_fg: PackedRgba::rgb(0xCE, 0xCD, 0xC3),
+        chip_bg: PackedRgba::rgb(0x40, 0x40, 0x3C),
+        error_fg: PackedRgba::rgb(0xAF, 0x3A, 0x29),
+        label_fg: PackedRgba::rgb(0x87, 0x87, 0x80),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+/// Render the full MR list screen.
+///
+/// Layout:
+/// ```text
+/// Row 0:     [Filter bar: / filter input_________]
+/// Row 1:     [chip1] [chip2]   (if filter active)
+/// Row 2:     -----------------------------------------
+/// Row 3..N:  IID    Title          State  Author  ...
+///            -----------------------------------------
+///            !42    Fix pipeline   opened alice   ...
+///            !41    Add CI config  merged bob     ...
+/// Bottom:    Showing 42 of 128 merge requests
+/// ```
+pub fn render_mr_list(frame: &mut Frame<'_>, state: &MrListState, area: Rect) {
+    if area.height < 3 || area.width < 10 {
+        return;
+    }
+
+    let mut y = area.y;
+    let max_x = area.x.saturating_add(area.width);
+
+    // -- Filter bar ---------------------------------------------------------
+    let filter_area = Rect::new(area.x, y, area.width, 2.min(area.height));
+    let fb_state = FilterBarState {
+        input: state.filter_input.clone(),
+        cursor: state.filter_input.len(),
+        focused: state.filter_focused,
+        tokens: crate::filter_dsl::parse_filter_tokens(&state.filter_input),
+        unknown_fields: Vec::new(),
+    };
+    let filter_rows = render_filter_bar(frame, &fb_state, filter_area, &filter_colors());
+    y = y.saturating_add(filter_rows);
+
+    // -- Status line (total count) ------------------------------------------
+    let remaining_height = area.height.saturating_sub(y - area.y);
+    if remaining_height < 2 {
+        return;
+    }
+
+    // Reserve bottom row for status.
+    let table_height = remaining_height.saturating_sub(1);
+    let status_y = y.saturating_add(table_height);
+
+    // -- Entity table -------------------------------------------------------
+    let sort_col = match state.sort_field {
+        MrSortField::UpdatedAt | MrSortField::Iid => 0,
+        MrSortField::Title => 1,
+        MrSortField::State => 2,
+        MrSortField::Author => 3,
+        MrSortField::TargetBranch => 4,
+    };
+
+    let mut table_state = EntityTableState {
+        selected: state.selected_index,
+        scroll_offset: state.scroll_offset,
+        sort_column: sort_col,
+        sort_ascending: matches!(state.sort_order, MrSortOrder::Asc),
+    };
+
+    let table_area = Rect::new(area.x, y, area.width, table_height);
+    render_entity_table(
+        frame,
+        &state.rows,
+        MR_COLUMNS,
+        &mut table_state,
+        table_area,
+        &table_colors(),
+    );
+
+    // -- Bottom status ------------------------------------------------------
+    if status_y < area.y.saturating_add(area.height) {
+        render_status_line(frame, state, area.x, status_y, max_x);
+    }
+}
+
+/// Render the bottom status line showing row count and pagination info.
+fn render_status_line(frame: &mut Frame<'_>, state: &MrListState, x: u16, y: u16, max_x: u16) {
+    let muted = Cell {
+        fg: PackedRgba::rgb(0x87, 0x87, 0x80),
+        ..Cell::default()
+    };
+
+    let status = if state.rows.is_empty() {
+        "No merge requests found".to_string()
+    } else {
+        let showing = state.rows.len();
+        let total = state.total_count;
+        if state.next_cursor.is_some() {
+            format!("Showing {showing} of {total} merge requests (more available)")
+        } else {
+            format!("Showing {showing} of {total} merge requests")
+        }
+    };
+
+    frame.print_text_clipped(x, y, &status, muted, max_x);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ftui::render::grapheme_pool::GraphemePool;
+
+    macro_rules! with_frame {
+        ($width:expr, $height:expr, |$frame:ident| $body:block) => {{
+            let mut pool = GraphemePool::new();
+            let mut $frame = Frame::new($width, $height, &mut pool);
+            $body
+        }};
+    }
+
+    fn sample_state(row_count: usize) -> MrListState {
+        let rows: Vec<MrListRow> = (0..row_count)
+            .map(|i| MrListRow {
+                project_path: "group/project".into(),
+                iid: (i + 1) as i64,
+                title: format!("MR {}", i + 1),
+                state: if i % 2 == 0 { "opened" } else { "merged" }.into(),
+                author: "taylor".into(),
+                target_branch: "main".into(),
+                labels: if i == 0 {
+                    vec!["backend".into(), "urgent".into()]
+                } else {
+                    vec![]
+                },
+                updated_at: 1_700_000_000_000 - (i as i64 * 60_000),
+                draft: i % 3 == 0,
+            })
+            .collect();
+
+        MrListState {
+            total_count: row_count as u64,
+            rows,
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn test_render_mr_list_no_panic() {
+        with_frame!(120, 30, |frame| {
+            let state = sample_state(10);
+            render_mr_list(&mut frame, &state, Rect::new(0, 0, 120, 30));
+        });
+    }
+
+    #[test]
+    fn test_render_mr_list_empty_no_panic() {
+        with_frame!(80, 20, |frame| {
+            let state = MrListState::default();
+            render_mr_list(&mut frame, &state, Rect::new(0, 0, 80, 20));
+        });
+    }
+
+    #[test]
+    fn test_render_mr_list_tiny_noop() {
+        with_frame!(5, 2, |frame| {
+            let state = sample_state(5);
+            render_mr_list(&mut frame, &state, Rect::new(0, 0, 5, 2));
+        });
+    }
+
+    #[test]
+    fn test_render_mr_list_narrow_no_panic() {
+        with_frame!(40, 15, |frame| {
+            let state = sample_state(5);
+            render_mr_list(&mut frame, &state, Rect::new(0, 0, 40, 15));
+        });
+    }
+
+    #[test]
+    fn test_render_mr_list_with_filter_no_panic() {
+        with_frame!(100, 25, |frame| {
+            let mut state = sample_state(5);
+            state.filter_input = "state:opened".into();
+            state.filter_focused = true;
+            render_mr_list(&mut frame, &state, Rect::new(0, 0, 100, 25));
+        });
+    }
+
+    #[test]
+    fn test_mr_list_row_cells() {
+        let row = MrListRow {
+            project_path: "group/proj".into(),
+            iid: 42,
+            title: "Fix pipeline".into(),
+            state: "opened".into(),
+            author: "alice".into(),
+            target_branch: "main".into(),
+            labels: vec!["backend".into(), "urgent".into()],
+            updated_at: 1_700_000_000_000,
+            draft: false,
+        };
+
+        let cells = row.cells(7);
+        assert_eq!(cells[0], "!42");
+        assert_eq!(cells[1], "Fix pipeline");
+        assert_eq!(cells[2], "opened");
+        assert_eq!(cells[3], "alice");
+        assert_eq!(cells[4], "main");
+        assert_eq!(cells[5], "backend, urgent");
+        assert_eq!(cells[6], "group/proj");
+    }
+
+    #[test]
+    fn test_mr_list_row_cells_draft() {
+        let row = MrListRow {
+            project_path: "g/p".into(),
+            iid: 7,
+            title: "WIP MR".into(),
+            state: "opened".into(),
+            author: "bob".into(),
+            target_branch: "develop".into(),
+            labels: vec![],
+            updated_at: 0,
+            draft: true,
+        };
+
+        let cells = row.cells(7);
+        assert_eq!(cells[0], "!7 [WIP]");
+    }
+
+    #[test]
+    fn test_mr_list_row_cells_truncated() {
+        let row = MrListRow {
+            project_path: "g/p".into(),
+            iid: 1,
+            title: "t".into(),
+            state: "opened".into(),
+            author: "a".into(),
+            target_branch: "main".into(),
+            labels: vec![],
+            updated_at: 0,
+            draft: false,
+        };
+
+        let cells = row.cells(3);
+        assert_eq!(cells.len(), 3);
+    }
+
+    #[test]
+    fn test_column_count() {
+        assert_eq!(MR_COLUMNS.len(), 7);
+    }
+}

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

@@ -1,92 +0,0 @@
-# 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

@@ -1,308 +0,0 @@
-# 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

@@ -1,452 +0,0 @@
-# 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

@@ -1,210 +0,0 @@
-# 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

@@ -1,179 +0,0 @@
-# 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

@@ -1,170 +0,0 @@
-# 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

@@ -1,216 +0,0 @@
-# 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

@@ -1,198 +0,0 @@
-# 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

@@ -1,347 +0,0 @@
-# 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

@@ -1,181 +0,0 @@
-# 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

@@ -1,290 +0,0 @@
-# `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 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.
+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.
 
 ```diff
 @@ Bridge Contract (Cross-Cutting)

docs/plan-expose-discussion-ids.md

@@ -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`,
-`issues <IID>`/`mrs <IID>`, and `discussions --include-notes` — without special-casing by command.
+`show`, 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

gitlore-sync-explorer.html

@@ -0,0 +1,844 @@
+<!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,6 +19,3 @@ 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,6 +151,3 @@ 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,6 +6,3 @@ 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,6 +18,3 @@ 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

@@ -1,23 +0,0 @@
--- 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/027_tui_list_indexes.sql

@@ -0,0 +1,41 @@
+-- Covering indexes for TUI list screen keyset pagination.
+-- These supplement existing indexes from earlier migrations to
+-- enable efficient ORDER BY ... LIMIT queries without temp B-tree sorts.
+
+-- Issue list: default sort (updated_at DESC, iid DESC) with state filter.
+-- Covers: WHERE project_id = ? AND state = ? ORDER BY updated_at DESC, iid DESC
+CREATE INDEX IF NOT EXISTS idx_issues_tui_list
+    ON issues(project_id, state, updated_at DESC, iid DESC);
+
+-- MR list: default sort (updated_at DESC, iid DESC) with state filter.
+CREATE INDEX IF NOT EXISTS idx_mrs_tui_list
+    ON merge_requests(project_id, state, updated_at DESC, iid DESC);
+
+-- Discussion list for entity detail screens: ordered by first note timestamp.
+CREATE INDEX IF NOT EXISTS idx_discussions_issue_ordered
+    ON discussions(issue_id, first_note_at DESC)
+    WHERE issue_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_discussions_mr_ordered
+    ON discussions(merge_request_id, first_note_at DESC)
+    WHERE merge_request_id IS NOT NULL;
+
+-- Notes within a discussion: chronological order for detail views.
+CREATE INDEX IF NOT EXISTS idx_notes_discussion_ordered
+    ON notes(discussion_id, created_at ASC);
+
+-- Filter-path indexes for TUI filter bar queries.
+-- Issues: author filter with state (covers WHERE author_username = ? AND state = ?).
+CREATE INDEX IF NOT EXISTS idx_issues_author_state
+    ON issues(author_username, state);
+
+-- MRs: author filter with state.
+CREATE INDEX IF NOT EXISTS idx_mrs_author_state
+    ON merge_requests(author_username, state);
+
+-- MRs: target branch filter with state.
+CREATE INDEX IF NOT EXISTS idx_mrs_target_branch_state
+    ON merge_requests(target_branch, state);
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (27, strftime('%s', 'now') * 1000, 'TUI list screen covering indexes');

migrations/028_discussions_mr_fk.sql

@@ -1,58 +0,0 @@
--- 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');