perf(ingestion): implement prefetch pattern for issue discussions

Issue discussion sync was ~10x slower than MR discussion sync because it
used a fully sequential pattern: fetch one issue's discussions, write to
DB, repeat. MR sync already used a prefetch pattern with concurrent HTTP
requests followed by sequential DB writes.

This commit brings issue discussion sync to parity with MRs:

Architecture (prefetch pattern):
  1. HTTP phase: Concurrent fetches via `join_all()` with batch size
     controlled by `dependent_concurrency` config (default 8)
  2. Transform phase: Normalize discussions and notes during prefetch
  3. DB phase: Sequential writes with proper transaction boundaries

Changes:
  - gitlab/client.rs: Add `fetch_all_issue_discussions()` to mirror
    the existing MR pattern for API consistency
  - discussions.rs: Replace `ingest_issue_discussions()` with:
    * `prefetch_issue_discussions()` - async HTTP fetch + transform
    * `write_prefetched_issue_discussions()` - sync DB writes
    * New structs: `PrefetchedIssueDiscussions`, `PrefetchedDiscussion`
  - orchestrator.rs: Update `sync_discussions_sequential()` to use
    concurrent prefetch for each batch instead of sequential calls
  - surgical.rs: Update single-issue surgical sync to use new functions
  - mod.rs: Update public exports

Expected improvement: 5-10x speedup on issue discussion sync (from ~50s
to ~5-10s for large projects) due to concurrent HTTP round-trips.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.beads/last-touched

@@ -1 +1 @@
-bd-1elx
+bd-8con

.gitignore

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

AGENTS.md

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

CLAUDE.md

@@ -0,0 +1,953 @@
+# 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
+
+# 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.lock

@@ -171,9 +171,9 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "charmed-lipgloss"
-version = "0.1.2"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "45e10db01f5eaea11d98ca5c5cffd8cc4add7ac56d0128d91ba1f2a3757b6c5a"
+checksum = "a5986a4a6d84055da99e44a6c532fd412d636fe5c3fe17da105a7bf40287ccd1"
 dependencies = [
  "bitflags",
  "colored",
@@ -183,6 +183,7 @@ dependencies = [
  "thiserror",
  "toml",
  "tracing",
+ "unicode-segmentation",
  "unicode-width 0.1.14",
 ]
 
@@ -1157,7 +1158,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lore"
-version = "0.8.3"
+version = "0.9.1"
 dependencies = [
  "async-stream",
  "charmed-lipgloss",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lore"
-version = "0.8.3"
+version = "0.9.1"
 edition = "2024"
 description = "Gitlore - Local GitLab data management with semantic search"
 authors = ["Taylor Eernisse"]
@@ -25,7 +25,7 @@ clap_complete = "4"
 dialoguer = "0.12"
 console = "0.16"
 indicatif = "0.18"
-lipgloss = { package = "charmed-lipgloss", version = "0.1", default-features = false, features = ["native"] }
+lipgloss = { package = "charmed-lipgloss", version = "0.2", default-features = false, features = ["native"] }
 open = "5"
 
 # HTTP

README.md

@@ -12,6 +12,9 @@ Local GitLab data management with semantic search, people intelligence, and temp
 - **Hybrid search**: Combines FTS5 lexical search with Ollama-powered vector embeddings via Reciprocal Rank Fusion
 - **People intelligence**: Expert discovery, workload analysis, review patterns, active discussions, and code ownership overlap
 - **Timeline pipeline**: Reconstructs chronological event histories by combining search, graph traversal, and event aggregation across related entities
+- **Code provenance tracing**: Traces why code was introduced by linking files to MRs, MRs to issues, and issues to discussion threads
+- **File-level history**: Shows which MRs touched a file with rename-chain resolution and inline DiffNote snippets
+- **Surgical sync**: Sync specific issues or MRs by IID without running a full incremental sync, with preflight validation
 - **Git history linking**: Tracks merge and squash commit SHAs to connect MRs with git history
 - **File change tracking**: Records which files each MR touches, enabling file-level history queries
 - **Raw payload storage**: Preserves original GitLab API responses for debugging
@@ -21,9 +24,12 @@ Local GitLab data management with semantic search, people intelligence, and temp
 - **Resource event history**: Tracks state changes, label events, and milestone events for issues and MRs
 - **Note querying**: Rich filtering over discussion notes by author, type, path, resolution status, time range, and body content
 - **Discussion drift detection**: Semantic analysis of how discussions diverge from original issue intent
+- **Automated sync scheduling**: Cron-based automatic syncing with configurable intervals (Unix)
+- **Token management**: Secure interactive or piped token storage with masked display
 - **Robot mode**: Machine-readable JSON output with structured errors, meaningful exit codes, and actionable recovery steps
 - **Error tolerance**: Auto-corrects common CLI mistakes (case, typos, single-dash flags, value casing) with teaching feedback
 - **Observability**: Verbosity controls, JSON log format, structured metrics, and stage timing
+- **Icon system**: Configurable icon sets (Nerd Fonts, Unicode, ASCII) with automatic detection
 
 ## Installation
 
@@ -77,6 +83,15 @@ lore timeline "deployment"
 # Timeline for a specific issue
 lore timeline issue:42
 
+# Why was this file changed? (file -> MR -> issue -> discussion)
+lore trace src/features/auth/login.ts
+
+# Which MRs touched this file?
+lore file-history src/features/auth/
+
+# Sync a specific issue without full sync
+lore sync --issue 42 -p group/repo
+
 # Query notes by author
 lore notes --author alice --since 7d
 
@@ -190,6 +205,8 @@ Create a personal access token with `read_api` scope:
 | `XDG_DATA_HOME` | XDG Base Directory for data (fallback: `~/.local/share`) | No |
 | `NO_COLOR` | Disable color output when set (any value) | No |
 | `CLICOLOR` | Standard color control (0 to disable) | No |
+| `LORE_ICONS` | Override icon set: `nerd`, `unicode`, or `ascii` | No |
+| `NERD_FONTS` | Enable Nerd Font icons when set to a non-empty value | No |
 | `RUST_LOG` | Logging level filter (e.g., `lore=debug`) | No |
 
 ## Commands
@@ -353,12 +370,13 @@ Shows: total DiffNotes, categorized by code area with percentage breakdown.
 
 #### Active Mode
 
-Surface unresolved discussions needing attention.
+Surface unresolved discussions needing attention. By default, only discussions on open issues and non-merged MRs are shown.
 
 ```bash
 lore who --active                     # Unresolved discussions (last 7 days)
 lore who --active --since 30d        # Wider time window
 lore who --active -p group/repo      # Scoped to project
+lore who --active --include-closed   # Include discussions on closed/merged entities
 ```
 
 Shows: discussion threads with participants and last activity timestamps.
@@ -382,6 +400,7 @@ 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) |
@@ -465,8 +484,6 @@ lore notes --contains "TODO"                 # Substring search in note body
 lore notes --include-system                  # Include system-generated notes
 lore notes --since 2w --until 2024-12-31     # Time-bounded range
 lore notes --sort updated --asc              # Sort by update time, ascending
-lore notes --format csv                      # CSV output
-lore notes --format jsonl                    # Line-delimited JSON
 lore notes -o                                # Open first result in browser
 
 # Field selection (robot mode)
@@ -493,9 +510,52 @@ lore -J notes --fields minimal               # Compact: id, author_username, bod
 | `--resolution` | Filter by resolution status (`any`, `unresolved`, `resolved`) |
 | `--sort` | Sort by `created` (default) or `updated` |
 | `--asc` | Sort ascending (default: descending) |
-| `--format` | Output format: `table` (default), `json`, `jsonl`, `csv` |
 | `-o` / `--open` | Open first result in browser |
 
+### `lore file-history`
+
+Show which merge requests touched a file, with rename-chain resolution and optional DiffNote discussion snippets.
+
+```bash
+lore file-history src/main.rs                         # MRs that touched this file
+lore file-history src/auth/ -p group/repo             # Scoped to project
+lore file-history src/foo.rs --discussions             # Include DiffNote snippets
+lore file-history src/bar.rs --no-follow-renames       # Skip rename chain resolution
+lore file-history src/bar.rs --merged                  # Only merged MRs
+lore file-history src/bar.rs -n 100                    # More results
+```
+
+Rename-chain resolution follows file renames through `mr_file_changes` so that querying a renamed file also surfaces MRs that touched previous names. Disable with `--no-follow-renames`.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-p` / `--project` | all | Scope to a specific project (fuzzy match) |
+| `--discussions` | off | Include DiffNote discussion snippets on the file |
+| `--no-follow-renames` | off | Disable rename chain resolution |
+| `--merged` | off | Only show merged MRs |
+| `-n` / `--limit` | `50` | Maximum results |
+
+### `lore trace`
+
+Trace why code was introduced by building provenance chains: file -> MR -> issue -> discussion threads.
+
+```bash
+lore trace src/main.rs                         # Why was this file changed?
+lore trace src/auth/ -p group/repo             # Scoped to project
+lore trace src/foo.rs --discussions             # Include DiffNote context
+lore trace src/bar.rs:42                        # Line hint (future Tier 2)
+lore trace src/bar.rs --no-follow-renames       # Skip rename chain resolution
+```
+
+Each trace chain links a file change to the MR that introduced it, the issue(s) that motivated it (via "closes" references), and the discussion threads on those entities. Line-level hints (`:line` suffix) are accepted but produce an advisory message until Tier 2 git-blame integration is available.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-p` / `--project` | all | Scope to a specific project (fuzzy match) |
+| `--discussions` | off | Include DiffNote discussion snippets |
+| `--no-follow-renames` | off | Disable rename chain resolution |
+| `-n` / `--limit` | `20` | Maximum trace chains to display |
+
 ### `lore drift`
 
 Detect discussion divergence from the original intent of an issue by comparing the semantic similarity of discussion content against the issue description.
@@ -506,9 +566,34 @@ lore drift issues 42 --threshold 0.6        # Higher threshold (stricter)
 lore drift issues 42 -p group/repo          # Scope to project
 ```
 
+### `lore cron`
+
+Manage cron-based automatic syncing (Unix only). Installs a crontab entry that runs `lore sync --lock -q` at a configurable interval.
+
+```bash
+lore cron install                     # Install cron job (every 8 minutes)
+lore cron install --interval 15       # Custom interval in minutes
+lore cron status                      # Check if cron is installed
+lore cron uninstall                   # Remove cron job
+```
+
+The `--lock` flag on the auto-sync ensures that if a sync is already running, the cron invocation exits cleanly rather than competing for the database lock.
+
+### `lore token`
+
+Manage the stored GitLab token. Supports interactive entry with validation, non-interactive piped input, and masked display.
+
+```bash
+lore token set                         # Interactive token entry + validation
+lore token set --token glpat-xxx       # Non-interactive token storage
+echo glpat-xxx | lore token set        # Pipe token from stdin
+lore token show                        # Show token (masked)
+lore token show --unmask               # Show full token
+```
+
 ### `lore sync`
 
-Run the full sync pipeline: ingest from GitLab (including work item status enrichment via GraphQL), generate searchable documents, and compute embeddings.
+Run the full sync pipeline: ingest from GitLab (including work item status enrichment via GraphQL), generate searchable documents, and compute embeddings. Supports both incremental (cursor-based) and surgical (per-IID) modes.
 
 ```bash
 lore sync                    # Full pipeline
@@ -518,11 +603,29 @@ lore sync --no-embed         # Skip embedding step
 lore sync --no-docs          # Skip document regeneration
 lore sync --no-events        # Skip resource event fetching
 lore sync --no-file-changes  # Skip MR file change fetching
+lore sync --no-status        # Skip work-item status enrichment via GraphQL
 lore sync --dry-run          # Preview what would be synced
+lore sync --timings          # Show detailed timing breakdown per stage
+lore sync --lock             # Acquire file lock (skip if another sync is running)
+
+# Surgical sync: fetch specific entities by IID
+lore sync --issue 42 -p group/repo               # Sync a single issue
+lore sync --mr 99 -p group/repo                  # Sync a single MR
+lore sync --issue 42 --mr 99 -p group/repo       # Mix issues and MRs
+lore sync --issue 1 --issue 2 -p group/repo      # Multiple issues
+lore sync --issue 42 -p group/repo --preflight-only  # Validate without writing
 ```
 
 The sync command displays animated progress bars for each stage and outputs timing metrics on completion. In robot mode (`-J`), detailed stage timing is included in the JSON response.
 
+#### Surgical Sync
+
+When `--issue` or `--mr` flags are provided, sync switches to surgical mode which fetches only the specified entities and their dependents (discussions, events, file changes) from GitLab. This is faster than a full incremental sync and useful for refreshing specific entities on demand.
+
+Surgical mode requires `-p` / `--project` to scope the operation. Each entity goes through preflight validation against the GitLab API, then ingestion, document regeneration, and embedding. Entities that haven't changed since the last sync are skipped (TOCTOU check).
+
+Use `--preflight-only` to validate that entities exist on GitLab without writing to the database.
+
 ### `lore ingest`
 
 Sync data from GitLab to local database. Runs only the ingestion step (no doc generation or embeddings). For issue ingestion, this includes a status enrichment phase that fetches work item statuses via the GitLab GraphQL API.
@@ -753,7 +856,7 @@ The CLI auto-corrects common mistakes before parsing, emitting a teaching note t
 |-----------|---------|------|
 | Single-dash long flag | `-robot` -> `--robot` | All |
 | Case normalization | `--Robot` -> `--robot` | All |
-| Flag prefix expansion | `--proj` -> `--project` (unambiguous only) | All |
+| Flag prefix expansion | `--proj` -> `--project`, `--no-color` -> `--color never` (unambiguous only) | All |
 | Fuzzy flag match | `--projct` -> `--project` | All (threshold 0.9 in robot, 0.8 in human) |
 | Subcommand alias | `merge_requests` -> `mrs`, `robotdocs` -> `robot-docs` | All |
 | Value normalization | `--state Opened` -> `--state opened` | All |
@@ -785,7 +888,7 @@ Commands accept aliases for common variations:
 | `stats` | `stat` |
 | `status` | `st` |
 
-Unambiguous prefixes also work via subcommand inference (e.g., `lore iss` -> `lore issues`, `lore time` -> `lore timeline`).
+Unambiguous prefixes also work via subcommand inference (e.g., `lore iss` -> `lore issues`, `lore time` -> `lore timeline`, `lore tra` -> `lore trace`).
 
 ### Agent Self-Discovery
 
@@ -840,6 +943,8 @@ lore --robot <command>                    # Machine-readable JSON
 lore -J <command>                         # JSON shorthand
 lore --color never <command>              # Disable color output
 lore --color always <command>             # Force color output
+lore --icons nerd <command>               # Nerd Font icons
+lore --icons ascii <command>              # ASCII-only icons (no Unicode)
 lore -q <command>                         # Suppress non-essential output
 lore -v <command>                         # Debug logging
 lore -vv <command>                        # More verbose debug logging
@@ -847,7 +952,7 @@ lore -vvv <command>                       # Trace-level logging
 lore --log-format json <command>          # JSON-formatted log output to stderr
 ```
 
-Color output respects `NO_COLOR` and `CLICOLOR` environment variables in `auto` mode (the default).
+Color output respects `NO_COLOR` and `CLICOLOR` environment variables in `auto` mode (the default). Icon sets default to `unicode` and can be overridden via `--icons`, `LORE_ICONS`, or `NERD_FONTS` environment variables.
 
 ## Shell Completions
 
@@ -895,7 +1000,7 @@ Data is stored in SQLite with WAL mode and foreign keys enabled. Main tables:
 | `embeddings` | Vector embeddings for semantic search |
 | `dirty_sources` | Entities needing document regeneration after ingest |
 | `pending_discussion_fetches` | Queue for discussion fetch operations |
-| `sync_runs` | Audit trail of sync operations |
+| `sync_runs` | Audit trail of sync operations (supports surgical mode tracking with per-entity results) |
 | `sync_cursors` | Cursor positions for incremental sync |
 | `app_locks` | Crash-safe single-flight lock |
 | `raw_payloads` | Compressed original API responses |

acceptance-criteria.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/lore-me-spec.md

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

migrations/022_notes_query_index.sql

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

migrations/024_note_documents.sql

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

migrations/025_note_dirty_backfill.sql

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

migrations/026_scoring_indexes.sql

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

migrations/027_surgical_sync_runs.sql

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

migrations/028_discussions_mr_fk.sql

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

plans/gitlab-todos-notifications-integration.md

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

src/cli/autocorrect.rs

@@ -25,6 +25,7 @@ pub enum CorrectionRule {
     ValueNormalization,
     ValueFuzzy,
     FlagPrefix,
+    NoColorExpansion,
 }
 
 /// Result of the correction pass over raw args.
@@ -128,6 +129,11 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
             "--dry-run",
             "--no-dry-run",
             "--timings",
+            "--lock",
+            "--issue",
+            "--mr",
+            "--project",
+            "--preflight-only",
         ],
     ),
     (
@@ -177,6 +183,7 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
             "--max-evidence",
         ],
     ),
+    ("related", &["--limit", "--project"]),
     (
         "who",
         &[
@@ -203,7 +210,6 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
         &[
             "--limit",
             "--fields",
-            "--format",
             "--author",
             "--note-type",
             "--contains",
@@ -281,6 +287,20 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
     ),
     ("show", &["--project"]),
     ("reset", &["--yes"]),
+    (
+        "me",
+        &[
+            "--issues",
+            "--mrs",
+            "--activity",
+            "--since",
+            "--project",
+            "--all",
+            "--user",
+            "--fields",
+            "--reset-cursor",
+        ],
+    ),
 ];
 
 /// Valid values for enum-like flags, used for post-clap error enhancement.
@@ -424,9 +444,21 @@ pub fn correct_args(raw: Vec<String>, strict: bool) -> CorrectionResult {
         }
 
         if let Some(fixed) = try_correct(&arg, &valid, strict) {
-            let s = fixed.corrected.clone();
-            corrections.push(fixed);
-            corrected.push(s);
+            if fixed.rule == CorrectionRule::NoColorExpansion {
+                // Expand --no-color → --color never
+                corrections.push(Correction {
+                    original: fixed.original,
+                    corrected: "--color never".to_string(),
+                    rule: CorrectionRule::NoColorExpansion,
+                    confidence: 1.0,
+                });
+                corrected.push("--color".to_string());
+                corrected.push("never".to_string());
+            } else {
+                let s = fixed.corrected.clone();
+                corrections.push(fixed);
+                corrected.push(s);
+            }
         } else {
             corrected.push(arg);
         }
@@ -611,12 +643,27 @@ const CLAP_BUILTINS: &[&str] = &["--help", "--version"];
 ///
 /// When `strict` is true, fuzzy matching is disabled — only deterministic
 /// corrections (single-dash fix, case normalization) are applied.
+///
+/// Special case: `--no-color` is rewritten to `--color never` by returning
+/// the `--color` correction and letting the caller handle arg insertion.
+/// However, since we correct one arg at a time, we use `NoColorExpansion`
+/// to signal that the next phase should insert `never` after this arg.
 fn try_correct(arg: &str, valid_flags: &[&str], strict: bool) -> Option<Correction> {
     // Only attempt correction on flag-like args (starts with `-`)
     if !arg.starts_with('-') {
         return None;
     }
 
+    // Special case: --no-color → --color never (common agent/user expectation)
+    if arg.eq_ignore_ascii_case("--no-color") {
+        return Some(Correction {
+            original: arg.to_string(),
+            corrected: "--no-color".to_string(), // sentinel; expanded in correct_args
+            rule: CorrectionRule::NoColorExpansion,
+            confidence: 1.0,
+        });
+    }
+
     // B2: Never correct clap built-in flags (--help, --version)
     let flag_part_for_builtin = if let Some(eq_pos) = arg.find('=') {
         &arg[..eq_pos]
@@ -766,9 +813,21 @@ fn try_correct(arg: &str, valid_flags: &[&str], strict: bool) -> Option<Correcti
 }
 
 /// Find the best fuzzy match among valid flags for a given (lowercased) input.
+///
+/// Applies a length guard to prevent short candidates (e.g. `--for`, 5 chars
+/// including dashes) from inflating Jaro-Winkler scores against long inputs.
+/// When the input is more than 40% longer than a candidate, that candidate is
+/// excluded from fuzzy consideration (it can still match via prefix rule).
 fn best_fuzzy_match<'a>(input: &str, valid_flags: &[&'a str]) -> Option<(&'a str, f64)> {
     valid_flags
         .iter()
+        .filter(|&&flag| {
+            // Guard: skip short candidates when input is much longer.
+            // e.g. "--foobar" (8 chars) should not fuzzy-match "--for" (5 chars)
+            // Ratio: input must be within 1.4x the candidate length.
+            let max_input_len = (flag.len() as f64 * 1.4) as usize;
+            input.len() <= max_input_len
+        })
         .map(|&flag| (flag, jaro_winkler(input, flag)))
         .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal))
 }
@@ -846,6 +905,9 @@ pub fn format_teaching_note(correction: &Correction) -> String {
                 correction.corrected, correction.original
             )
         }
+        CorrectionRule::NoColorExpansion => {
+            "Use `--color never` instead of `--no-color`".to_string()
+        }
     }
 }
 
@@ -1286,6 +1348,53 @@ mod tests {
         assert!(note.contains("full flag name"));
     }
 
+    // ---- --no-color expansion ----
+
+    #[test]
+    fn no_color_expands_to_color_never() {
+        let result = correct_args(args("lore --no-color health"), false);
+        assert_eq!(result.corrections.len(), 1);
+        assert_eq!(result.corrections[0].rule, CorrectionRule::NoColorExpansion);
+        assert_eq!(result.args, args("lore --color never health"));
+    }
+
+    #[test]
+    fn no_color_case_insensitive() {
+        let result = correct_args(args("lore --No-Color issues"), false);
+        assert_eq!(result.corrections.len(), 1);
+        assert_eq!(result.args, args("lore --color never issues"));
+    }
+
+    #[test]
+    fn no_color_with_robot_mode() {
+        let result = correct_args(args("lore --robot --no-color health"), true);
+        assert_eq!(result.corrections.len(), 1);
+        assert_eq!(result.args, args("lore --robot --color never health"));
+    }
+
+    // ---- Fuzzy matching length guard ----
+
+    #[test]
+    fn foobar_does_not_match_for() {
+        // --foobar (8 chars) should NOT fuzzy-match --for (5 chars)
+        let result = correct_args(args("lore count --foobar issues"), false);
+        assert!(
+            !result.corrections.iter().any(|c| c.corrected == "--for"),
+            "expected --foobar not to match --for"
+        );
+    }
+
+    #[test]
+    fn fro_still_matches_for() {
+        // --fro (5 chars) is short enough to fuzzy-match --for (5 chars)
+        // and also qualifies as a prefix match
+        let result = correct_args(args("lore count --fro issues"), false);
+        assert!(
+            result.corrections.iter().any(|c| c.corrected == "--for"),
+            "expected --fro to match --for"
+        );
+    }
+
     // ---- Post-clap suggestion helpers ----
 
     #[test]

src/cli/commands/auth_test.rs

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

src/cli/commands/count.rs

@@ -257,7 +257,10 @@ pub fn print_event_count_json(counts: &EventCounts, elapsed_ms: u64) {
         meta: RobotMeta { elapsed_ms },
     };
 
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 pub fn print_event_count(counts: &EventCounts) {
@@ -325,7 +328,10 @@ pub fn print_count_json(result: &CountResult, elapsed_ms: u64) {
         meta: RobotMeta { elapsed_ms },
     };
 
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 pub fn print_count(result: &CountResult) {

src/cli/commands/cron.rs

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

src/cli/commands/doctor.rs

@@ -240,14 +240,14 @@ async fn check_gitlab(config: Option<&Config>) -> GitLabCheck {
         };
     };
 
-    let token = match std::env::var(&config.gitlab.token_env_var) {
-        Ok(t) if !t.trim().is_empty() => t.trim().to_string(),
-        _ => {
+    let token = match config.gitlab.resolve_token() {
+        Ok(t) => t,
+        Err(_) => {
             return GitLabCheck {
                 result: CheckResult {
                     status: CheckStatus::Error,
                     message: Some(format!(
-                        "{} not set in environment",
+                        "Token not set. Run 'lore token set' or export {}.",
                         config.gitlab.token_env_var
                     )),
                 },
@@ -257,6 +257,8 @@ async fn check_gitlab(config: Option<&Config>) -> GitLabCheck {
         }
     };
 
+    let source = config.gitlab.token_source().unwrap_or("unknown");
+
     let client = GitLabClient::new(&config.gitlab.base_url, &token, None);
 
     match client.get_current_user().await {
@@ -264,7 +266,7 @@ async fn check_gitlab(config: Option<&Config>) -> GitLabCheck {
             result: CheckResult {
                 status: CheckStatus::Ok,
                 message: Some(format!(
-                    "{} (authenticated as @{})",
+                    "{} (authenticated as @{}, token from {source})",
                     config.gitlab.base_url, user.username
                 )),
             },

src/cli/commands/drift.rs

@@ -382,7 +382,7 @@ fn extract_drift_topics(description: &str, notes: &[NoteRow], drift_idx: usize)
     }
 
     let mut sorted: Vec<(String, usize)> = freq.into_iter().collect();
-    sorted.sort_by(|a, b| b.1.cmp(&a.1));
+    sorted.sort_by_key(|b| std::cmp::Reverse(b.1));
 
     sorted
         .into_iter()

src/cli/commands/embed.rs

@@ -137,5 +137,8 @@ pub fn print_embed_json(result: &EmbedCommandResult, elapsed_ms: u64) {
         data: result,
         meta: RobotMeta { elapsed_ms },
     };
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }

src/cli/commands/file_history.rs

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

src/cli/commands/generate_docs.rs

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

src/cli/commands/ingest.rs

@@ -293,10 +293,7 @@ async fn run_ingest_inner(
     );
     lock.acquire(force)?;
 
-    let token =
-        std::env::var(&config.gitlab.token_env_var).map_err(|_| LoreError::TokenNotSet {
-            env_var: config.gitlab.token_env_var.clone(),
-        })?;
+    let token = config.gitlab.resolve_token()?;
 
     let client = GitLabClient::new(
         &config.gitlab.base_url,
@@ -982,7 +979,10 @@ pub fn print_ingest_summary_json(result: &IngestResult, elapsed_ms: u64) {
         meta: RobotMeta { elapsed_ms },
     };
 
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 pub fn print_ingest_summary(result: &IngestResult) {
@@ -1109,5 +1109,8 @@ pub fn print_dry_run_preview_json(preview: &DryRunPreview) {
         data: preview.clone(),
     };
 
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }

src/cli/commands/init.rs

@@ -1,9 +1,10 @@
 use std::fs;
+use std::io::{IsTerminal, Read};
 
-use crate::core::config::{MinimalConfig, MinimalGitLabConfig, ProjectConfig};
+use crate::core::config::{Config, MinimalConfig, MinimalGitLabConfig, ProjectConfig};
 use crate::core::db::{create_connection, run_migrations};
 use crate::core::error::{LoreError, Result};
-use crate::core::paths::{get_config_path, get_data_dir};
+use crate::core::paths::{ensure_config_permissions, get_config_path, get_data_dir};
 use crate::gitlab::{GitLabClient, GitLabProject};
 
 pub struct InitInputs {
@@ -172,3 +173,141 @@ pub async fn run_init(inputs: InitInputs, options: InitOptions) -> Result<InitRe
         default_project: inputs.default_project,
     })
 }
+
+// ── token set / show ──
+
+pub struct TokenSetResult {
+    pub username: String,
+    pub config_path: String,
+}
+
+pub struct TokenShowResult {
+    pub token: String,
+    pub source: &'static str,
+}
+
+/// Read token from --token flag or stdin, validate against GitLab, store in config.
+pub async fn run_token_set(
+    config_path_override: Option<&str>,
+    token_arg: Option<String>,
+) -> Result<TokenSetResult> {
+    let config_path = get_config_path(config_path_override);
+
+    if !config_path.exists() {
+        return Err(LoreError::ConfigNotFound {
+            path: config_path.display().to_string(),
+        });
+    }
+
+    // Resolve token value: flag > stdin > error
+    let token = if let Some(t) = token_arg {
+        t.trim().to_string()
+    } else if !std::io::stdin().is_terminal() {
+        let mut buf = String::new();
+        std::io::stdin()
+            .read_to_string(&mut buf)
+            .map_err(|e| LoreError::Other(format!("Failed to read token from stdin: {e}")))?;
+        buf.trim().to_string()
+    } else {
+        return Err(LoreError::Other(
+            "No token provided. Use --token or pipe to stdin.".to_string(),
+        ));
+    };
+
+    if token.is_empty() {
+        return Err(LoreError::Other("Token cannot be empty.".to_string()));
+    }
+
+    // Load config to get the base URL for validation
+    let config = Config::load(config_path_override)?;
+
+    // Validate token against GitLab
+    let client = GitLabClient::new(&config.gitlab.base_url, &token, None);
+    let user = client.get_current_user().await.map_err(|e| {
+        if matches!(e, LoreError::GitLabAuthFailed) {
+            LoreError::Other("Token validation failed: authentication rejected by GitLab.".into())
+        } else {
+            e
+        }
+    })?;
+
+    // Read config as raw JSON, insert token, write back
+    let content = fs::read_to_string(&config_path)
+        .map_err(|e| LoreError::Other(format!("Failed to read config file: {e}")))?;
+
+    let mut json: serde_json::Value =
+        serde_json::from_str(&content).map_err(|e| LoreError::ConfigInvalid {
+            details: format!("Invalid JSON in config file: {e}"),
+        })?;
+
+    json["gitlab"]["token"] = serde_json::Value::String(token);
+
+    let output = serde_json::to_string_pretty(&json)
+        .map_err(|e| LoreError::Other(format!("Failed to serialize config: {e}")))?;
+    fs::write(&config_path, format!("{output}\n"))?;
+
+    // Enforce permissions
+    ensure_config_permissions(&config_path);
+
+    Ok(TokenSetResult {
+        username: user.username,
+        config_path: config_path.display().to_string(),
+    })
+}
+
+/// Show the current token (masked or unmasked) and its source.
+pub fn run_token_show(config_path_override: Option<&str>, unmask: bool) -> Result<TokenShowResult> {
+    let config = Config::load(config_path_override)?;
+
+    let source = config
+        .gitlab
+        .token_source()
+        .ok_or_else(|| LoreError::TokenNotSet {
+            env_var: config.gitlab.token_env_var.clone(),
+        })?;
+
+    let token = config.gitlab.resolve_token()?;
+
+    let display_token = if unmask { token } else { mask_token(&token) };
+
+    Ok(TokenShowResult {
+        token: display_token,
+        source,
+    })
+}
+
+fn mask_token(token: &str) -> String {
+    let len = token.len();
+    if len <= 8 {
+        "*".repeat(len)
+    } else {
+        let visible = &token[..4];
+        format!("{visible}{}", "*".repeat(len - 4))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn mask_token_hides_short_tokens_completely() {
+        assert_eq!(mask_token(""), "");
+        assert_eq!(mask_token("a"), "*");
+        assert_eq!(mask_token("abcd"), "****");
+        assert_eq!(mask_token("abcdefgh"), "********");
+    }
+
+    #[test]
+    fn mask_token_reveals_first_four_chars_for_long_tokens() {
+        assert_eq!(mask_token("abcdefghi"), "abcd*****");
+        assert_eq!(mask_token("glpat-xyzABC123456"), "glpa**************");
+    }
+
+    #[test]
+    fn mask_token_boundary_at_nine_chars() {
+        // 8 chars → fully masked, 9 chars → first 4 visible
+        assert_eq!(mask_token("12345678"), "********");
+        assert_eq!(mask_token("123456789"), "1234*****");
+    }
+}

src/cli/commands/list.rs

@@ -980,59 +980,6 @@ pub fn print_list_notes_json(result: &NoteListResult, elapsed_ms: u64, fields: O
     }
 }
 
-pub fn print_list_notes_jsonl(result: &NoteListResult) {
-    for note in &result.notes {
-        let json_row = NoteListRowJson::from(note);
-        match serde_json::to_string(&json_row) {
-            Ok(json) => println!("{json}"),
-            Err(e) => eprintln!("Error serializing to JSON: {e}"),
-        }
-    }
-}
-
-/// Escape a field for RFC 4180 CSV: quote fields containing commas, quotes, or newlines.
-fn csv_escape(field: &str) -> String {
-    if field.contains(',') || field.contains('"') || field.contains('\n') || field.contains('\r') {
-        let escaped = field.replace('"', "\"\"");
-        format!("\"{escaped}\"")
-    } else {
-        field.to_string()
-    }
-}
-
-pub fn print_list_notes_csv(result: &NoteListResult) {
-    println!(
-        "id,gitlab_id,author_username,body,note_type,is_system,created_at,updated_at,position_new_path,position_new_line,noteable_type,parent_iid,project_path"
-    );
-    for note in &result.notes {
-        let body = note.body.as_deref().unwrap_or("");
-        let note_type = note.note_type.as_deref().unwrap_or("");
-        let path = note.position_new_path.as_deref().unwrap_or("");
-        let line = note
-            .position_new_line
-            .map_or(String::new(), |l| l.to_string());
-        let noteable = note.noteable_type.as_deref().unwrap_or("");
-        let parent_iid = note.parent_iid.map_or(String::new(), |i| i.to_string());
-
-        println!(
-            "{},{},{},{},{},{},{},{},{},{},{},{},{}",
-            note.id,
-            note.gitlab_id,
-            csv_escape(&note.author_username),
-            csv_escape(body),
-            csv_escape(note_type),
-            note.is_system,
-            note.created_at,
-            note.updated_at,
-            csv_escape(path),
-            line,
-            csv_escape(noteable),
-            parent_iid,
-            csv_escape(&note.project_path),
-        );
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Note query layer
 // ---------------------------------------------------------------------------

src/cli/commands/list_tests.rs

@@ -95,6 +95,8 @@ fn test_config(default_project: Option<&str>) -> Config {
         gitlab: GitLabConfig {
             base_url: "https://gitlab.example.com".to_string(),
             token_env_var: "GITLAB_TOKEN".to_string(),
+            token: None,
+            username: None,
         },
         projects: vec![ProjectConfig {
             path: "group/project".to_string(),
@@ -1269,60 +1271,6 @@ fn test_truncate_note_body() {
     assert!(result.ends_with("..."));
 }
 
-#[test]
-fn test_csv_escape_basic() {
-    assert_eq!(csv_escape("simple"), "simple");
-    assert_eq!(csv_escape("has,comma"), "\"has,comma\"");
-    assert_eq!(csv_escape("has\"quote"), "\"has\"\"quote\"");
-    assert_eq!(csv_escape("has\nnewline"), "\"has\nnewline\"");
-}
-
-#[test]
-fn test_csv_output_basic() {
-    let result = NoteListResult {
-        notes: vec![NoteListRow {
-            id: 1,
-            gitlab_id: 100,
-            author_username: "alice".to_string(),
-            body: Some("Hello, world".to_string()),
-            note_type: Some("DiffNote".to_string()),
-            is_system: false,
-            created_at: 1_000_000,
-            updated_at: 2_000_000,
-            position_new_path: Some("src/main.rs".to_string()),
-            position_new_line: Some(42),
-            position_old_path: None,
-            position_old_line: None,
-            resolvable: true,
-            resolved: false,
-            resolved_by: None,
-            noteable_type: Some("Issue".to_string()),
-            parent_iid: Some(7),
-            parent_title: Some("Test issue".to_string()),
-            project_path: "group/project".to_string(),
-        }],
-        total_count: 1,
-    };
-
-    // Verify csv_escape handles the comma in body correctly
-    let body = result.notes[0].body.as_deref().unwrap();
-    let escaped = csv_escape(body);
-    assert_eq!(escaped, "\"Hello, world\"");
-
-    // Verify the formatting helpers
-    assert_eq!(
-        format_note_type(result.notes[0].note_type.as_deref()),
-        "Diff"
-    );
-    assert_eq!(
-        format_note_parent(
-            result.notes[0].noteable_type.as_deref(),
-            result.notes[0].parent_iid,
-        ),
-        "Issue #7"
-    );
-}
-
 #[test]
 fn test_jsonl_output_one_per_line() {
     let result = NoteListResult {

src/cli/commands/me/me_tests.rs

@@ -0,0 +1,905 @@
+use super::*;
+use crate::cli::commands::me::types::{ActivityEventType, AttentionState};
+use crate::core::db::{create_connection, run_migrations};
+use crate::core::time::now_ms;
+use rusqlite::Connection;
+use std::path::Path;
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+fn setup_test_db() -> Connection {
+    let conn = create_connection(Path::new(":memory:")).unwrap();
+    run_migrations(&conn).unwrap();
+    conn
+}
+
+fn insert_project(conn: &Connection, id: i64, path: &str) {
+    conn.execute(
+        "INSERT INTO projects (id, gitlab_project_id, path_with_namespace, web_url)
+         VALUES (?1, ?2, ?3, ?4)",
+        rusqlite::params![
+            id,
+            id * 100,
+            path,
+            format!("https://git.example.com/{path}")
+        ],
+    )
+    .unwrap();
+}
+
+fn insert_issue(conn: &Connection, id: i64, project_id: i64, iid: i64, author: &str) {
+    insert_issue_with_status(
+        conn,
+        id,
+        project_id,
+        iid,
+        author,
+        "opened",
+        Some("In Progress"),
+    );
+}
+
+fn insert_issue_with_state(
+    conn: &Connection,
+    id: i64,
+    project_id: i64,
+    iid: i64,
+    author: &str,
+    state: &str,
+) {
+    // For closed issues, don't set status_name (they won't appear in dashboard anyway)
+    let status_name = if state == "opened" {
+        Some("In Progress")
+    } else {
+        None
+    };
+    insert_issue_with_status(conn, id, project_id, iid, author, state, status_name);
+}
+
+#[allow(clippy::too_many_arguments)]
+fn insert_issue_with_status(
+    conn: &Connection,
+    id: i64,
+    project_id: i64,
+    iid: i64,
+    author: &str,
+    state: &str,
+    status_name: Option<&str>,
+) {
+    let ts = now_ms();
+    conn.execute(
+        "INSERT INTO issues (id, gitlab_id, project_id, iid, title, state, status_name, author_username, created_at, updated_at, last_seen_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
+        rusqlite::params![
+            id,
+            id * 10,
+            project_id,
+            iid,
+            format!("Issue {iid}"),
+            state,
+            status_name,
+            author,
+            ts,
+            ts,
+            ts
+        ],
+    )
+    .unwrap();
+}
+
+fn insert_assignee(conn: &Connection, issue_id: i64, username: &str) {
+    conn.execute(
+        "INSERT INTO issue_assignees (issue_id, username) VALUES (?1, ?2)",
+        rusqlite::params![issue_id, username],
+    )
+    .unwrap();
+}
+
+#[allow(clippy::too_many_arguments)]
+fn insert_mr(
+    conn: &Connection,
+    id: i64,
+    project_id: i64,
+    iid: i64,
+    author: &str,
+    state: &str,
+    draft: bool,
+) {
+    let ts = now_ms();
+    conn.execute(
+        "INSERT INTO merge_requests (id, gitlab_id, project_id, iid, title, author_username, state, draft, last_seen_at, updated_at, created_at, merged_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)",
+        rusqlite::params![
+            id,
+            id * 10,
+            project_id,
+            iid,
+            format!("MR {iid}"),
+            author,
+            state,
+            i32::from(draft),
+            ts,
+            ts,
+            ts,
+            if state == "merged" { Some(ts) } else { None::<i64> }
+        ],
+    )
+    .unwrap();
+}
+
+fn insert_reviewer(conn: &Connection, mr_id: i64, username: &str) {
+    conn.execute(
+        "INSERT INTO mr_reviewers (merge_request_id, username) VALUES (?1, ?2)",
+        rusqlite::params![mr_id, username],
+    )
+    .unwrap();
+}
+
+fn insert_discussion(
+    conn: &Connection,
+    id: i64,
+    project_id: i64,
+    mr_id: Option<i64>,
+    issue_id: Option<i64>,
+) {
+    let noteable_type = if mr_id.is_some() {
+        "MergeRequest"
+    } else {
+        "Issue"
+    };
+    let ts = now_ms();
+    conn.execute(
+        "INSERT INTO discussions (id, gitlab_discussion_id, project_id, merge_request_id, issue_id, noteable_type, resolvable, resolved, last_seen_at, last_note_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, 0, 0, ?7, ?8)",
+        rusqlite::params![
+            id,
+            format!("disc-{id}"),
+            project_id,
+            mr_id,
+            issue_id,
+            noteable_type,
+            ts,
+            ts
+        ],
+    )
+    .unwrap();
+}
+
+#[allow(clippy::too_many_arguments)]
+fn insert_note_at(
+    conn: &Connection,
+    id: i64,
+    discussion_id: i64,
+    project_id: i64,
+    author: &str,
+    is_system: bool,
+    body: &str,
+    created_at: i64,
+) {
+    conn.execute(
+        "INSERT INTO notes (id, gitlab_id, discussion_id, project_id, note_type, is_system, author_username, body, created_at, updated_at, last_seen_at)
+         VALUES (?1, ?2, ?3, ?4, 'DiscussionNote', ?5, ?6, ?7, ?8, ?9, ?10)",
+        rusqlite::params![
+            id,
+            id * 10,
+            discussion_id,
+            project_id,
+            i32::from(is_system),
+            author,
+            body,
+            created_at,
+            created_at,
+            now_ms()
+        ],
+    )
+    .unwrap();
+}
+
+#[allow(clippy::too_many_arguments)]
+fn insert_state_event(
+    conn: &Connection,
+    id: i64,
+    project_id: i64,
+    issue_id: Option<i64>,
+    mr_id: Option<i64>,
+    state: &str,
+    actor: &str,
+    created_at: i64,
+) {
+    conn.execute(
+        "INSERT INTO resource_state_events (id, gitlab_id, project_id, issue_id, merge_request_id, state, actor_username, created_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+        rusqlite::params![id, id * 10, project_id, issue_id, mr_id, state, actor, created_at],
+    )
+    .unwrap();
+}
+
+#[allow(clippy::too_many_arguments)]
+fn insert_label_event(
+    conn: &Connection,
+    id: i64,
+    project_id: i64,
+    issue_id: Option<i64>,
+    mr_id: Option<i64>,
+    action: &str,
+    label_name: &str,
+    actor: &str,
+    created_at: i64,
+) {
+    conn.execute(
+        "INSERT INTO resource_label_events (id, gitlab_id, project_id, issue_id, merge_request_id, action, label_name, actor_username, created_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
+        rusqlite::params![
+            id,
+            id * 10,
+            project_id,
+            issue_id,
+            mr_id,
+            action,
+            label_name,
+            actor,
+            created_at
+        ],
+    )
+    .unwrap();
+}
+
+// ─── Open Issues Tests (Task #7) ───────────────────────────────────────────
+
+#[test]
+fn open_issues_returns_assigned_only() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_issue(&conn, 11, 1, 43, "someone");
+    // Only assign issue 42 to alice
+    insert_assignee(&conn, 10, "alice");
+
+    let results = query_open_issues(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].iid, 42);
+}
+
+#[test]
+fn open_issues_excludes_closed() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_issue_with_state(&conn, 11, 1, 43, "someone", "closed");
+    insert_assignee(&conn, 10, "alice");
+    insert_assignee(&conn, 11, "alice");
+
+    let results = query_open_issues(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].iid, 42);
+}
+
+#[test]
+fn open_issues_project_filter() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo-a");
+    insert_project(&conn, 2, "group/repo-b");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_issue(&conn, 11, 2, 43, "someone");
+    insert_assignee(&conn, 10, "alice");
+    insert_assignee(&conn, 11, "alice");
+
+    // Filter to project 1 only
+    let results = query_open_issues(&conn, "alice", &[1]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].project_path, "group/repo-a");
+}
+
+#[test]
+fn open_issues_empty_when_unassigned() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "alice");
+    // alice authored but is NOT assigned
+    let results = query_open_issues(&conn, "alice", &[]).unwrap();
+    assert!(results.is_empty());
+}
+
+// ─── Attention State Tests (Task #10) ──────────────────────────────────────
+
+#[test]
+fn attention_state_not_started_no_notes() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let results = query_open_issues(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].attention_state, AttentionState::NotStarted);
+}
+
+#[test]
+fn attention_state_needs_attention_others_replied() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    // alice comments first, then bob replies after
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t1 = now_ms() - 5000;
+    let t2 = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "alice", false, "my comment", t1);
+    insert_note_at(&conn, 201, disc_id, 1, "bob", false, "reply", t2);
+
+    let results = query_open_issues(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].attention_state, AttentionState::NeedsAttention);
+}
+
+#[test]
+fn attention_state_awaiting_response() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t1 = now_ms() - 5000;
+    let t2 = now_ms() - 1000;
+    // bob first, then alice replies (alice's latest >= others' latest)
+    insert_note_at(&conn, 200, disc_id, 1, "bob", false, "question", t1);
+    insert_note_at(&conn, 201, disc_id, 1, "alice", false, "my reply", t2);
+
+    let results = query_open_issues(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].attention_state, AttentionState::AwaitingResponse);
+}
+
+// ─── Authored MRs Tests (Task #8) ─────────────────────────────────────────
+
+#[test]
+fn authored_mrs_returns_own_only() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_mr(&conn, 10, 1, 99, "alice", "opened", false);
+    insert_mr(&conn, 11, 1, 100, "bob", "opened", false);
+
+    let results = query_authored_mrs(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].iid, 99);
+}
+
+#[test]
+fn authored_mrs_excludes_merged() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_mr(&conn, 10, 1, 99, "alice", "opened", false);
+    insert_mr(&conn, 11, 1, 100, "alice", "merged", false);
+
+    let results = query_authored_mrs(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].iid, 99);
+}
+
+#[test]
+fn authored_mrs_project_filter() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo-a");
+    insert_project(&conn, 2, "group/repo-b");
+    insert_mr(&conn, 10, 1, 99, "alice", "opened", false);
+    insert_mr(&conn, 11, 2, 100, "alice", "opened", false);
+
+    let results = query_authored_mrs(&conn, "alice", &[2]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].project_path, "group/repo-b");
+}
+
+#[test]
+fn authored_mr_not_ready_when_draft_no_reviewers() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_mr(&conn, 10, 1, 99, "alice", "opened", true);
+    // No reviewers added
+
+    let results = query_authored_mrs(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert!(results[0].draft);
+    assert_eq!(results[0].attention_state, AttentionState::NotReady);
+}
+
+#[test]
+fn authored_mr_not_ready_overridden_when_has_reviewers() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_mr(&conn, 10, 1, 99, "alice", "opened", true);
+    insert_reviewer(&conn, 10, "bob");
+
+    let results = query_authored_mrs(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    // Draft with reviewers -> not_started (not not_ready), since no one has commented
+    assert_eq!(results[0].attention_state, AttentionState::NotStarted);
+}
+
+// ─── Reviewing MRs Tests (Task #9) ────────────────────────────────────────
+
+#[test]
+fn reviewing_mrs_returns_reviewer_items() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_mr(&conn, 10, 1, 99, "bob", "opened", false);
+    insert_mr(&conn, 11, 1, 100, "charlie", "opened", false);
+    insert_reviewer(&conn, 10, "alice");
+    // alice is NOT a reviewer of MR 100
+
+    let results = query_reviewing_mrs(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].iid, 99);
+}
+
+#[test]
+fn reviewing_mrs_includes_author_username() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_mr(&conn, 10, 1, 99, "bob", "opened", false);
+    insert_reviewer(&conn, 10, "alice");
+
+    let results = query_reviewing_mrs(&conn, "alice", &[]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].author_username, Some("bob".to_string()));
+}
+
+#[test]
+fn reviewing_mrs_project_filter() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo-a");
+    insert_project(&conn, 2, "group/repo-b");
+    insert_mr(&conn, 10, 1, 99, "bob", "opened", false);
+    insert_mr(&conn, 11, 2, 100, "bob", "opened", false);
+    insert_reviewer(&conn, 10, "alice");
+    insert_reviewer(&conn, 11, "alice");
+
+    let results = query_reviewing_mrs(&conn, "alice", &[1]).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].project_path, "group/repo-a");
+}
+
+// ─── Activity Feed Tests (Tasks #11-13) ────────────────────────────────────
+
+#[test]
+fn activity_note_on_assigned_issue() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "bob", false, "a comment", t);
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].event_type, ActivityEventType::Note);
+    assert_eq!(results[0].entity_iid, 42);
+    assert_eq!(results[0].entity_type, "issue");
+    assert!(!results[0].is_own);
+}
+
+#[test]
+fn activity_note_on_authored_mr() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_mr(&conn, 10, 1, 99, "alice", "opened", false);
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, Some(10), None);
+    let t = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "bob", false, "nice work", t);
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].event_type, ActivityEventType::Note);
+    assert_eq!(results[0].entity_type, "mr");
+    assert_eq!(results[0].entity_iid, 99);
+}
+
+#[test]
+fn activity_state_event_on_my_issue() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let t = now_ms() - 1000;
+    insert_state_event(&conn, 300, 1, Some(10), None, "closed", "bob", t);
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].event_type, ActivityEventType::StatusChange);
+    assert_eq!(results[0].summary, "closed");
+}
+
+#[test]
+fn activity_label_event_on_my_issue() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let t = now_ms() - 1000;
+    insert_label_event(&conn, 400, 1, Some(10), None, "add", "bug", "bob", t);
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].event_type, ActivityEventType::LabelChange);
+    assert!(results[0].summary.contains("bug"));
+}
+
+#[test]
+fn activity_excludes_unassociated_items() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    // Issue NOT assigned to alice
+    insert_issue(&conn, 10, 1, 42, "someone");
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "bob", false, "a comment", t);
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert!(
+        results.is_empty(),
+        "should not see activity on unassigned issues"
+    );
+}
+
+#[test]
+fn activity_since_filter() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let old_t = now_ms() - 100_000_000; // ~1 day ago
+    let recent_t = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "bob", false, "old comment", old_t);
+    insert_note_at(
+        &conn,
+        201,
+        disc_id,
+        1,
+        "bob",
+        false,
+        "new comment",
+        recent_t,
+    );
+
+    // since = 50 seconds ago, should only get the recent note
+    let since = now_ms() - 50_000;
+    let results = query_activity(&conn, "alice", &[], since).unwrap();
+    assert_eq!(results.len(), 1);
+    // Notes no longer duplicate body into body_preview (summary carries the content)
+    assert_eq!(results[0].body_preview, None);
+    assert_eq!(results[0].summary, "new comment");
+}
+
+#[test]
+fn activity_project_filter() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo-a");
+    insert_project(&conn, 2, "group/repo-b");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_issue(&conn, 11, 2, 43, "someone");
+    insert_assignee(&conn, 10, "alice");
+    insert_assignee(&conn, 11, "alice");
+
+    let disc_a = 100;
+    let disc_b = 101;
+    insert_discussion(&conn, disc_a, 1, None, Some(10));
+    insert_discussion(&conn, disc_b, 2, None, Some(11));
+    let t = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_a, 1, "bob", false, "comment a", t);
+    insert_note_at(&conn, 201, disc_b, 2, "bob", false, "comment b", t);
+
+    // Filter to project 1 only
+    let results = query_activity(&conn, "alice", &[1], 0).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].project_path, "group/repo-a");
+}
+
+#[test]
+fn activity_sorted_newest_first() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t1 = now_ms() - 5000;
+    let t2 = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "bob", false, "first", t1);
+    insert_note_at(&conn, 201, disc_id, 1, "charlie", false, "second", t2);
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert_eq!(results.len(), 2);
+    assert!(
+        results[0].timestamp >= results[1].timestamp,
+        "should be sorted newest first"
+    );
+}
+
+#[test]
+fn activity_is_own_flag() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "alice", false, "my comment", t);
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert_eq!(results.len(), 1);
+    assert!(results[0].is_own);
+}
+
+// ─── Assignment Detection Tests (Task #12) ─────────────────────────────────
+
+#[test]
+fn activity_assignment_system_note() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "bob", true, "assigned to @alice", t);
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].event_type, ActivityEventType::Assign);
+}
+
+#[test]
+fn activity_unassignment_system_note() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    insert_assignee(&conn, 10, "alice");
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "bob", true, "unassigned @alice", t);
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].event_type, ActivityEventType::Unassign);
+}
+
+#[test]
+fn activity_review_request_system_note() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_mr(&conn, 10, 1, 99, "bob", "opened", false);
+    insert_reviewer(&conn, 10, "alice");
+
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, Some(10), None);
+    let t = now_ms() - 1000;
+    insert_note_at(
+        &conn,
+        200,
+        disc_id,
+        1,
+        "bob",
+        true,
+        "requested review from @alice",
+        t,
+    );
+
+    let results = query_activity(&conn, "alice", &[], 0).unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0].event_type, ActivityEventType::ReviewRequest);
+}
+
+// ─── Since-Last-Check Mention Tests ─────────────────────────────────────────
+
+#[test]
+fn since_last_check_detects_mention_with_trailing_comma() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(
+        &conn,
+        200,
+        disc_id,
+        1,
+        "bob",
+        false,
+        "please review this @alice, thanks",
+        t,
+    );
+
+    let groups = query_since_last_check(&conn, "alice", 0).unwrap();
+    let total_events: usize = groups.iter().map(|g| g.events.len()).sum();
+    assert_eq!(total_events, 1, "expected mention with comma to match");
+}
+
+#[test]
+fn since_last_check_ignores_email_like_text() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(
+        &conn,
+        200,
+        disc_id,
+        1,
+        "bob",
+        false,
+        "contact alice at foo@alice.com",
+        t,
+    );
+
+    let groups = query_since_last_check(&conn, "alice", 0).unwrap();
+    let total_events: usize = groups.iter().map(|g| g.events.len()).sum();
+    assert_eq!(total_events, 0, "email text should not count as mention");
+}
+
+#[test]
+fn since_last_check_detects_mention_with_trailing_period() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(
+        &conn,
+        200,
+        disc_id,
+        1,
+        "bob",
+        false,
+        "please review this @alice.",
+        t,
+    );
+
+    let groups = query_since_last_check(&conn, "alice", 0).unwrap();
+    let total_events: usize = groups.iter().map(|g| g.events.len()).sum();
+    assert_eq!(total_events, 1, "expected mention with period to match");
+}
+
+#[test]
+fn since_last_check_detects_mention_inside_parentheses() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(
+        &conn,
+        200,
+        disc_id,
+        1,
+        "bob",
+        false,
+        "thanks (@alice) for the update",
+        t,
+    );
+
+    let groups = query_since_last_check(&conn, "alice", 0).unwrap();
+    let total_events: usize = groups.iter().map(|g| g.events.len()).sum();
+    assert_eq!(total_events, 1, "expected parenthesized mention to match");
+}
+
+#[test]
+fn since_last_check_ignores_domain_like_text() {
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 10, 1, 42, "someone");
+    let disc_id = 100;
+    insert_discussion(&conn, disc_id, 1, None, Some(10));
+    let t = now_ms() - 1000;
+    insert_note_at(
+        &conn,
+        200,
+        disc_id,
+        1,
+        "bob",
+        false,
+        "@alice.com is the old hostname",
+        t,
+    );
+
+    let groups = query_since_last_check(&conn, "alice", 0).unwrap();
+    let total_events: usize = groups.iter().map(|g| g.events.len()).sum();
+    assert_eq!(
+        total_events, 0,
+        "domain-like text should not count as mention"
+    );
+}
+
+// ─── Helper Tests ──────────────────────────────────────────────────────────
+
+#[test]
+fn parse_attention_state_all_variants() {
+    assert_eq!(
+        parse_attention_state("needs_attention"),
+        AttentionState::NeedsAttention
+    );
+    assert_eq!(
+        parse_attention_state("not_started"),
+        AttentionState::NotStarted
+    );
+    assert_eq!(
+        parse_attention_state("awaiting_response"),
+        AttentionState::AwaitingResponse
+    );
+    assert_eq!(parse_attention_state("stale"), AttentionState::Stale);
+    assert_eq!(parse_attention_state("not_ready"), AttentionState::NotReady);
+    assert_eq!(parse_attention_state("unknown"), AttentionState::NotStarted);
+}
+
+#[test]
+fn parse_event_type_all_variants() {
+    assert_eq!(parse_event_type("note"), ActivityEventType::Note);
+    assert_eq!(parse_event_type("mention_note"), ActivityEventType::Note);
+    assert_eq!(
+        parse_event_type("status_change"),
+        ActivityEventType::StatusChange
+    );
+    assert_eq!(
+        parse_event_type("label_change"),
+        ActivityEventType::LabelChange
+    );
+    assert_eq!(parse_event_type("assign"), ActivityEventType::Assign);
+    assert_eq!(parse_event_type("unassign"), ActivityEventType::Unassign);
+    assert_eq!(
+        parse_event_type("review_request"),
+        ActivityEventType::ReviewRequest
+    );
+    assert_eq!(
+        parse_event_type("milestone_change"),
+        ActivityEventType::MilestoneChange
+    );
+    assert_eq!(parse_event_type("unknown"), ActivityEventType::Note);
+}
+
+#[test]
+fn build_project_clause_empty() {
+    assert_eq!(build_project_clause("i.project_id", &[]), "");
+}
+
+#[test]
+fn build_project_clause_single() {
+    let clause = build_project_clause("i.project_id", &[1]);
+    assert_eq!(clause, "AND i.project_id = ?2");
+}
+
+#[test]
+fn build_project_clause_multiple() {
+    let clause = build_project_clause("i.project_id", &[1, 2, 3]);
+    assert_eq!(clause, "AND i.project_id IN (?2,?3,?4)");
+}
+
+#[test]
+fn build_project_clause_at_custom_start() {
+    let clause = build_project_clause_at("p.id", &[1, 2], 3);
+    assert_eq!(clause, "AND p.id IN (?3,?4)");
+}

src/cli/commands/me/mod.rs

@@ -0,0 +1,500 @@
+pub mod queries;
+pub mod render_human;
+pub mod render_robot;
+pub mod types;
+
+use std::collections::HashSet;
+
+use rusqlite::Connection;
+
+use crate::Config;
+use crate::cli::MeArgs;
+use crate::core::cursor;
+use crate::core::db::create_connection;
+use crate::core::error::{LoreError, Result};
+use crate::core::paths::get_db_path;
+use crate::core::project::resolve_project;
+use crate::core::time::parse_since;
+
+use self::queries::{
+    query_activity, query_authored_mrs, query_open_issues, query_reviewing_mrs,
+    query_since_last_check,
+};
+use self::types::{AttentionState, MeDashboard, MeSummary, SinceLastCheck};
+
+/// Default activity lookback: 1 day in milliseconds.
+const DEFAULT_ACTIVITY_SINCE_DAYS: i64 = 1;
+const MS_PER_DAY: i64 = 24 * 60 * 60 * 1000;
+
+/// Resolve the effective username from CLI flag or config.
+///
+/// Precedence: `--user` flag > `config.gitlab.username` > error (AC-1.2).
+pub fn resolve_username<'a>(args: &'a MeArgs, config: &'a Config) -> Result<&'a str> {
+    if let Some(ref user) = args.user {
+        return Ok(user.as_str());
+    }
+    if let Some(ref username) = config.gitlab.username {
+        return Ok(username.as_str());
+    }
+    Err(LoreError::ConfigInvalid {
+        details: "No GitLab username configured. Set gitlab.username in config.json or pass --user <username>.".to_string(),
+    })
+}
+
+/// Resolve the project scope for the dashboard.
+///
+/// Returns a list of project IDs to filter by. An empty vec means "all projects".
+///
+/// Precedence (AC-8):
+/// - `--project` and `--all` both set → error (AC-8.4, clap also enforces this)
+/// - `--all` → empty vec (all projects)
+/// - `--project` → resolve to single project ID via fuzzy match
+/// - config.default_project → resolve that
+/// - no default → empty vec (all projects)
+pub fn resolve_project_scope(
+    conn: &Connection,
+    args: &MeArgs,
+    config: &Config,
+) -> Result<Vec<i64>> {
+    if args.all {
+        return Ok(Vec::new());
+    }
+    if let Some(ref project) = args.project {
+        let id = resolve_project(conn, project)?;
+        return Ok(vec![id]);
+    }
+    if let Some(ref dp) = config.default_project {
+        let id = resolve_project(conn, dp)?;
+        return Ok(vec![id]);
+    }
+    Ok(Vec::new())
+}
+
+/// Run the `lore me` personal dashboard command.
+///
+/// Orchestrates: username resolution → project scope → query execution →
+/// summary computation → dashboard assembly → rendering.
+pub fn run_me(config: &Config, args: &MeArgs, robot_mode: bool) -> Result<()> {
+    let start = std::time::Instant::now();
+    let username = resolve_username(args, config)?;
+
+    // 0. Handle --reset-cursor early return
+    if args.reset_cursor {
+        cursor::reset_cursor(username)
+            .map_err(|e| LoreError::Other(format!("reset cursor: {e}")))?;
+        let elapsed_ms = start.elapsed().as_millis() as u64;
+        if robot_mode {
+            render_robot::print_cursor_reset_json(elapsed_ms)?;
+        } else {
+            println!("Cursor reset for @{username}. Next `lore me` will establish a new baseline.");
+        }
+        return Ok(());
+    }
+
+    // 1. Open DB
+    let db_path = get_db_path(config.storage.db_path.as_deref());
+    let conn = create_connection(&db_path)?;
+
+    // 2. Check for synced data (AC-10.2)
+    let has_data: bool = conn
+        .query_row("SELECT EXISTS(SELECT 1 FROM projects LIMIT 1)", [], |row| {
+            row.get(0)
+        })
+        .unwrap_or(false);
+    if !has_data {
+        return Err(LoreError::NotFound(
+            "No synced data found. Run `lore sync` first to fetch your GitLab data.".to_string(),
+        ));
+    }
+
+    // 3. Resolve project scope
+    let project_ids = resolve_project_scope(&conn, args, config)?;
+    let single_project = project_ids.len() == 1;
+
+    // 4. Parse --since (default 1d for activity feed)
+    let since_ms = match args.since.as_deref() {
+        Some(raw) => parse_since(raw).ok_or_else(|| {
+            LoreError::Other(format!(
+                "Invalid --since value '{raw}'. Expected: 7d, 2w, 3m, YYYY-MM-DD, or Unix-ms timestamp."
+            ))
+        })?,
+        None => crate::core::time::now_ms() - DEFAULT_ACTIVITY_SINCE_DAYS * MS_PER_DAY,
+    };
+
+    // 5. Determine which sections to query
+    let show_all = args.show_all_sections();
+    let want_issues = show_all || args.issues;
+    let want_mrs = show_all || args.mrs;
+    let want_activity = show_all || args.activity;
+
+    // 6. Run queries for requested sections
+    let open_issues = if want_issues {
+        query_open_issues(&conn, username, &project_ids)?
+    } else {
+        Vec::new()
+    };
+
+    let open_mrs_authored = if want_mrs {
+        query_authored_mrs(&conn, username, &project_ids)?
+    } else {
+        Vec::new()
+    };
+
+    let reviewing_mrs = if want_mrs {
+        query_reviewing_mrs(&conn, username, &project_ids)?
+    } else {
+        Vec::new()
+    };
+
+    let activity = if want_activity {
+        query_activity(&conn, username, &project_ids, since_ms)?
+    } else {
+        Vec::new()
+    };
+
+    // 6b. Since-last-check (cursor-based inbox)
+    let cursor_ms = cursor::read_cursor(username);
+    // Capture global watermark BEFORE project filtering so --project doesn't
+    // permanently skip events from other projects.
+    let mut global_watermark: Option<i64> = None;
+    let since_last_check = if let Some(prev_cursor) = cursor_ms {
+        let groups = query_since_last_check(&conn, username, prev_cursor)?;
+        // Watermark from ALL groups (unfiltered) — this is the true high-water mark
+        global_watermark = groups.iter().map(|g| g.latest_timestamp).max();
+        // If --project was passed, filter groups by project for display only
+        let groups = if !project_ids.is_empty() {
+            filter_groups_by_project_ids(&conn, &groups, &project_ids)
+        } else {
+            groups
+        };
+        let total = groups.iter().map(|g| g.events.len()).sum();
+        Some(SinceLastCheck {
+            cursor_ms: prev_cursor,
+            groups,
+            total_event_count: total,
+        })
+    } else {
+        None // First run — no section shown
+    };
+
+    // 7. Compute summary
+    let needs_attention_count = open_issues
+        .iter()
+        .filter(|i| i.attention_state == AttentionState::NeedsAttention)
+        .count()
+        + open_mrs_authored
+            .iter()
+            .filter(|m| m.attention_state == AttentionState::NeedsAttention)
+            .count()
+        + reviewing_mrs
+            .iter()
+            .filter(|m| m.attention_state == AttentionState::NeedsAttention)
+            .count();
+
+    // Count distinct projects across all items
+    let mut project_paths: HashSet<&str> = HashSet::new();
+    for i in &open_issues {
+        project_paths.insert(&i.project_path);
+    }
+    for m in &open_mrs_authored {
+        project_paths.insert(&m.project_path);
+    }
+    for m in &reviewing_mrs {
+        project_paths.insert(&m.project_path);
+    }
+
+    let summary = MeSummary {
+        project_count: project_paths.len(),
+        open_issue_count: open_issues.len(),
+        authored_mr_count: open_mrs_authored.len(),
+        reviewing_mr_count: reviewing_mrs.len(),
+        needs_attention_count,
+    };
+
+    // 8. Assemble dashboard
+    let dashboard = MeDashboard {
+        username: username.to_string(),
+        since_ms: Some(since_ms),
+        summary,
+        open_issues,
+        open_mrs_authored,
+        reviewing_mrs,
+        activity,
+        since_last_check,
+    };
+
+    // 9. Render
+    let elapsed_ms = start.elapsed().as_millis() as u64;
+
+    if robot_mode {
+        let fields = args.fields.as_deref();
+        render_robot::print_me_json(&dashboard, elapsed_ms, fields)?;
+    } else if show_all {
+        render_human::print_me_dashboard(&dashboard, single_project);
+    } else {
+        render_human::print_me_dashboard_filtered(
+            &dashboard,
+            single_project,
+            want_issues,
+            want_mrs,
+            want_activity,
+        );
+    }
+
+    // 10. Advance cursor AFTER successful render (watermark pattern)
+    // Uses max event timestamp from UNFILTERED results so --project filtering
+    // doesn't permanently skip events from other projects.
+    let watermark = global_watermark.unwrap_or_else(crate::core::time::now_ms);
+    cursor::write_cursor(username, watermark)
+        .map_err(|e| LoreError::Other(format!("write cursor: {e}")))?;
+
+    Ok(())
+}
+
+/// Filter since-last-check groups to only those matching the given project IDs.
+/// Used when --project narrows the display scope (cursor is still global).
+fn filter_groups_by_project_ids(
+    conn: &Connection,
+    groups: &[types::SinceCheckGroup],
+    project_ids: &[i64],
+) -> Vec<types::SinceCheckGroup> {
+    // Resolve project IDs to paths for matching
+    let paths: HashSet<String> = project_ids
+        .iter()
+        .filter_map(|pid| {
+            conn.query_row(
+                "SELECT path_with_namespace FROM projects WHERE id = ?1",
+                rusqlite::params![pid],
+                |row| row.get::<_, String>(0),
+            )
+            .ok()
+        })
+        .collect();
+
+    groups
+        .iter()
+        .filter(|g| paths.contains(&g.project_path))
+        .cloned()
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::core::config::{
+        EmbeddingConfig, GitLabConfig, LoggingConfig, ProjectConfig, ScoringConfig, StorageConfig,
+        SyncConfig,
+    };
+    use crate::core::db::{create_connection, run_migrations};
+    use std::path::Path;
+
+    fn test_config(username: Option<&str>) -> Config {
+        Config {
+            gitlab: GitLabConfig {
+                base_url: "https://gitlab.example.com".to_string(),
+                token_env_var: "GITLAB_TOKEN".to_string(),
+                token: None,
+                username: username.map(String::from),
+            },
+            projects: vec![ProjectConfig {
+                path: "group/project".to_string(),
+            }],
+            default_project: None,
+            sync: SyncConfig::default(),
+            storage: StorageConfig::default(),
+            embedding: EmbeddingConfig::default(),
+            logging: LoggingConfig::default(),
+            scoring: ScoringConfig::default(),
+        }
+    }
+
+    fn test_args(user: Option<&str>) -> MeArgs {
+        MeArgs {
+            issues: false,
+            mrs: false,
+            activity: false,
+            since: None,
+            project: None,
+            all: false,
+            user: user.map(String::from),
+            fields: None,
+            reset_cursor: false,
+        }
+    }
+
+    #[test]
+    fn resolve_username_cli_flag_wins() {
+        let config = test_config(Some("config-user"));
+        let args = test_args(Some("cli-user"));
+        let result = resolve_username(&args, &config).unwrap();
+        assert_eq!(result, "cli-user");
+    }
+
+    #[test]
+    fn resolve_username_falls_back_to_config() {
+        let config = test_config(Some("config-user"));
+        let args = test_args(None);
+        let result = resolve_username(&args, &config).unwrap();
+        assert_eq!(result, "config-user");
+    }
+
+    #[test]
+    fn resolve_username_errors_when_both_absent() {
+        let config = test_config(None);
+        let args = test_args(None);
+        let err = resolve_username(&args, &config).unwrap_err();
+        let msg = err.to_string();
+        assert!(msg.contains("username"), "unexpected error: {msg}");
+        assert!(msg.contains("--user"), "should suggest --user flag: {msg}");
+    }
+
+    fn test_config_with_default_project(
+        username: Option<&str>,
+        default_project: Option<&str>,
+    ) -> Config {
+        Config {
+            gitlab: GitLabConfig {
+                base_url: "https://gitlab.example.com".to_string(),
+                token_env_var: "GITLAB_TOKEN".to_string(),
+                token: None,
+                username: username.map(String::from),
+            },
+            projects: vec![
+                ProjectConfig {
+                    path: "group/project".to_string(),
+                },
+                ProjectConfig {
+                    path: "other/repo".to_string(),
+                },
+            ],
+            default_project: default_project.map(String::from),
+            sync: SyncConfig::default(),
+            storage: StorageConfig::default(),
+            embedding: EmbeddingConfig::default(),
+            logging: LoggingConfig::default(),
+            scoring: ScoringConfig::default(),
+        }
+    }
+
+    fn setup_test_db() -> Connection {
+        let conn = create_connection(Path::new(":memory:")).unwrap();
+        run_migrations(&conn).unwrap();
+        conn.execute(
+            "INSERT INTO projects (gitlab_project_id, path_with_namespace, web_url)
+             VALUES (1, 'group/project', 'https://gitlab.example.com/group/project')",
+            [],
+        )
+        .unwrap();
+        conn.execute(
+            "INSERT INTO projects (gitlab_project_id, path_with_namespace, web_url)
+             VALUES (2, 'other/repo', 'https://gitlab.example.com/other/repo')",
+            [],
+        )
+        .unwrap();
+        conn
+    }
+
+    #[test]
+    fn resolve_project_scope_all_flag_returns_empty() {
+        let conn = setup_test_db();
+        let config = test_config(Some("jdoe"));
+        let mut args = test_args(None);
+        args.all = true;
+        let ids = resolve_project_scope(&conn, &args, &config).unwrap();
+        assert!(ids.is_empty(), "expected empty for --all, got {ids:?}");
+    }
+
+    #[test]
+    fn resolve_project_scope_project_flag_resolves() {
+        let conn = setup_test_db();
+        let config = test_config(Some("jdoe"));
+        let mut args = test_args(None);
+        args.project = Some("group/project".to_string());
+        let ids = resolve_project_scope(&conn, &args, &config).unwrap();
+        assert_eq!(ids.len(), 1);
+    }
+
+    #[test]
+    fn resolve_project_scope_default_project() {
+        let conn = setup_test_db();
+        let config = test_config_with_default_project(Some("jdoe"), Some("other/repo"));
+        let args = test_args(None);
+        let ids = resolve_project_scope(&conn, &args, &config).unwrap();
+        assert_eq!(ids.len(), 1);
+    }
+
+    #[test]
+    fn resolve_project_scope_no_default_returns_empty() {
+        let conn = setup_test_db();
+        let config = test_config(Some("jdoe"));
+        let args = test_args(None);
+        let ids = resolve_project_scope(&conn, &args, &config).unwrap();
+        assert!(ids.is_empty(), "expected empty, got {ids:?}");
+    }
+
+    #[test]
+    fn resolve_project_scope_project_flag_fuzzy_match() {
+        let conn = setup_test_db();
+        let config = test_config(Some("jdoe"));
+        let mut args = test_args(None);
+        args.project = Some("project".to_string());
+        let ids = resolve_project_scope(&conn, &args, &config).unwrap();
+        assert_eq!(ids.len(), 1);
+    }
+
+    #[test]
+    fn resolve_project_scope_all_overrides_default_project() {
+        let conn = setup_test_db();
+        let config = test_config_with_default_project(Some("jdoe"), Some("group/project"));
+        let mut args = test_args(None);
+        args.all = true;
+        let ids = resolve_project_scope(&conn, &args, &config).unwrap();
+        assert!(
+            ids.is_empty(),
+            "expected --all to override default_project, got {ids:?}"
+        );
+    }
+
+    #[test]
+    fn resolve_project_scope_project_flag_overrides_default() {
+        let conn = setup_test_db();
+        let config = test_config_with_default_project(Some("jdoe"), Some("group/project"));
+        let mut args = test_args(None);
+        args.project = Some("other/repo".to_string());
+        let ids = resolve_project_scope(&conn, &args, &config).unwrap();
+        assert_eq!(ids.len(), 1, "expected --project to override default");
+        // Verify it resolved the explicit project, not the default
+        let resolved_path: String = conn
+            .query_row(
+                "SELECT path_with_namespace FROM projects WHERE id = ?1",
+                rusqlite::params![ids[0]],
+                |row| row.get(0),
+            )
+            .unwrap();
+        assert_eq!(resolved_path, "other/repo");
+    }
+
+    #[test]
+    fn resolve_project_scope_unknown_project_errors() {
+        let conn = setup_test_db();
+        let config = test_config(Some("jdoe"));
+        let mut args = test_args(None);
+        args.project = Some("nonexistent/project".to_string());
+        let err = resolve_project_scope(&conn, &args, &config).unwrap_err();
+        let msg = err.to_string();
+        assert!(msg.contains("not found"), "expected not found error: {msg}");
+    }
+
+    #[test]
+    fn show_all_sections_true_when_no_flags() {
+        let args = test_args(None);
+        assert!(args.show_all_sections());
+    }
+
+    #[test]
+    fn show_all_sections_false_with_issues_flag() {
+        let mut args = test_args(None);
+        args.issues = true;
+        assert!(!args.show_all_sections());
+    }
+}

src/cli/commands/me/queries.rs

@@ -0,0 +1,838 @@
+// ─── Query Functions ────────────────────────────────────────────────────────
+//
+// SQL queries powering the `lore me` dashboard.
+// Each function takes &Connection, username, optional project scope,
+// and returns Result<Vec<StructType>>.
+
+use rusqlite::Connection;
+
+use crate::core::error::Result;
+
+use regex::Regex;
+use std::collections::HashMap;
+
+use super::types::{
+    ActivityEventType, AttentionState, MeActivityEvent, MeIssue, MeMr, SinceCheckEvent,
+    SinceCheckGroup,
+};
+
+/// Stale threshold: items with no activity for 30 days are marked "stale".
+const STALE_THRESHOLD_MS: i64 = 30 * 24 * 3600 * 1000;
+
+// ─── Open Issues (AC-5.1, Task #7) ─────────────────────────────────────────
+
+/// Query open issues assigned to the user via issue_assignees.
+/// Returns issues sorted by attention state priority, then by most recently updated.
+/// Attention state is computed inline using CTE-based note timestamp comparison.
+pub fn query_open_issues(
+    conn: &Connection,
+    username: &str,
+    project_ids: &[i64],
+) -> Result<Vec<MeIssue>> {
+    let project_clause = build_project_clause("i.project_id", project_ids);
+
+    let sql = format!(
+        "WITH note_ts AS (
+            SELECT d.issue_id,
+                MAX(CASE WHEN n.author_username = ?1 THEN n.created_at END) AS my_ts,
+                MAX(CASE WHEN n.author_username != ?1 THEN n.created_at END) AS others_ts,
+                MAX(n.created_at) AS any_ts
+            FROM notes n
+            JOIN discussions d ON n.discussion_id = d.id
+            WHERE n.is_system = 0 AND d.issue_id IS NOT NULL
+            GROUP BY d.issue_id
+        )
+        SELECT i.iid, i.title, p.path_with_namespace, i.status_name, i.updated_at, i.web_url,
+            CASE
+                WHEN nt.any_ts IS NOT NULL AND nt.any_ts < (strftime('%s', 'now') * 1000 - {stale_ms})
+                    THEN 'stale'
+                WHEN nt.others_ts IS NOT NULL AND (nt.my_ts IS NULL OR nt.others_ts > nt.my_ts)
+                    THEN 'needs_attention'
+                WHEN nt.my_ts IS NOT NULL AND nt.my_ts >= COALESCE(nt.others_ts, 0)
+                    THEN 'awaiting_response'
+                ELSE 'not_started'
+            END AS attention_state
+        FROM issues i
+        JOIN issue_assignees ia ON ia.issue_id = i.id
+        JOIN projects p ON i.project_id = p.id
+        LEFT JOIN note_ts nt ON nt.issue_id = i.id
+        WHERE ia.username = ?1
+          AND i.state = 'opened'
+          AND (i.status_name COLLATE NOCASE IN ('In Progress', 'In Review') OR i.status_name IS NULL)
+          {project_clause}
+        ORDER BY
+            CASE
+                WHEN nt.others_ts IS NOT NULL AND (nt.my_ts IS NULL OR nt.others_ts > nt.my_ts)
+                    AND (nt.any_ts IS NULL OR nt.any_ts >= (strftime('%s', 'now') * 1000 - {stale_ms}))
+                    THEN 0
+                WHEN nt.any_ts IS NULL AND nt.my_ts IS NULL
+                    THEN 1
+                WHEN nt.my_ts IS NOT NULL AND nt.my_ts >= COALESCE(nt.others_ts, 0)
+                    AND (nt.any_ts IS NULL OR nt.any_ts >= (strftime('%s', 'now') * 1000 - {stale_ms}))
+                    THEN 2
+                WHEN nt.any_ts IS NOT NULL AND nt.any_ts < (strftime('%s', 'now') * 1000 - {stale_ms})
+                    THEN 3
+                ELSE 1
+            END,
+            i.updated_at DESC",
+        stale_ms = STALE_THRESHOLD_MS,
+    );
+
+    let params = build_params(username, project_ids);
+    let param_refs: Vec<&dyn rusqlite::types::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+
+    let mut stmt = conn.prepare(&sql)?;
+    let rows = stmt.query_map(param_refs.as_slice(), |row| {
+        let attention_str: String = row.get(6)?;
+        Ok(MeIssue {
+            iid: row.get(0)?,
+            title: row.get::<_, Option<String>>(1)?.unwrap_or_default(),
+            project_path: row.get(2)?,
+            status_name: row.get(3)?,
+            updated_at: row.get(4)?,
+            web_url: row.get(5)?,
+            attention_state: parse_attention_state(&attention_str),
+            labels: Vec::new(),
+        })
+    })?;
+
+    let mut issues: Vec<MeIssue> = rows.collect::<std::result::Result<Vec<_>, _>>()?;
+    populate_issue_labels(conn, &mut issues)?;
+    Ok(issues)
+}
+
+// ─── Authored MRs (AC-5.2, Task #8) ────────────────────────────────────────
+
+/// Query open MRs authored by the user.
+pub fn query_authored_mrs(
+    conn: &Connection,
+    username: &str,
+    project_ids: &[i64],
+) -> Result<Vec<MeMr>> {
+    let project_clause = build_project_clause("m.project_id", project_ids);
+
+    let sql = format!(
+        "WITH note_ts AS (
+            SELECT d.merge_request_id,
+                MAX(CASE WHEN n.author_username = ?1 THEN n.created_at END) AS my_ts,
+                MAX(CASE WHEN n.author_username != ?1 THEN n.created_at END) AS others_ts,
+                MAX(n.created_at) AS any_ts
+            FROM notes n
+            JOIN discussions d ON n.discussion_id = d.id
+            WHERE n.is_system = 0 AND d.merge_request_id IS NOT NULL
+            GROUP BY d.merge_request_id
+        )
+        SELECT m.iid, m.title, p.path_with_namespace, m.draft, m.detailed_merge_status,
+            m.updated_at, m.web_url,
+            CASE
+                WHEN m.draft = 1 AND NOT EXISTS (
+                    SELECT 1 FROM mr_reviewers WHERE merge_request_id = m.id
+                ) THEN 'not_ready'
+                WHEN nt.any_ts IS NOT NULL AND nt.any_ts < (strftime('%s', 'now') * 1000 - {stale_ms})
+                    THEN 'stale'
+                WHEN nt.others_ts IS NOT NULL AND (nt.my_ts IS NULL OR nt.others_ts > nt.my_ts)
+                    THEN 'needs_attention'
+                WHEN nt.my_ts IS NOT NULL AND nt.my_ts >= COALESCE(nt.others_ts, 0)
+                    THEN 'awaiting_response'
+                ELSE 'not_started'
+            END AS attention_state
+        FROM merge_requests m
+        JOIN projects p ON m.project_id = p.id
+        LEFT JOIN note_ts nt ON nt.merge_request_id = m.id
+        WHERE m.author_username = ?1
+          AND m.state = 'opened'
+          {project_clause}
+        ORDER BY
+            CASE
+                WHEN m.draft = 1 AND NOT EXISTS (SELECT 1 FROM mr_reviewers WHERE merge_request_id = m.id) THEN 4
+                WHEN nt.others_ts IS NOT NULL AND (nt.my_ts IS NULL OR nt.others_ts > nt.my_ts)
+                    AND (nt.any_ts IS NULL OR nt.any_ts >= (strftime('%s', 'now') * 1000 - {stale_ms})) THEN 0
+                WHEN nt.any_ts IS NULL AND nt.my_ts IS NULL THEN 1
+                WHEN nt.my_ts IS NOT NULL AND nt.my_ts >= COALESCE(nt.others_ts, 0)
+                    AND (nt.any_ts IS NULL OR nt.any_ts >= (strftime('%s', 'now') * 1000 - {stale_ms})) THEN 2
+                WHEN nt.any_ts IS NOT NULL AND nt.any_ts < (strftime('%s', 'now') * 1000 - {stale_ms}) THEN 3
+                ELSE 1
+            END,
+            m.updated_at DESC",
+        stale_ms = STALE_THRESHOLD_MS,
+    );
+
+    let params = build_params(username, project_ids);
+    let param_refs: Vec<&dyn rusqlite::types::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+
+    let mut stmt = conn.prepare(&sql)?;
+    let rows = stmt.query_map(param_refs.as_slice(), |row| {
+        let attention_str: String = row.get(7)?;
+        Ok(MeMr {
+            iid: row.get(0)?,
+            title: row.get::<_, Option<String>>(1)?.unwrap_or_default(),
+            project_path: row.get(2)?,
+            draft: row.get::<_, i32>(3)? != 0,
+            detailed_merge_status: row.get(4)?,
+            updated_at: row.get(5)?,
+            web_url: row.get(6)?,
+            attention_state: parse_attention_state(&attention_str),
+            author_username: None,
+            labels: Vec::new(),
+        })
+    })?;
+
+    let mut mrs: Vec<MeMr> = rows.collect::<std::result::Result<Vec<_>, _>>()?;
+    populate_mr_labels(conn, &mut mrs)?;
+    Ok(mrs)
+}
+
+// ─── Reviewing MRs (AC-5.3, Task #9) ───────────────────────────────────────
+
+/// Query open MRs where user is a reviewer.
+pub fn query_reviewing_mrs(
+    conn: &Connection,
+    username: &str,
+    project_ids: &[i64],
+) -> Result<Vec<MeMr>> {
+    let project_clause = build_project_clause("m.project_id", project_ids);
+
+    let sql = format!(
+        "WITH note_ts AS (
+            SELECT d.merge_request_id,
+                MAX(CASE WHEN n.author_username = ?1 THEN n.created_at END) AS my_ts,
+                MAX(CASE WHEN n.author_username != ?1 THEN n.created_at END) AS others_ts,
+                MAX(n.created_at) AS any_ts
+            FROM notes n
+            JOIN discussions d ON n.discussion_id = d.id
+            WHERE n.is_system = 0 AND d.merge_request_id IS NOT NULL
+            GROUP BY d.merge_request_id
+        )
+        SELECT m.iid, m.title, p.path_with_namespace, m.draft, m.detailed_merge_status,
+            m.author_username, m.updated_at, m.web_url,
+            CASE
+                -- not_ready is impossible here: JOIN mr_reviewers guarantees a reviewer exists
+                WHEN nt.any_ts IS NOT NULL AND nt.any_ts < (strftime('%s', 'now') * 1000 - {stale_ms})
+                    THEN 'stale'
+                WHEN nt.others_ts IS NOT NULL AND (nt.my_ts IS NULL OR nt.others_ts > nt.my_ts)
+                    THEN 'needs_attention'
+                WHEN nt.my_ts IS NOT NULL AND nt.my_ts >= COALESCE(nt.others_ts, 0)
+                    THEN 'awaiting_response'
+                ELSE 'not_started'
+            END AS attention_state
+        FROM merge_requests m
+        JOIN mr_reviewers r ON r.merge_request_id = m.id
+        JOIN projects p ON m.project_id = p.id
+        LEFT JOIN note_ts nt ON nt.merge_request_id = m.id
+        WHERE r.username = ?1
+          AND m.state = 'opened'
+          {project_clause}
+        ORDER BY
+            CASE
+                WHEN nt.others_ts IS NOT NULL AND (nt.my_ts IS NULL OR nt.others_ts > nt.my_ts)
+                    AND (nt.any_ts IS NULL OR nt.any_ts >= (strftime('%s', 'now') * 1000 - {stale_ms})) THEN 0
+                WHEN nt.any_ts IS NULL AND nt.my_ts IS NULL THEN 1
+                WHEN nt.my_ts IS NOT NULL AND nt.my_ts >= COALESCE(nt.others_ts, 0)
+                    AND (nt.any_ts IS NULL OR nt.any_ts >= (strftime('%s', 'now') * 1000 - {stale_ms})) THEN 2
+                WHEN nt.any_ts IS NOT NULL AND nt.any_ts < (strftime('%s', 'now') * 1000 - {stale_ms}) THEN 3
+                ELSE 1
+            END,
+            m.updated_at DESC",
+        stale_ms = STALE_THRESHOLD_MS,
+    );
+
+    let params = build_params(username, project_ids);
+    let param_refs: Vec<&dyn rusqlite::types::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+
+    let mut stmt = conn.prepare(&sql)?;
+    let rows = stmt.query_map(param_refs.as_slice(), |row| {
+        let attention_str: String = row.get(8)?;
+        Ok(MeMr {
+            iid: row.get(0)?,
+            title: row.get::<_, Option<String>>(1)?.unwrap_or_default(),
+            project_path: row.get(2)?,
+            draft: row.get::<_, i32>(3)? != 0,
+            detailed_merge_status: row.get(4)?,
+            author_username: row.get(5)?,
+            updated_at: row.get(6)?,
+            web_url: row.get(7)?,
+            attention_state: parse_attention_state(&attention_str),
+            labels: Vec::new(),
+        })
+    })?;
+
+    let mut mrs: Vec<MeMr> = rows.collect::<std::result::Result<Vec<_>, _>>()?;
+    populate_mr_labels(conn, &mut mrs)?;
+    Ok(mrs)
+}
+
+// ─── Activity Feed (AC-5.4, Tasks #11-13) ──────────────────────────────────
+
+/// Query activity events on items currently associated with the user.
+/// Combines notes, state events, label events, milestone events, and
+/// assignment/reviewer system notes into a unified feed sorted newest-first.
+pub fn query_activity(
+    conn: &Connection,
+    username: &str,
+    project_ids: &[i64],
+    since_ms: i64,
+) -> Result<Vec<MeActivityEvent>> {
+    // Build project filter for activity sources.
+    // Activity params: ?1=username, ?2=since_ms, ?3+=project_ids
+    let project_clause = build_project_clause_at("p.id", project_ids, 3);
+
+    // Build the "my items" subquery fragments for issue/MR association checks.
+    // These ensure we only see activity on items CURRENTLY associated with the user
+    // AND currently open (AC-3.6). Without the state filter, activity would include
+    // events on closed/merged items that don't appear in the dashboard lists.
+    let my_issue_check = "EXISTS (
+        SELECT 1 FROM issue_assignees ia
+        JOIN issues i2 ON ia.issue_id = i2.id
+        WHERE ia.issue_id = {entity_issue_id} AND ia.username = ?1 AND i2.state = 'opened'
+    )";
+    let my_mr_check = "(
+        EXISTS (SELECT 1 FROM merge_requests mr2 WHERE mr2.id = {entity_mr_id} AND mr2.author_username = ?1 AND mr2.state = 'opened')
+        OR EXISTS (SELECT 1 FROM mr_reviewers rv
+            JOIN merge_requests mr3 ON rv.merge_request_id = mr3.id
+            WHERE rv.merge_request_id = {entity_mr_id} AND rv.username = ?1 AND mr3.state = 'opened')
+    )";
+
+    // Source 1: Human comments on my items
+    let notes_sql = format!(
+        "SELECT n.created_at, 'note',
+            CASE WHEN d.issue_id IS NOT NULL THEN 'issue' ELSE 'mr' END,
+            COALESCE(i.iid, m.iid),
+            p.path_with_namespace,
+            n.author_username,
+            CASE WHEN n.author_username = ?1 THEN 1 ELSE 0 END,
+            SUBSTR(n.body, 1, 200),
+            NULL
+        FROM notes n
+        JOIN discussions d ON n.discussion_id = d.id
+        JOIN projects p ON d.project_id = p.id
+        LEFT JOIN issues i ON d.issue_id = i.id
+        LEFT JOIN merge_requests m ON d.merge_request_id = m.id
+        WHERE n.is_system = 0
+          AND n.created_at >= ?2
+          {project_clause}
+          AND (
+            (d.issue_id IS NOT NULL AND {issue_check})
+            OR (d.merge_request_id IS NOT NULL AND {mr_check})
+          )",
+        project_clause = project_clause,
+        issue_check = my_issue_check.replace("{entity_issue_id}", "d.issue_id"),
+        mr_check = my_mr_check.replace("{entity_mr_id}", "d.merge_request_id"),
+    );
+
+    // Source 2: State events
+    let state_sql = format!(
+        "SELECT e.created_at, 'status_change',
+            CASE WHEN e.issue_id IS NOT NULL THEN 'issue' ELSE 'mr' END,
+            COALESCE(i.iid, m.iid),
+            p.path_with_namespace,
+            e.actor_username,
+            CASE WHEN e.actor_username = ?1 THEN 1 ELSE 0 END,
+            e.state,
+            NULL
+        FROM resource_state_events e
+        JOIN projects p ON e.project_id = p.id
+        LEFT JOIN issues i ON e.issue_id = i.id
+        LEFT JOIN merge_requests m ON e.merge_request_id = m.id
+        WHERE e.created_at >= ?2
+          {project_clause}
+          AND (
+            (e.issue_id IS NOT NULL AND {issue_check})
+            OR (e.merge_request_id IS NOT NULL AND {mr_check})
+          )",
+        project_clause = project_clause,
+        issue_check = my_issue_check.replace("{entity_issue_id}", "e.issue_id"),
+        mr_check = my_mr_check.replace("{entity_mr_id}", "e.merge_request_id"),
+    );
+
+    // Source 3: Label events
+    let label_sql = format!(
+        "SELECT e.created_at, 'label_change',
+            CASE WHEN e.issue_id IS NOT NULL THEN 'issue' ELSE 'mr' END,
+            COALESCE(i.iid, m.iid),
+            p.path_with_namespace,
+            e.actor_username,
+            CASE WHEN e.actor_username = ?1 THEN 1 ELSE 0 END,
+            (e.action || ' ' || COALESCE(e.label_name, '(deleted)')),
+            NULL
+        FROM resource_label_events e
+        JOIN projects p ON e.project_id = p.id
+        LEFT JOIN issues i ON e.issue_id = i.id
+        LEFT JOIN merge_requests m ON e.merge_request_id = m.id
+        WHERE e.created_at >= ?2
+          {project_clause}
+          AND (
+            (e.issue_id IS NOT NULL AND {issue_check})
+            OR (e.merge_request_id IS NOT NULL AND {mr_check})
+          )",
+        project_clause = project_clause,
+        issue_check = my_issue_check.replace("{entity_issue_id}", "e.issue_id"),
+        mr_check = my_mr_check.replace("{entity_mr_id}", "e.merge_request_id"),
+    );
+
+    // Source 4: Milestone events
+    let milestone_sql = format!(
+        "SELECT e.created_at, 'milestone_change',
+            CASE WHEN e.issue_id IS NOT NULL THEN 'issue' ELSE 'mr' END,
+            COALESCE(i.iid, m.iid),
+            p.path_with_namespace,
+            e.actor_username,
+            CASE WHEN e.actor_username = ?1 THEN 1 ELSE 0 END,
+            (e.action || ' ' || COALESCE(e.milestone_title, '(deleted)')),
+            NULL
+        FROM resource_milestone_events e
+        JOIN projects p ON e.project_id = p.id
+        LEFT JOIN issues i ON e.issue_id = i.id
+        LEFT JOIN merge_requests m ON e.merge_request_id = m.id
+        WHERE e.created_at >= ?2
+          {project_clause}
+          AND (
+            (e.issue_id IS NOT NULL AND {issue_check})
+            OR (e.merge_request_id IS NOT NULL AND {mr_check})
+          )",
+        project_clause = project_clause,
+        issue_check = my_issue_check.replace("{entity_issue_id}", "e.issue_id"),
+        mr_check = my_mr_check.replace("{entity_mr_id}", "e.merge_request_id"),
+    );
+
+    // Source 5: Assignment/reviewer system notes (AC-12)
+    let assign_sql = format!(
+        "SELECT n.created_at,
+            CASE
+                WHEN LOWER(n.body) LIKE '%assigned to @%' THEN 'assign'
+                WHEN LOWER(n.body) LIKE '%unassigned @%' THEN 'unassign'
+                WHEN LOWER(n.body) LIKE '%requested review from @%' THEN 'review_request'
+                ELSE 'assign'
+            END,
+            CASE WHEN d.issue_id IS NOT NULL THEN 'issue' ELSE 'mr' END,
+            COALESCE(i.iid, m.iid),
+            p.path_with_namespace,
+            n.author_username,
+            CASE WHEN n.author_username = ?1 THEN 1 ELSE 0 END,
+            n.body,
+            NULL
+        FROM notes n
+        JOIN discussions d ON n.discussion_id = d.id
+        JOIN projects p ON d.project_id = p.id
+        LEFT JOIN issues i ON d.issue_id = i.id
+        LEFT JOIN merge_requests m ON d.merge_request_id = m.id
+        WHERE n.is_system = 1
+          AND n.created_at >= ?2
+          {project_clause}
+          AND (
+            LOWER(n.body) LIKE '%assigned to @' || LOWER(?1) || '%'
+            OR LOWER(n.body) LIKE '%unassigned @' || LOWER(?1) || '%'
+            OR LOWER(n.body) LIKE '%requested review from @' || LOWER(?1) || '%'
+          )
+          AND (
+            (d.issue_id IS NOT NULL AND {issue_check})
+            OR (d.merge_request_id IS NOT NULL AND {mr_check})
+          )",
+        project_clause = project_clause,
+        issue_check = my_issue_check.replace("{entity_issue_id}", "d.issue_id"),
+        mr_check = my_mr_check.replace("{entity_mr_id}", "d.merge_request_id"),
+    );
+
+    let full_sql = format!(
+        "{notes_sql}
+         UNION ALL {state_sql}
+         UNION ALL {label_sql}
+         UNION ALL {milestone_sql}
+         UNION ALL {assign_sql}
+         ORDER BY 1 DESC
+         LIMIT 100"
+    );
+
+    let mut params: Vec<Box<dyn rusqlite::types::ToSql>> = Vec::new();
+    params.push(Box::new(username.to_string()));
+    params.push(Box::new(since_ms));
+    for &pid in project_ids {
+        params.push(Box::new(pid));
+    }
+    let param_refs: Vec<&dyn rusqlite::types::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+
+    let mut stmt = conn.prepare(&full_sql)?;
+    let rows = stmt.query_map(param_refs.as_slice(), |row| {
+        let event_type_str: String = row.get(1)?;
+        Ok(MeActivityEvent {
+            timestamp: row.get(0)?,
+            event_type: parse_event_type(&event_type_str),
+            entity_type: row.get(2)?,
+            entity_iid: row.get(3)?,
+            project_path: row.get(4)?,
+            actor: row.get(5)?,
+            is_own: row.get::<_, i32>(6)? != 0,
+            summary: row.get::<_, Option<String>>(7)?.unwrap_or_default(),
+            body_preview: row.get(8)?,
+        })
+    })?;
+
+    let events: Vec<MeActivityEvent> = rows.collect::<std::result::Result<Vec<_>, _>>()?;
+    Ok(events)
+}
+
+// ─── Since Last Check (cursor-based inbox) ──────────────────────────────────
+
+/// Raw row from the since-last-check UNION query.
+struct RawSinceCheckRow {
+    timestamp: i64,
+    event_type: String,
+    entity_type: String,
+    entity_iid: i64,
+    entity_title: String,
+    project_path: String,
+    actor: Option<String>,
+    summary: String,
+    body_preview: Option<String>,
+    is_mention_source: bool,
+    mention_body: Option<String>,
+}
+
+/// Query actionable events from others since `cursor_ms`.
+/// Returns events from three sources:
+/// 1. Others' comments on my open items
+/// 2. @mentions on any item (not restricted to my items)
+/// 3. Assignment/review-request system notes mentioning me
+pub fn query_since_last_check(
+    conn: &Connection,
+    username: &str,
+    cursor_ms: i64,
+) -> Result<Vec<SinceCheckGroup>> {
+    // Build the "my items" subquery fragments (reused from activity).
+    let my_issue_check = "EXISTS (
+        SELECT 1 FROM issue_assignees ia
+        JOIN issues i2 ON ia.issue_id = i2.id
+        WHERE ia.issue_id = {entity_issue_id} AND ia.username = ?1 AND i2.state = 'opened'
+    )";
+    let my_mr_check = "(
+        EXISTS (SELECT 1 FROM merge_requests mr2 WHERE mr2.id = {entity_mr_id} AND mr2.author_username = ?1 AND mr2.state = 'opened')
+        OR EXISTS (SELECT 1 FROM mr_reviewers rv
+            JOIN merge_requests mr3 ON rv.merge_request_id = mr3.id
+            WHERE rv.merge_request_id = {entity_mr_id} AND rv.username = ?1 AND mr3.state = 'opened')
+    )";
+
+    // Source 1: Others' comments on my open items
+    let source1 = format!(
+        "SELECT n.created_at, 'note',
+            CASE WHEN d.issue_id IS NOT NULL THEN 'issue' ELSE 'mr' END,
+            COALESCE(i.iid, m.iid),
+            COALESCE(i.title, m.title),
+            p.path_with_namespace,
+            n.author_username,
+            SUBSTR(n.body, 1, 200),
+            NULL,
+            0,
+            NULL
+        FROM notes n
+        JOIN discussions d ON n.discussion_id = d.id
+        JOIN projects p ON d.project_id = p.id
+        LEFT JOIN issues i ON d.issue_id = i.id
+        LEFT JOIN merge_requests m ON d.merge_request_id = m.id
+        WHERE n.is_system = 0
+          AND n.created_at > ?2
+          AND n.author_username != ?1
+          AND (
+            (d.issue_id IS NOT NULL AND {issue_check})
+            OR (d.merge_request_id IS NOT NULL AND {mr_check})
+          )",
+        issue_check = my_issue_check.replace("{entity_issue_id}", "d.issue_id"),
+        mr_check = my_mr_check.replace("{entity_mr_id}", "d.merge_request_id"),
+    );
+
+    // Source 2: @mentions on ANY item (not restricted to my items)
+    // Word-boundary-aware matching to reduce false positives
+    let source2 = format!(
+        "SELECT n.created_at, 'mention_note',
+            CASE WHEN d.issue_id IS NOT NULL THEN 'issue' ELSE 'mr' END,
+            COALESCE(i.iid, m.iid),
+            COALESCE(i.title, m.title),
+            p.path_with_namespace,
+            n.author_username,
+            SUBSTR(n.body, 1, 200),
+            NULL,
+            1,
+            n.body
+        FROM notes n
+        JOIN discussions d ON n.discussion_id = d.id
+        JOIN projects p ON d.project_id = p.id
+        LEFT JOIN issues i ON d.issue_id = i.id
+        LEFT JOIN merge_requests m ON d.merge_request_id = m.id
+        WHERE n.is_system = 0
+          AND n.created_at > ?2
+          AND n.author_username != ?1
+          AND LOWER(n.body) LIKE '%@' || LOWER(?1) || '%'
+          AND NOT (
+            (d.issue_id IS NOT NULL AND {issue_check})
+            OR (d.merge_request_id IS NOT NULL AND {mr_check})
+          )",
+        issue_check = my_issue_check.replace("{entity_issue_id}", "d.issue_id"),
+        mr_check = my_mr_check.replace("{entity_mr_id}", "d.merge_request_id"),
+    );
+
+    // Source 3: Assignment/review-request system notes mentioning me
+    let source3 = "SELECT n.created_at,
+            CASE
+                WHEN LOWER(n.body) LIKE '%assigned to @%' THEN 'assign'
+                WHEN LOWER(n.body) LIKE '%unassigned @%' THEN 'unassign'
+                WHEN LOWER(n.body) LIKE '%requested review from @%' THEN 'review_request'
+                ELSE 'assign'
+            END,
+            CASE WHEN d.issue_id IS NOT NULL THEN 'issue' ELSE 'mr' END,
+            COALESCE(i.iid, m.iid),
+            COALESCE(i.title, m.title),
+            p.path_with_namespace,
+            n.author_username,
+            n.body,
+            NULL,
+            0,
+            NULL
+        FROM notes n
+        JOIN discussions d ON n.discussion_id = d.id
+        JOIN projects p ON d.project_id = p.id
+        LEFT JOIN issues i ON d.issue_id = i.id
+        LEFT JOIN merge_requests m ON d.merge_request_id = m.id
+        WHERE n.is_system = 1
+          AND n.created_at > ?2
+          AND n.author_username != ?1
+          AND (
+            LOWER(n.body) LIKE '%assigned to @' || LOWER(?1) || '%'
+            OR LOWER(n.body) LIKE '%unassigned @' || LOWER(?1) || '%'
+            OR LOWER(n.body) LIKE '%requested review from @' || LOWER(?1) || '%'
+          )"
+    .to_string();
+
+    let full_sql = format!(
+        "{source1}
+         UNION ALL {source2}
+         UNION ALL {source3}
+         ORDER BY 1 DESC
+         LIMIT 200"
+    );
+
+    let params: Vec<Box<dyn rusqlite::types::ToSql>> =
+        vec![Box::new(username.to_string()), Box::new(cursor_ms)];
+    let param_refs: Vec<&dyn rusqlite::types::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+
+    let mut stmt = conn.prepare(&full_sql)?;
+    let rows = stmt.query_map(param_refs.as_slice(), |row| {
+        Ok(RawSinceCheckRow {
+            timestamp: row.get(0)?,
+            event_type: row.get(1)?,
+            entity_type: row.get(2)?,
+            entity_iid: row.get(3)?,
+            entity_title: row.get::<_, Option<String>>(4)?.unwrap_or_default(),
+            project_path: row.get(5)?,
+            actor: row.get(6)?,
+            summary: row.get::<_, Option<String>>(7)?.unwrap_or_default(),
+            body_preview: row.get(8)?,
+            is_mention_source: row.get::<_, i32>(9)? != 0,
+            mention_body: row.get(10)?,
+        })
+    })?;
+
+    let mention_re = build_exact_mention_regex(username);
+    let raw_events: Vec<RawSinceCheckRow> = rows
+        .collect::<std::result::Result<Vec<_>, _>>()?
+        .into_iter()
+        .filter(|row| {
+            !row.is_mention_source
+                || row
+                    .mention_body
+                    .as_deref()
+                    .is_some_and(|body| contains_exact_mention(body, &mention_re))
+        })
+        .collect();
+    Ok(group_since_check_events(raw_events))
+}
+
+/// Group flat event rows by entity, sort groups newest-first, events within oldest-first.
+fn group_since_check_events(rows: Vec<RawSinceCheckRow>) -> Vec<SinceCheckGroup> {
+    // Key: (entity_type, entity_iid, project_path)
+    let mut groups: HashMap<(String, i64, String), SinceCheckGroup> = HashMap::new();
+
+    for row in rows {
+        let key = (
+            row.entity_type.clone(),
+            row.entity_iid,
+            row.project_path.clone(),
+        );
+        let group = groups.entry(key).or_insert_with(|| SinceCheckGroup {
+            entity_type: row.entity_type.clone(),
+            entity_iid: row.entity_iid,
+            entity_title: row.entity_title.clone(),
+            project_path: row.project_path.clone(),
+            events: Vec::new(),
+            latest_timestamp: 0,
+        });
+
+        if row.timestamp > group.latest_timestamp {
+            group.latest_timestamp = row.timestamp;
+        }
+
+        group.events.push(SinceCheckEvent {
+            timestamp: row.timestamp,
+            event_type: parse_event_type(&row.event_type),
+            actor: row.actor,
+            summary: row.summary,
+            body_preview: row.body_preview,
+        });
+    }
+
+    let mut result: Vec<SinceCheckGroup> = groups.into_values().collect();
+    // Sort groups newest-first
+    result.sort_by_key(|g| std::cmp::Reverse(g.latest_timestamp));
+    // Sort events within each group oldest-first (read top-to-bottom)
+    for group in &mut result {
+        group.events.sort_by_key(|e| e.timestamp);
+    }
+    result
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/// Parse attention state string from SQL CASE result.
+fn parse_attention_state(s: &str) -> AttentionState {
+    match s {
+        "needs_attention" => AttentionState::NeedsAttention,
+        "not_started" => AttentionState::NotStarted,
+        "awaiting_response" => AttentionState::AwaitingResponse,
+        "stale" => AttentionState::Stale,
+        "not_ready" => AttentionState::NotReady,
+        _ => AttentionState::NotStarted,
+    }
+}
+
+/// Parse activity event type string from SQL.
+fn parse_event_type(s: &str) -> ActivityEventType {
+    match s {
+        "note" => ActivityEventType::Note,
+        "mention_note" => ActivityEventType::Note,
+        "status_change" => ActivityEventType::StatusChange,
+        "label_change" => ActivityEventType::LabelChange,
+        "assign" => ActivityEventType::Assign,
+        "unassign" => ActivityEventType::Unassign,
+        "review_request" => ActivityEventType::ReviewRequest,
+        "milestone_change" => ActivityEventType::MilestoneChange,
+        _ => ActivityEventType::Note,
+    }
+}
+
+fn build_exact_mention_regex(username: &str) -> Regex {
+    let escaped = regex::escape(username);
+    let pattern = format!(r"(?i)@{escaped}");
+    Regex::new(&pattern).expect("mention regex must compile")
+}
+
+fn contains_exact_mention(body: &str, mention_re: &Regex) -> bool {
+    for m in mention_re.find_iter(body) {
+        let start = m.start();
+        let end = m.end();
+
+        let prev = body[..start].chars().next_back();
+        if prev.is_some_and(is_username_char) {
+            continue;
+        }
+
+        if let Some(next) = body[end..].chars().next() {
+            // Reject domain-like continuations such as "@alice.com"
+            if next == '.' {
+                let after_dot = body[end + next.len_utf8()..].chars().next();
+                if after_dot.is_some_and(is_username_char) {
+                    continue;
+                }
+            }
+
+            if is_username_char(next) {
+                continue;
+            }
+        }
+
+        return true;
+    }
+
+    false
+}
+
+fn is_username_char(ch: char) -> bool {
+    ch.is_ascii_alphanumeric() || matches!(ch, '_' | '-')
+}
+
+/// Build a SQL clause for project ID filtering.
+/// `start_idx` is the 1-based parameter index for the first project ID.
+/// Returns empty string when no filter is needed (all projects).
+fn build_project_clause_at(column: &str, project_ids: &[i64], start_idx: usize) -> String {
+    match project_ids.len() {
+        0 => String::new(),
+        1 => format!("AND {column} = ?{start_idx}"),
+        n => {
+            let placeholders: Vec<String> = (0..n).map(|i| format!("?{}", start_idx + i)).collect();
+            format!("AND {column} IN ({})", placeholders.join(","))
+        }
+    }
+}
+
+/// Convenience: project clause starting at param index 2 (after username at ?1).
+fn build_project_clause(column: &str, project_ids: &[i64]) -> String {
+    build_project_clause_at(column, project_ids, 2)
+}
+
+/// Build the parameter vector: username first, then project IDs.
+fn build_params(username: &str, project_ids: &[i64]) -> Vec<Box<dyn rusqlite::types::ToSql>> {
+    let mut params: Vec<Box<dyn rusqlite::types::ToSql>> = Vec::new();
+    params.push(Box::new(username.to_string()));
+    for &pid in project_ids {
+        params.push(Box::new(pid));
+    }
+    params
+}
+
+/// Populate labels for issues via cached per-item queries.
+fn populate_issue_labels(conn: &Connection, issues: &mut [MeIssue]) -> Result<()> {
+    if issues.is_empty() {
+        return Ok(());
+    }
+    for issue in issues.iter_mut() {
+        let mut stmt = conn.prepare_cached(
+            "SELECT l.name FROM labels l
+             JOIN issue_labels il ON l.id = il.label_id
+             JOIN issues i ON il.issue_id = i.id
+             JOIN projects p ON i.project_id = p.id
+             WHERE i.iid = ?1 AND p.path_with_namespace = ?2
+             ORDER BY l.name",
+        )?;
+        let labels: Vec<String> = stmt
+            .query_map(rusqlite::params![issue.iid, issue.project_path], |row| {
+                row.get(0)
+            })?
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+        issue.labels = labels;
+    }
+    Ok(())
+}
+
+/// Populate labels for MRs via cached per-item queries.
+fn populate_mr_labels(conn: &Connection, mrs: &mut [MeMr]) -> Result<()> {
+    if mrs.is_empty() {
+        return Ok(());
+    }
+    for mr in mrs.iter_mut() {
+        let mut stmt = conn.prepare_cached(
+            "SELECT l.name FROM labels l
+             JOIN mr_labels ml ON l.id = ml.label_id
+             JOIN merge_requests m ON ml.merge_request_id = m.id
+             JOIN projects p ON m.project_id = p.id
+             WHERE m.iid = ?1 AND p.path_with_namespace = ?2
+             ORDER BY l.name",
+        )?;
+        let labels: Vec<String> = stmt
+            .query_map(rusqlite::params![mr.iid, mr.project_path], |row| row.get(0))?
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+        mr.labels = labels;
+    }
+    Ok(())
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+#[path = "me_tests.rs"]
+mod tests;

src/cli/commands/me/render_human.rs

@@ -0,0 +1,667 @@
+use crate::cli::render::{self, Align, GlyphMode, Icons, LoreRenderer, StyledCell, Table, Theme};
+
+use super::types::{
+    ActivityEventType, AttentionState, MeActivityEvent, MeDashboard, MeIssue, MeMr, MeSummary,
+    SinceLastCheck,
+};
+
+// ─── Layout Helpers ─────────────────────────────────────────────────────────
+
+/// Compute the title/summary column width for a section given its fixed overhead.
+/// Returns a width clamped to [20, 80].
+fn title_width(overhead: usize) -> usize {
+    render::terminal_width()
+        .saturating_sub(overhead)
+        .clamp(20, 80)
+}
+
+// ─── Glyph Mode Helper ──────────────────────────────────────────────────────
+
+/// Get the current glyph mode, defaulting to Unicode if renderer not initialized.
+fn glyph_mode() -> GlyphMode {
+    LoreRenderer::try_get().map_or(GlyphMode::Unicode, LoreRenderer::glyph_mode)
+}
+
+// ─── Attention Icons ─────────────────────────────────────────────────────────
+
+/// Return the attention icon for the current glyph mode.
+fn attention_icon(state: &AttentionState) -> &'static str {
+    let mode = glyph_mode();
+    match state {
+        AttentionState::NeedsAttention => match mode {
+            GlyphMode::Nerd => "\u{f0f3}",    // bell
+            GlyphMode::Unicode => "\u{25c6}", // diamond
+            GlyphMode::Ascii => "[!]",
+        },
+        AttentionState::NotStarted => match mode {
+            GlyphMode::Nerd => "\u{f005}",    // star
+            GlyphMode::Unicode => "\u{2605}", // black star
+            GlyphMode::Ascii => "[*]",
+        },
+        AttentionState::AwaitingResponse => match mode {
+            GlyphMode::Nerd => "\u{f017}",    // clock
+            GlyphMode::Unicode => "\u{25f7}", // white circle with upper right quadrant
+            GlyphMode::Ascii => "[~]",
+        },
+        AttentionState::Stale => match mode {
+            GlyphMode::Nerd => "\u{f54c}",    // skull
+            GlyphMode::Unicode => "\u{2620}", // skull and crossbones
+            GlyphMode::Ascii => "[x]",
+        },
+        AttentionState::NotReady => match mode {
+            GlyphMode::Nerd => "\u{f040}",    // pencil
+            GlyphMode::Unicode => "\u{270e}", // lower right pencil
+            GlyphMode::Ascii => "[D]",
+        },
+    }
+}
+
+/// Style for an attention state.
+fn attention_style(state: &AttentionState) -> lipgloss::Style {
+    match state {
+        AttentionState::NeedsAttention => Theme::warning(),
+        AttentionState::NotStarted => Theme::info(),
+        AttentionState::AwaitingResponse | AttentionState::Stale => Theme::dim(),
+        AttentionState::NotReady => Theme::state_draft(),
+    }
+}
+
+/// Render the styled attention icon for an item.
+fn styled_attention(state: &AttentionState) -> String {
+    let icon = attention_icon(state);
+    attention_style(state).render(icon)
+}
+
+// ─── Merge Status Labels ────────────────────────────────────────────────────
+
+/// Convert GitLab's `detailed_merge_status` API values to human-friendly labels.
+fn humanize_merge_status(status: &str) -> &str {
+    match status {
+        "not_approved" => "needs approval",
+        "requested_changes" => "changes requested",
+        "mergeable" => "ready to merge",
+        "not_open" => "not open",
+        "checking" => "checking",
+        "ci_must_pass" => "CI pending",
+        "ci_still_running" => "CI running",
+        "discussions_not_resolved" => "unresolved threads",
+        "draft_status" => "draft",
+        "need_rebase" => "needs rebase",
+        "conflict" | "has_conflicts" => "has conflicts",
+        "blocked_status" => "blocked",
+        "approvals_syncing" => "syncing approvals",
+        "jira_association_missing" => "missing Jira link",
+        "unchecked" => "unchecked",
+        other => other,
+    }
+}
+
+// ─── Event Badges ────────────────────────────────────────────────────────────
+
+/// Return the badge label text for an activity event type.
+fn activity_badge_label(event_type: &ActivityEventType) -> String {
+    match event_type {
+        ActivityEventType::Note => "note",
+        ActivityEventType::StatusChange => "status",
+        ActivityEventType::LabelChange => "label",
+        ActivityEventType::Assign | ActivityEventType::Unassign => "assign",
+        ActivityEventType::ReviewRequest => "review",
+        ActivityEventType::MilestoneChange => "milestone",
+    }
+    .to_string()
+}
+
+/// Return the style for an activity event badge.
+fn activity_badge_style(event_type: &ActivityEventType) -> lipgloss::Style {
+    match event_type {
+        ActivityEventType::Note => Theme::info(),
+        ActivityEventType::StatusChange => Theme::warning(),
+        ActivityEventType::LabelChange => Theme::accent(),
+        ActivityEventType::Assign
+        | ActivityEventType::Unassign
+        | ActivityEventType::ReviewRequest => Theme::success(),
+        ActivityEventType::MilestoneChange => accent_magenta(),
+    }
+}
+
+/// Magenta accent for milestone badges.
+fn accent_magenta() -> lipgloss::Style {
+    if LoreRenderer::try_get().is_some_and(LoreRenderer::colors_enabled) {
+        lipgloss::Style::new().foreground("#d946ef")
+    } else {
+        lipgloss::Style::new()
+    }
+}
+
+/// Very dark gray for system events (label, assign, status, milestone, review).
+fn system_event_style() -> lipgloss::Style {
+    if LoreRenderer::try_get().is_some_and(LoreRenderer::colors_enabled) {
+        lipgloss::Style::new().foreground("#555555")
+    } else {
+        lipgloss::Style::new().faint()
+    }
+}
+
+// ─── Summary Header ─────────────────────────────────────────────────────────
+
+/// Print the summary header with counts and attention legend (Task #14).
+pub fn print_summary_header(summary: &MeSummary, username: &str) {
+    println!();
+    println!(
+        "{}",
+        Theme::bold().render(&format!(
+            "{} {} -- Personal Dashboard",
+            Icons::user(),
+            username,
+        ))
+    );
+    println!("{}", "\u{2500}".repeat(render::terminal_width()));
+
+    // Counts line
+    let needs = if summary.needs_attention_count > 0 {
+        Theme::warning().render(&format!("{} need attention", summary.needs_attention_count))
+    } else {
+        Theme::dim().render("0 need attention")
+    };
+
+    println!(
+        "  {} projects  {} issues  {} authored MRs  {} reviewing MRs  {}",
+        summary.project_count,
+        summary.open_issue_count,
+        summary.authored_mr_count,
+        summary.reviewing_mr_count,
+        needs,
+    );
+
+    // Attention legend
+    print_attention_legend();
+}
+
+/// Print the attention icon legend.
+fn print_attention_legend() {
+    println!();
+    let states = [
+        (AttentionState::NeedsAttention, "needs attention"),
+        (AttentionState::NotStarted, "not started"),
+        (AttentionState::AwaitingResponse, "awaiting response"),
+        (AttentionState::Stale, "stale (30d+)"),
+        (AttentionState::NotReady, "draft (not ready)"),
+    ];
+
+    let legend: Vec<String> = states
+        .iter()
+        .map(|(state, label)| format!("{} {}", styled_attention(state), Theme::dim().render(label)))
+        .collect();
+
+    println!("  {}", legend.join("  "));
+}
+
+// ─── Open Issues Section ─────────────────────────────────────────────────────
+
+/// Print the open issues section (Task #15).
+pub fn print_issues_section(issues: &[MeIssue], single_project: bool) {
+    if issues.is_empty() {
+        println!("{}", render::section_divider("Open Issues (0)"));
+        println!(
+            "    {}",
+            Theme::dim().render("No open issues assigned to you.")
+        );
+        return;
+    }
+
+    println!(
+        "{}",
+        render::section_divider(&format!("Open Issues ({})", issues.len()))
+    );
+
+    for issue in issues {
+        let attn = styled_attention(&issue.attention_state);
+        let ref_str = format!("#{}", issue.iid);
+        let status = issue
+            .status_name
+            .as_deref()
+            .map(|s| format!(" [{s}]"))
+            .unwrap_or_default();
+        let time = render::format_relative_time(issue.updated_at);
+
+        // Line 1: attention icon, issue ref, title, status, relative time
+        println!(
+            "    {} {}  {}{}  {}",
+            attn,
+            Theme::issue_ref().render(&ref_str),
+            render::truncate(&issue.title, title_width(43)),
+            Theme::dim().render(&status),
+            Theme::dim().render(&time),
+        );
+
+        // Line 2: project path (suppressed in single-project mode)
+        if !single_project {
+            println!("      {}", Theme::dim().render(&issue.project_path),);
+        }
+    }
+}
+
+// ─── MR Sections ─────────────────────────────────────────────────────────────
+
+/// Print the authored MRs section (Task #16).
+pub fn print_authored_mrs_section(mrs: &[MeMr], single_project: bool) {
+    if mrs.is_empty() {
+        println!("{}", render::section_divider("Authored MRs (0)"));
+        println!(
+            "    {}",
+            Theme::dim().render("No open MRs authored by you.")
+        );
+        return;
+    }
+
+    println!(
+        "{}",
+        render::section_divider(&format!("Authored MRs ({})", mrs.len()))
+    );
+
+    for mr in mrs {
+        let attn = styled_attention(&mr.attention_state);
+        let ref_str = format!("!{}", mr.iid);
+        let draft = if mr.draft {
+            Theme::state_draft().render(" [draft]")
+        } else {
+            String::new()
+        };
+        let merge_status = mr
+            .detailed_merge_status
+            .as_deref()
+            .filter(|s| !s.is_empty() && *s != "not_open")
+            .map(|s| format!(" ({})", humanize_merge_status(s)))
+            .unwrap_or_default();
+        let time = render::format_relative_time(mr.updated_at);
+
+        // Line 1: attention, MR ref, title, draft, merge status, time
+        println!(
+            "    {} {}  {}{}{}  {}",
+            attn,
+            Theme::mr_ref().render(&ref_str),
+            render::truncate(&mr.title, title_width(48)),
+            draft,
+            Theme::dim().render(&merge_status),
+            Theme::dim().render(&time),
+        );
+
+        // Line 2: project path
+        if !single_project {
+            println!("      {}", Theme::dim().render(&mr.project_path),);
+        }
+    }
+}
+
+/// Print the reviewing MRs section (Task #16).
+pub fn print_reviewing_mrs_section(mrs: &[MeMr], single_project: bool) {
+    if mrs.is_empty() {
+        println!("{}", render::section_divider("Reviewing MRs (0)"));
+        println!(
+            "    {}",
+            Theme::dim().render("No open MRs awaiting your review.")
+        );
+        return;
+    }
+
+    println!(
+        "{}",
+        render::section_divider(&format!("Reviewing MRs ({})", mrs.len()))
+    );
+
+    for mr in mrs {
+        let attn = styled_attention(&mr.attention_state);
+        let ref_str = format!("!{}", mr.iid);
+        let author = mr
+            .author_username
+            .as_deref()
+            .map(|a| format!(" by {}", Theme::username().render(&format!("@{a}"))))
+            .unwrap_or_default();
+        let draft = if mr.draft {
+            Theme::state_draft().render(" [draft]")
+        } else {
+            String::new()
+        };
+        let time = render::format_relative_time(mr.updated_at);
+
+        // Line 1: attention, MR ref, title, author, draft, time
+        println!(
+            "    {} {}  {}{}{}  {}",
+            attn,
+            Theme::mr_ref().render(&ref_str),
+            render::truncate(&mr.title, title_width(50)),
+            author,
+            draft,
+            Theme::dim().render(&time),
+        );
+
+        // Line 2: project path
+        if !single_project {
+            println!("      {}", Theme::dim().render(&mr.project_path),);
+        }
+    }
+}
+
+// ─── Activity Feed ───────────────────────────────────────────────────────────
+
+/// Print the activity feed section (Task #17).
+pub fn print_activity_section(events: &[MeActivityEvent], single_project: bool) {
+    if events.is_empty() {
+        println!("{}", render::section_divider("Activity (0)"));
+        println!(
+            "    {}",
+            Theme::dim().render("No recent activity on your items.")
+        );
+        return;
+    }
+
+    println!(
+        "{}",
+        render::section_divider(&format!("Activity ({})", events.len()))
+    );
+
+    // Columns: badge | ref | summary | actor | time
+    // Table handles alignment, padding, and truncation automatically.
+    let summary_max = title_width(46);
+    let mut table = Table::new()
+        .columns(5)
+        .indent(4)
+        .align(1, Align::Right)
+        .align(4, Align::Right)
+        .max_width(2, summary_max);
+
+    for event in events {
+        let badge_label = activity_badge_label(&event.event_type);
+        let badge_style = activity_badge_style(&event.event_type);
+
+        let ref_text = match event.entity_type.as_str() {
+            "issue" => format!("#{}", event.entity_iid),
+            "mr" => format!("!{}", event.entity_iid),
+            _ => format!("{}:{}", event.entity_type, event.entity_iid),
+        };
+        let is_system = !matches!(event.event_type, ActivityEventType::Note);
+        // System events → very dark gray; own notes → standard dim; else → full color.
+        let subdued = is_system || event.is_own;
+        let subdued_style = || {
+            if is_system {
+                system_event_style()
+            } else {
+                Theme::dim()
+            }
+        };
+
+        let badge_style_final = if subdued {
+            subdued_style()
+        } else {
+            badge_style
+        };
+
+        let ref_style = if subdued {
+            Some(subdued_style())
+        } else {
+            match event.entity_type.as_str() {
+                "issue" => Some(Theme::issue_ref()),
+                "mr" => Some(Theme::mr_ref()),
+                _ => None,
+            }
+        };
+
+        let clean_summary = event.summary.replace('\n', " ");
+        let summary_style: Option<lipgloss::Style> =
+            if subdued { Some(subdued_style()) } else { None };
+
+        let actor_text = if event.is_own {
+            event
+                .actor
+                .as_deref()
+                .map_or("(you)".to_string(), |a| format!("@{a} (you)"))
+        } else {
+            event
+                .actor
+                .as_deref()
+                .map_or(String::new(), |a| format!("@{a}"))
+        };
+        let actor_style = if subdued {
+            subdued_style()
+        } else {
+            Theme::username()
+        };
+
+        let time = render::format_relative_time_compact(event.timestamp);
+
+        table.add_row(vec![
+            StyledCell::styled(badge_label, badge_style_final),
+            match ref_style {
+                Some(s) => StyledCell::styled(ref_text, s),
+                None => StyledCell::plain(ref_text),
+            },
+            match summary_style {
+                Some(s) => StyledCell::styled(clean_summary, s),
+                None => StyledCell::plain(clean_summary),
+            },
+            StyledCell::styled(actor_text, actor_style),
+            StyledCell::styled(time, Theme::dim()),
+        ]);
+    }
+
+    // Render table rows and interleave per-event detail lines
+    let rendered = table.render();
+    for (line, event) in rendered.lines().zip(events.iter()) {
+        println!("{line}");
+        if !single_project {
+            println!("      {}", Theme::dim().render(&event.project_path));
+        }
+        if let Some(preview) = &event.body_preview
+            && !preview.is_empty()
+        {
+            let truncated = render::truncate(preview, 60);
+            println!("      {}", Theme::dim().render(&format!("\"{truncated}\"")));
+        }
+    }
+}
+
+/// Format an entity reference (#N for issues, !N for MRs), right-aligned to 6 chars.
+#[cfg(test)]
+fn format_entity_ref(entity_type: &str, iid: i64) -> String {
+    match entity_type {
+        "issue" => {
+            let s = format!("{:>6}", format!("#{iid}"));
+            Theme::issue_ref().render(&s)
+        }
+        "mr" => {
+            let s = format!("{:>6}", format!("!{iid}"));
+            Theme::mr_ref().render(&s)
+        }
+        _ => format!("{:>6}", format!("{entity_type}:{iid}")),
+    }
+}
+
+// ─── Since Last Check ────────────────────────────────────────────────────────
+
+/// Print the "since last check" section at the top of the dashboard.
+pub fn print_since_last_check_section(since: &SinceLastCheck, single_project: bool) {
+    let relative = render::format_relative_time(since.cursor_ms);
+
+    if since.groups.is_empty() {
+        println!(
+            "\n    {}",
+            Theme::dim().render(&format!(
+                "No new events since {} ({relative})",
+                render::format_datetime(since.cursor_ms),
+            ))
+        );
+        return;
+    }
+
+    println!(
+        "{}",
+        render::section_divider(&format!("Since Last Check ({relative})"))
+    );
+
+    for group in &since.groups {
+        // Entity header: !247  Fix race condition...
+        let ref_str = match group.entity_type.as_str() {
+            "issue" => format!("#{}", group.entity_iid),
+            "mr" => format!("!{}", group.entity_iid),
+            _ => format!("{}:{}", group.entity_type, group.entity_iid),
+        };
+        let ref_style = match group.entity_type.as_str() {
+            "issue" => Theme::issue_ref(),
+            "mr" => Theme::mr_ref(),
+            _ => Theme::bold(),
+        };
+
+        println!();
+        println!(
+            "    {}  {}",
+            ref_style.render(&ref_str),
+            Theme::bold().render(&render::truncate(&group.entity_title, title_width(20))),
+        );
+        if !single_project {
+            println!("      {}", Theme::dim().render(&group.project_path));
+        }
+
+        // Sub-events as indented rows
+        let summary_max = title_width(42);
+        let mut table = Table::new()
+            .columns(3)
+            .indent(6)
+            .align(2, Align::Right)
+            .max_width(1, summary_max);
+
+        for event in &group.events {
+            let badge = activity_badge_label(&event.event_type);
+            let badge_style = activity_badge_style(&event.event_type);
+
+            let actor_prefix = event
+                .actor
+                .as_deref()
+                .map(|a| format!("@{a} "))
+                .unwrap_or_default();
+            let clean_summary = event.summary.replace('\n', " ");
+            let summary_text = format!("{actor_prefix}{clean_summary}");
+
+            let time = render::format_relative_time_compact(event.timestamp);
+
+            table.add_row(vec![
+                StyledCell::styled(badge, badge_style),
+                StyledCell::plain(summary_text),
+                StyledCell::styled(time, Theme::dim()),
+            ]);
+        }
+
+        let rendered = table.render();
+        for (line, event) in rendered.lines().zip(group.events.iter()) {
+            println!("{line}");
+            if let Some(preview) = &event.body_preview
+                && !preview.is_empty()
+            {
+                let truncated = render::truncate(preview, 60);
+                println!(
+                    "        {}",
+                    Theme::dim().render(&format!("\"{truncated}\""))
+                );
+            }
+        }
+    }
+
+    // Footer
+    println!(
+        "\n    {}",
+        Theme::dim().render(&format!(
+            "{} events across {} items",
+            since.total_event_count,
+            since.groups.len()
+        ))
+    );
+}
+
+// ─── Full Dashboard ──────────────────────────────────────────────────────────
+
+/// Render the complete human-mode dashboard.
+pub fn print_me_dashboard(dashboard: &MeDashboard, single_project: bool) {
+    if let Some(ref since) = dashboard.since_last_check {
+        print_since_last_check_section(since, single_project);
+    }
+    print_summary_header(&dashboard.summary, &dashboard.username);
+    print_issues_section(&dashboard.open_issues, single_project);
+    print_authored_mrs_section(&dashboard.open_mrs_authored, single_project);
+    print_reviewing_mrs_section(&dashboard.reviewing_mrs, single_project);
+    print_activity_section(&dashboard.activity, single_project);
+    println!();
+}
+
+/// Render a filtered dashboard (only requested sections).
+pub fn print_me_dashboard_filtered(
+    dashboard: &MeDashboard,
+    single_project: bool,
+    show_issues: bool,
+    show_mrs: bool,
+    show_activity: bool,
+) {
+    if let Some(ref since) = dashboard.since_last_check {
+        print_since_last_check_section(since, single_project);
+    }
+    print_summary_header(&dashboard.summary, &dashboard.username);
+
+    if show_issues {
+        print_issues_section(&dashboard.open_issues, single_project);
+    }
+    if show_mrs {
+        print_authored_mrs_section(&dashboard.open_mrs_authored, single_project);
+        print_reviewing_mrs_section(&dashboard.reviewing_mrs, single_project);
+    }
+    if show_activity {
+        print_activity_section(&dashboard.activity, single_project);
+    }
+    println!();
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn attention_icon_returns_nonempty_for_all_states() {
+        let states = [
+            AttentionState::NeedsAttention,
+            AttentionState::NotStarted,
+            AttentionState::AwaitingResponse,
+            AttentionState::Stale,
+            AttentionState::NotReady,
+        ];
+        for state in &states {
+            assert!(!attention_icon(state).is_empty(), "empty for {state:?}");
+        }
+    }
+
+    #[test]
+    fn format_entity_ref_issue() {
+        let result = format_entity_ref("issue", 42);
+        assert!(result.contains("42"), "got: {result}");
+    }
+
+    #[test]
+    fn format_entity_ref_mr() {
+        let result = format_entity_ref("mr", 99);
+        assert!(result.contains("99"), "got: {result}");
+    }
+
+    #[test]
+    fn activity_badge_label_returns_nonempty_for_all_types() {
+        let types = [
+            ActivityEventType::Note,
+            ActivityEventType::StatusChange,
+            ActivityEventType::LabelChange,
+            ActivityEventType::Assign,
+            ActivityEventType::Unassign,
+            ActivityEventType::ReviewRequest,
+            ActivityEventType::MilestoneChange,
+        ];
+        for t in &types {
+            assert!(!activity_badge_label(t).is_empty(), "empty for {t:?}");
+        }
+    }
+}

src/cli/commands/me/render_robot.rs

@@ -0,0 +1,428 @@
+use serde::Serialize;
+
+use crate::cli::robot::RobotMeta;
+use crate::core::time::ms_to_iso;
+
+use super::types::{
+    ActivityEventType, AttentionState, MeActivityEvent, MeDashboard, MeIssue, MeMr, MeSummary,
+    SinceCheckEvent, SinceCheckGroup, SinceLastCheck,
+};
+
+// ─── Robot JSON Output (Task #18) ────────────────────────────────────────────
+
+/// Print the full me dashboard as robot-mode JSON.
+pub fn print_me_json(
+    dashboard: &MeDashboard,
+    elapsed_ms: u64,
+    fields: Option<&[String]>,
+) -> crate::core::error::Result<()> {
+    let envelope = MeJsonEnvelope {
+        ok: true,
+        data: MeDataJson::from_dashboard(dashboard),
+        meta: RobotMeta { elapsed_ms },
+    };
+
+    let mut value = serde_json::to_value(&envelope)
+        .map_err(|e| crate::core::error::LoreError::Other(format!("JSON serialization: {e}")))?;
+
+    // Apply --fields filtering (Task #19)
+    if let Some(f) = fields {
+        let expanded = crate::cli::robot::expand_fields_preset(f, "me_items");
+        // Filter all item arrays
+        for key in &["open_issues", "open_mrs_authored", "reviewing_mrs"] {
+            crate::cli::robot::filter_fields(&mut value, key, &expanded);
+        }
+
+        // Activity gets its own minimal preset
+        let activity_expanded = crate::cli::robot::expand_fields_preset(f, "me_activity");
+        crate::cli::robot::filter_fields(&mut value, "activity", &activity_expanded);
+    }
+
+    let json = serde_json::to_string(&value)
+        .map_err(|e| crate::core::error::LoreError::Other(format!("JSON serialization: {e}")))?;
+    println!("{json}");
+    Ok(())
+}
+
+/// Print `--reset-cursor` response using standard robot envelope.
+pub fn print_cursor_reset_json(elapsed_ms: u64) -> crate::core::error::Result<()> {
+    let value = cursor_reset_envelope_json(elapsed_ms);
+    let json = serde_json::to_string(&value)
+        .map_err(|e| crate::core::error::LoreError::Other(format!("JSON serialization: {e}")))?;
+    println!("{json}");
+    Ok(())
+}
+
+fn cursor_reset_envelope_json(elapsed_ms: u64) -> serde_json::Value {
+    serde_json::json!({
+        "ok": true,
+        "data": {
+            "cursor_reset": true
+        },
+        "meta": {
+            "elapsed_ms": elapsed_ms
+        }
+    })
+}
+
+// ─── JSON Envelope ───────────────────────────────────────────────────────────
+
+#[derive(Serialize)]
+struct MeJsonEnvelope {
+    ok: bool,
+    data: MeDataJson,
+    meta: RobotMeta,
+}
+
+#[derive(Serialize)]
+struct MeDataJson {
+    username: String,
+    since_iso: Option<String>,
+    summary: SummaryJson,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    since_last_check: Option<SinceLastCheckJson>,
+    open_issues: Vec<IssueJson>,
+    open_mrs_authored: Vec<MrJson>,
+    reviewing_mrs: Vec<MrJson>,
+    activity: Vec<ActivityJson>,
+}
+
+impl MeDataJson {
+    fn from_dashboard(d: &MeDashboard) -> Self {
+        Self {
+            username: d.username.clone(),
+            since_iso: d.since_ms.map(ms_to_iso),
+            summary: SummaryJson::from(&d.summary),
+            since_last_check: d.since_last_check.as_ref().map(SinceLastCheckJson::from),
+            open_issues: d.open_issues.iter().map(IssueJson::from).collect(),
+            open_mrs_authored: d.open_mrs_authored.iter().map(MrJson::from).collect(),
+            reviewing_mrs: d.reviewing_mrs.iter().map(MrJson::from).collect(),
+            activity: d.activity.iter().map(ActivityJson::from).collect(),
+        }
+    }
+}
+
+// ─── Summary ─────────────────────────────────────────────────────────────────
+
+#[derive(Serialize)]
+struct SummaryJson {
+    project_count: usize,
+    open_issue_count: usize,
+    authored_mr_count: usize,
+    reviewing_mr_count: usize,
+    needs_attention_count: usize,
+}
+
+impl From<&MeSummary> for SummaryJson {
+    fn from(s: &MeSummary) -> Self {
+        Self {
+            project_count: s.project_count,
+            open_issue_count: s.open_issue_count,
+            authored_mr_count: s.authored_mr_count,
+            reviewing_mr_count: s.reviewing_mr_count,
+            needs_attention_count: s.needs_attention_count,
+        }
+    }
+}
+
+// ─── Issue ───────────────────────────────────────────────────────────────────
+
+#[derive(Serialize)]
+struct IssueJson {
+    project: String,
+    iid: i64,
+    title: String,
+    state: String,
+    attention_state: String,
+    status_name: Option<String>,
+    labels: Vec<String>,
+    updated_at_iso: String,
+    web_url: Option<String>,
+}
+
+impl From<&MeIssue> for IssueJson {
+    fn from(i: &MeIssue) -> Self {
+        Self {
+            project: i.project_path.clone(),
+            iid: i.iid,
+            title: i.title.clone(),
+            state: "opened".to_string(),
+            attention_state: attention_state_str(&i.attention_state),
+            status_name: i.status_name.clone(),
+            labels: i.labels.clone(),
+            updated_at_iso: ms_to_iso(i.updated_at),
+            web_url: i.web_url.clone(),
+        }
+    }
+}
+
+// ─── MR ──────────────────────────────────────────────────────────────────────
+
+#[derive(Serialize)]
+struct MrJson {
+    project: String,
+    iid: i64,
+    title: String,
+    state: String,
+    attention_state: String,
+    draft: bool,
+    detailed_merge_status: Option<String>,
+    author_username: Option<String>,
+    labels: Vec<String>,
+    updated_at_iso: String,
+    web_url: Option<String>,
+}
+
+impl From<&MeMr> for MrJson {
+    fn from(m: &MeMr) -> Self {
+        Self {
+            project: m.project_path.clone(),
+            iid: m.iid,
+            title: m.title.clone(),
+            state: "opened".to_string(),
+            attention_state: attention_state_str(&m.attention_state),
+            draft: m.draft,
+            detailed_merge_status: m.detailed_merge_status.clone(),
+            author_username: m.author_username.clone(),
+            labels: m.labels.clone(),
+            updated_at_iso: ms_to_iso(m.updated_at),
+            web_url: m.web_url.clone(),
+        }
+    }
+}
+
+// ─── Activity ────────────────────────────────────────────────────────────────
+
+#[derive(Serialize)]
+struct ActivityJson {
+    timestamp_iso: String,
+    event_type: String,
+    entity_type: String,
+    entity_iid: i64,
+    project: String,
+    actor: Option<String>,
+    is_own: bool,
+    summary: String,
+    body_preview: Option<String>,
+}
+
+impl From<&MeActivityEvent> for ActivityJson {
+    fn from(e: &MeActivityEvent) -> Self {
+        Self {
+            timestamp_iso: ms_to_iso(e.timestamp),
+            event_type: event_type_str(&e.event_type),
+            entity_type: e.entity_type.clone(),
+            entity_iid: e.entity_iid,
+            project: e.project_path.clone(),
+            actor: e.actor.clone(),
+            is_own: e.is_own,
+            summary: e.summary.clone(),
+            body_preview: e.body_preview.clone(),
+        }
+    }
+}
+
+// ─── Since Last Check ────────────────────────────────────────────────────────
+
+#[derive(Serialize)]
+struct SinceLastCheckJson {
+    cursor_iso: String,
+    total_event_count: usize,
+    groups: Vec<SinceCheckGroupJson>,
+}
+
+impl From<&SinceLastCheck> for SinceLastCheckJson {
+    fn from(s: &SinceLastCheck) -> Self {
+        Self {
+            cursor_iso: ms_to_iso(s.cursor_ms),
+            total_event_count: s.total_event_count,
+            groups: s.groups.iter().map(SinceCheckGroupJson::from).collect(),
+        }
+    }
+}
+
+#[derive(Serialize)]
+struct SinceCheckGroupJson {
+    entity_type: String,
+    entity_iid: i64,
+    entity_title: String,
+    project: String,
+    events: Vec<SinceCheckEventJson>,
+}
+
+impl From<&SinceCheckGroup> for SinceCheckGroupJson {
+    fn from(g: &SinceCheckGroup) -> Self {
+        Self {
+            entity_type: g.entity_type.clone(),
+            entity_iid: g.entity_iid,
+            entity_title: g.entity_title.clone(),
+            project: g.project_path.clone(),
+            events: g.events.iter().map(SinceCheckEventJson::from).collect(),
+        }
+    }
+}
+
+#[derive(Serialize)]
+struct SinceCheckEventJson {
+    timestamp_iso: String,
+    event_type: String,
+    actor: Option<String>,
+    summary: String,
+    body_preview: Option<String>,
+}
+
+impl From<&SinceCheckEvent> for SinceCheckEventJson {
+    fn from(e: &SinceCheckEvent) -> Self {
+        Self {
+            timestamp_iso: ms_to_iso(e.timestamp),
+            event_type: event_type_str(&e.event_type),
+            actor: e.actor.clone(),
+            summary: e.summary.clone(),
+            body_preview: e.body_preview.clone(),
+        }
+    }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/// Convert `AttentionState` to its programmatic string representation.
+fn attention_state_str(state: &AttentionState) -> String {
+    match state {
+        AttentionState::NeedsAttention => "needs_attention",
+        AttentionState::NotStarted => "not_started",
+        AttentionState::AwaitingResponse => "awaiting_response",
+        AttentionState::Stale => "stale",
+        AttentionState::NotReady => "not_ready",
+    }
+    .to_string()
+}
+
+/// Convert `ActivityEventType` to its programmatic string representation.
+fn event_type_str(event_type: &ActivityEventType) -> String {
+    match event_type {
+        ActivityEventType::Note => "note",
+        ActivityEventType::StatusChange => "status_change",
+        ActivityEventType::LabelChange => "label_change",
+        ActivityEventType::Assign => "assign",
+        ActivityEventType::Unassign => "unassign",
+        ActivityEventType::ReviewRequest => "review_request",
+        ActivityEventType::MilestoneChange => "milestone_change",
+    }
+    .to_string()
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn attention_state_str_all_variants() {
+        assert_eq!(
+            attention_state_str(&AttentionState::NeedsAttention),
+            "needs_attention"
+        );
+        assert_eq!(
+            attention_state_str(&AttentionState::NotStarted),
+            "not_started"
+        );
+        assert_eq!(
+            attention_state_str(&AttentionState::AwaitingResponse),
+            "awaiting_response"
+        );
+        assert_eq!(attention_state_str(&AttentionState::Stale), "stale");
+        assert_eq!(attention_state_str(&AttentionState::NotReady), "not_ready");
+    }
+
+    #[test]
+    fn event_type_str_all_variants() {
+        assert_eq!(event_type_str(&ActivityEventType::Note), "note");
+        assert_eq!(
+            event_type_str(&ActivityEventType::StatusChange),
+            "status_change"
+        );
+        assert_eq!(
+            event_type_str(&ActivityEventType::LabelChange),
+            "label_change"
+        );
+        assert_eq!(event_type_str(&ActivityEventType::Assign), "assign");
+        assert_eq!(event_type_str(&ActivityEventType::Unassign), "unassign");
+        assert_eq!(
+            event_type_str(&ActivityEventType::ReviewRequest),
+            "review_request"
+        );
+        assert_eq!(
+            event_type_str(&ActivityEventType::MilestoneChange),
+            "milestone_change"
+        );
+    }
+
+    #[test]
+    fn issue_json_from_me_issue() {
+        let issue = MeIssue {
+            iid: 42,
+            title: "Fix auth bug".to_string(),
+            project_path: "group/repo".to_string(),
+            attention_state: AttentionState::NeedsAttention,
+            status_name: Some("In progress".to_string()),
+            labels: vec!["bug".to_string()],
+            updated_at: 1_700_000_000_000,
+            web_url: Some("https://gitlab.com/group/repo/-/issues/42".to_string()),
+        };
+        let json = IssueJson::from(&issue);
+        assert_eq!(json.iid, 42);
+        assert_eq!(json.attention_state, "needs_attention");
+        assert_eq!(json.state, "opened");
+        assert_eq!(json.status_name, Some("In progress".to_string()));
+    }
+
+    #[test]
+    fn mr_json_from_me_mr() {
+        let mr = MeMr {
+            iid: 99,
+            title: "Add feature".to_string(),
+            project_path: "group/repo".to_string(),
+            attention_state: AttentionState::AwaitingResponse,
+            draft: true,
+            detailed_merge_status: Some("mergeable".to_string()),
+            author_username: Some("alice".to_string()),
+            labels: vec![],
+            updated_at: 1_700_000_000_000,
+            web_url: None,
+        };
+        let json = MrJson::from(&mr);
+        assert_eq!(json.iid, 99);
+        assert_eq!(json.attention_state, "awaiting_response");
+        assert!(json.draft);
+        assert_eq!(json.author_username, Some("alice".to_string()));
+    }
+
+    #[test]
+    fn activity_json_from_event() {
+        let event = MeActivityEvent {
+            timestamp: 1_700_000_000_000,
+            event_type: ActivityEventType::Note,
+            entity_type: "issue".to_string(),
+            entity_iid: 42,
+            project_path: "group/repo".to_string(),
+            actor: Some("bob".to_string()),
+            is_own: false,
+            summary: "Added a comment".to_string(),
+            body_preview: Some("This looks good".to_string()),
+        };
+        let json = ActivityJson::from(&event);
+        assert_eq!(json.event_type, "note");
+        assert_eq!(json.entity_iid, 42);
+        assert!(!json.is_own);
+        assert_eq!(json.body_preview, Some("This looks good".to_string()));
+    }
+
+    #[test]
+    fn cursor_reset_envelope_includes_meta_elapsed_ms() {
+        let value = cursor_reset_envelope_json(17);
+        assert_eq!(value["ok"], serde_json::json!(true));
+        assert_eq!(value["data"]["cursor_reset"], serde_json::json!(true));
+        assert_eq!(value["meta"]["elapsed_ms"], serde_json::json!(17));
+    }
+}

src/cli/commands/me/types.rs

@@ -0,0 +1,127 @@
+// ─── Dashboard Types ─────────────────────────────────────────────────────────
+//
+// Data structs for the `lore me` personal dashboard.
+// These are populated by query functions and consumed by renderers.
+
+/// Attention state for a work item (AC-4.4).
+/// Ordered by display priority (first = most urgent).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum AttentionState {
+    /// Others commented after me (or I never engaged but others have)
+    NeedsAttention = 0,
+    /// Zero non-system notes from anyone
+    NotStarted = 1,
+    /// My latest note >= all others' latest notes
+    AwaitingResponse = 2,
+    /// Latest note from anyone is older than 30 days
+    Stale = 3,
+    /// MR-only: draft with no reviewers
+    NotReady = 4,
+}
+
+/// Activity event type for the feed (AC-5.4, AC-6.4).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ActivityEventType {
+    /// Human comment (non-system note)
+    Note,
+    /// State change (opened/closed/reopened/merged)
+    StatusChange,
+    /// Label added or removed
+    LabelChange,
+    /// Assignment event
+    Assign,
+    /// Unassignment event
+    Unassign,
+    /// Review request
+    ReviewRequest,
+    /// Milestone change
+    MilestoneChange,
+}
+
+/// Summary counts for the dashboard header (AC-5.5).
+pub struct MeSummary {
+    pub project_count: usize,
+    pub open_issue_count: usize,
+    pub authored_mr_count: usize,
+    pub reviewing_mr_count: usize,
+    pub needs_attention_count: usize,
+}
+
+/// An open issue assigned to the user (AC-5.1).
+pub struct MeIssue {
+    pub iid: i64,
+    pub title: String,
+    pub project_path: String,
+    pub attention_state: AttentionState,
+    pub status_name: Option<String>,
+    pub labels: Vec<String>,
+    pub updated_at: i64,
+    pub web_url: Option<String>,
+}
+
+/// An open MR authored by or reviewing for the user (AC-5.2, AC-5.3).
+pub struct MeMr {
+    pub iid: i64,
+    pub title: String,
+    pub project_path: String,
+    pub attention_state: AttentionState,
+    pub draft: bool,
+    pub detailed_merge_status: Option<String>,
+    pub author_username: Option<String>,
+    pub labels: Vec<String>,
+    pub updated_at: i64,
+    pub web_url: Option<String>,
+}
+
+/// An activity event in the feed (AC-5.4).
+pub struct MeActivityEvent {
+    pub timestamp: i64,
+    pub event_type: ActivityEventType,
+    pub entity_type: String,
+    pub entity_iid: i64,
+    pub project_path: String,
+    pub actor: Option<String>,
+    pub is_own: bool,
+    pub summary: String,
+    pub body_preview: Option<String>,
+}
+
+/// A single actionable event in the "since last check" section.
+#[derive(Clone)]
+pub struct SinceCheckEvent {
+    pub timestamp: i64,
+    pub event_type: ActivityEventType,
+    pub actor: Option<String>,
+    pub summary: String,
+    pub body_preview: Option<String>,
+}
+
+/// Events grouped by entity for the "since last check" section.
+#[derive(Clone)]
+pub struct SinceCheckGroup {
+    pub entity_type: String,
+    pub entity_iid: i64,
+    pub entity_title: String,
+    pub project_path: String,
+    pub events: Vec<SinceCheckEvent>,
+    pub latest_timestamp: i64,
+}
+
+/// The complete "since last check" result.
+pub struct SinceLastCheck {
+    pub cursor_ms: i64,
+    pub groups: Vec<SinceCheckGroup>,
+    pub total_event_count: usize,
+}
+
+/// The complete dashboard result.
+pub struct MeDashboard {
+    pub username: String,
+    pub since_ms: Option<i64>,
+    pub summary: MeSummary,
+    pub open_issues: Vec<MeIssue>,
+    pub open_mrs_authored: Vec<MeMr>,
+    pub reviewing_mrs: Vec<MeMr>,
+    pub activity: Vec<MeActivityEvent>,
+    pub since_last_check: Option<SinceLastCheck>,
+}

src/cli/commands/mod.rs

@@ -1,5 +1,7 @@
 pub mod auth_test;
 pub mod count;
+#[cfg(unix)]
+pub mod cron;
 pub mod doctor;
 pub mod drift;
 pub mod embed;
@@ -8,11 +10,14 @@ pub mod generate_docs;
 pub mod ingest;
 pub mod init;
 pub mod list;
+pub mod me;
+pub mod related;
 pub mod search;
 pub mod show;
 pub mod stats;
 pub mod sync;
 pub mod sync_status;
+pub mod sync_surgical;
 pub mod timeline;
 pub mod trace;
 pub mod who;
@@ -22,6 +27,12 @@ pub use count::{
     print_count, print_count_json, print_event_count, print_event_count_json, run_count,
     run_count_events,
 };
+#[cfg(unix)]
+pub use cron::{
+    print_cron_install, print_cron_install_json, print_cron_status, print_cron_status_json,
+    print_cron_uninstall, print_cron_uninstall_json, run_cron_install, run_cron_status,
+    run_cron_uninstall,
+};
 pub use doctor::{DoctorChecks, print_doctor_results, run_doctor};
 pub use drift::{DriftResponse, print_drift_human, print_drift_json, run_drift};
 pub use embed::{print_embed, print_embed_json, run_embed};
@@ -31,13 +42,14 @@ pub use ingest::{
     DryRunPreview, IngestDisplay, print_dry_run_preview, print_dry_run_preview_json,
     print_ingest_summary, print_ingest_summary_json, run_ingest, run_ingest_dry_run,
 };
-pub use init::{InitInputs, InitOptions, InitResult, run_init};
+pub use init::{InitInputs, InitOptions, InitResult, run_init, run_token_set, run_token_show};
 pub use list::{
     ListFilters, MrListFilters, NoteListFilters, open_issue_in_browser, open_mr_in_browser,
     print_list_issues, print_list_issues_json, print_list_mrs, print_list_mrs_json,
-    print_list_notes, print_list_notes_csv, print_list_notes_json, print_list_notes_jsonl,
-    query_notes, run_list_issues, run_list_mrs,
+    print_list_notes, print_list_notes_json, query_notes, run_list_issues, run_list_mrs,
 };
+pub use me::run_me;
+pub use related::{RelatedResponse, print_related_human, print_related_json, run_related};
 pub use search::{
     SearchCliFilters, SearchResponse, print_search_results, print_search_results_json, run_search,
 };
@@ -48,6 +60,7 @@ pub use show::{
 pub use stats::{print_stats, print_stats_json, run_stats};
 pub use sync::{SyncOptions, SyncResult, print_sync, print_sync_json, run_sync};
 pub use sync_status::{print_sync_status, print_sync_status_json, run_sync_status};
+pub use sync_surgical::run_sync_surgical;
 pub use timeline::{TimelineParams, print_timeline, print_timeline_json_with_meta, run_timeline};
 pub use trace::{parse_trace_path, print_trace, print_trace_json};
 pub use who::{WhoRun, print_who_human, print_who_json, run_who};

src/cli/commands/related.rs

@@ -0,0 +1,637 @@
+//! Semantic similarity discovery: find related entities via vector search.
+
+use std::collections::HashSet;
+
+use rusqlite::Connection;
+use serde::Serialize;
+
+use crate::cli::render::{Icons, Theme};
+use crate::cli::robot::RobotMeta;
+use crate::core::config::Config;
+use crate::core::db::create_connection;
+use crate::core::error::{LoreError, Result};
+use crate::core::paths::get_db_path;
+use crate::core::project::resolve_project;
+use crate::core::time::ms_to_iso;
+use crate::embedding::ollama::{OllamaClient, OllamaConfig};
+use crate::search::search_vector;
+
+// ---------------------------------------------------------------------------
+// Response types
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Serialize)]
+pub struct RelatedResponse {
+    pub mode: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source: Option<RelatedSource>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub query: Option<String>,
+    pub results: Vec<RelatedResult>,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub warnings: Vec<String>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct RelatedSource {
+    pub source_type: String,
+    pub iid: i64,
+    pub title: String,
+    pub project_path: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct RelatedResult {
+    pub source_type: String,
+    pub iid: i64,
+    pub title: String,
+    pub url: String,
+    pub similarity_score: f64,
+    pub project_path: String,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub shared_labels: Vec<String>,
+    pub author: Option<String>,
+    pub updated_at: String,
+}
+
+// ---------------------------------------------------------------------------
+// Internal row types
+// ---------------------------------------------------------------------------
+
+struct DocumentRow {
+    id: i64,
+    source_type: String,
+    source_id: i64,
+    #[allow(dead_code)]
+    project_id: i64,
+    #[allow(dead_code)]
+    title: Option<String>,
+    url: Option<String>,
+    content_text: String,
+    label_names: Option<String>,
+    author_username: Option<String>,
+    updated_at: Option<i64>,
+}
+
+struct EntityInfo {
+    #[allow(dead_code)]
+    iid: i64,
+    title: String,
+    project_path: String,
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/// Run the related command.
+///
+/// Modes:
+/// - Entity mode: `lore related issues 42` or `lore related mrs 99`
+/// - Query mode: `lore related 'search terms'`
+pub async fn run_related(
+    config: &Config,
+    query_or_type: &str,
+    iid: Option<i64>,
+    limit: usize,
+    project: Option<&str>,
+) -> Result<RelatedResponse> {
+    let db_path = get_db_path(config.storage.db_path.as_deref());
+    let conn = create_connection(&db_path)?;
+
+    // Check if embeddings exist
+    let embedding_count: i64 = conn
+        .query_row("SELECT COUNT(*) FROM embedding_metadata", [], |row| {
+            row.get(0)
+        })
+        .unwrap_or(0);
+
+    if embedding_count == 0 {
+        return Err(LoreError::Other(
+            "No embeddings found. Run 'lore embed' first to generate vector embeddings.".into(),
+        ));
+    }
+
+    // Validate input
+    if query_or_type.trim().is_empty() {
+        return Err(LoreError::Other(
+            "Query cannot be empty. Provide an entity type (issues/mrs) and IID, or a search query.".into(),
+        ));
+    }
+
+    // Determine mode: entity vs query
+    let entity_type = match query_or_type.to_lowercase().as_str() {
+        "issues" | "issue" | "i" => Some("issue"),
+        "mrs" | "mr" | "m" | "merge_request" => Some("merge_request"),
+        _ => None,
+    };
+
+    if let Some(etype) = entity_type {
+        // Entity mode
+        let iid = iid.ok_or_else(|| {
+            LoreError::Other("Entity mode requires an IID (e.g., 'lore related issues 42')".into())
+        })?;
+        run_related_entity(&conn, config, etype, iid, limit, project).await
+    } else {
+        // Query mode - treat query_or_type as free text
+        run_related_query(&conn, config, query_or_type, limit, project).await
+    }
+}
+
+async fn run_related_entity(
+    conn: &Connection,
+    config: &Config,
+    entity_type: &str,
+    iid: i64,
+    limit: usize,
+    project_filter: Option<&str>,
+) -> Result<RelatedResponse> {
+    // Find the source document
+    let source_doc = find_entity_document(conn, entity_type, iid, project_filter)?;
+    let source_info = get_entity_info(conn, entity_type, source_doc.source_id)?;
+
+    // Embed the source content
+    let embedding = embed_text(config, &source_doc.content_text).await?;
+
+    // Search for similar documents (limit + 1 to account for filtering self)
+    let vector_results = search_vector(conn, &embedding, limit.saturating_add(1))?;
+
+    // Filter out self and hydrate results
+    let source_labels = parse_label_names(&source_doc.label_names);
+    let mut results = Vec::new();
+    let mut warnings = Vec::new();
+
+    for vr in vector_results {
+        // Skip self
+        if vr.document_id == source_doc.id {
+            continue;
+        }
+
+        if let Some(result) = hydrate_result(conn, vr.document_id, vr.distance, &source_labels)? {
+            results.push(result);
+        }
+
+        if results.len() >= limit {
+            break;
+        }
+    }
+
+    // Check for low similarity
+    if !results.is_empty() && results.iter().all(|r| r.similarity_score < 0.3) {
+        warnings.push("No strongly related entities found (all scores < 0.3)".to_string());
+    }
+
+    Ok(RelatedResponse {
+        mode: "entity".to_string(),
+        source: Some(RelatedSource {
+            source_type: entity_type.to_string(),
+            iid,
+            title: source_info.title,
+            project_path: source_info.project_path,
+        }),
+        query: None,
+        results,
+        warnings,
+    })
+}
+
+async fn run_related_query(
+    conn: &Connection,
+    config: &Config,
+    query: &str,
+    limit: usize,
+    project_filter: Option<&str>,
+) -> Result<RelatedResponse> {
+    let mut warnings = Vec::new();
+
+    // Warn if query is very short
+    if query.split_whitespace().count() <= 2 {
+        warnings.push("Short queries may produce noisy results".to_string());
+    }
+
+    // Embed the query
+    let embedding = embed_text(config, query).await?;
+
+    // Search for similar documents (fetch extra to allow for project filtering)
+    let vector_results = search_vector(conn, &embedding, limit.saturating_mul(2))?;
+
+    // Filter by project if specified and hydrate
+    let project_id = project_filter
+        .map(|p| resolve_project(conn, p))
+        .transpose()?;
+
+    let mut results = Vec::new();
+    let empty_labels: HashSet<String> = HashSet::new();
+
+    for vr in vector_results {
+        // Check project filter
+        if let Some(pid) = project_id {
+            let doc_project_id: Option<i64> = conn
+                .query_row(
+                    "SELECT project_id FROM documents WHERE id = ?1",
+                    [vr.document_id],
+                    |row| row.get(0),
+                )
+                .ok();
+
+            if doc_project_id != Some(pid) {
+                continue;
+            }
+        }
+
+        if let Some(result) = hydrate_result(conn, vr.document_id, vr.distance, &empty_labels)? {
+            results.push(result);
+        }
+
+        if results.len() >= limit {
+            break;
+        }
+    }
+
+    // Check for low similarity
+    if !results.is_empty() && results.iter().all(|r| r.similarity_score < 0.3) {
+        warnings.push("No strongly related entities found (all scores < 0.3)".to_string());
+    }
+
+    Ok(RelatedResponse {
+        mode: "query".to_string(),
+        source: None,
+        query: Some(query.to_string()),
+        results,
+        warnings,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// DB helpers
+// ---------------------------------------------------------------------------
+
+fn find_entity_document(
+    conn: &Connection,
+    entity_type: &str,
+    iid: i64,
+    project_filter: Option<&str>,
+) -> Result<DocumentRow> {
+    let table = match entity_type {
+        "issue" => "issues",
+        "merge_request" => "merge_requests",
+        _ => {
+            return Err(LoreError::Other(format!(
+                "Unknown entity type: {entity_type}"
+            )));
+        }
+    };
+
+    let (sql, params): (String, Vec<Box<dyn rusqlite::ToSql>>) = match project_filter {
+        Some(project) => {
+            let project_id = resolve_project(conn, project)?;
+            (
+                format!(
+                    "SELECT d.id, d.source_type, d.source_id, d.project_id, d.title, d.url,
+                            d.content_text, d.label_names, d.author_username, d.updated_at
+                     FROM documents d
+                     JOIN {table} e ON d.source_id = e.id
+                     WHERE d.source_type = ?1 AND e.iid = ?2 AND e.project_id = ?3"
+                ),
+                vec![
+                    Box::new(entity_type.to_string()),
+                    Box::new(iid),
+                    Box::new(project_id),
+                ],
+            )
+        }
+        None => (
+            format!(
+                "SELECT d.id, d.source_type, d.source_id, d.project_id, d.title, d.url,
+                        d.content_text, d.label_names, d.author_username, d.updated_at
+                 FROM documents d
+                 JOIN {table} e ON d.source_id = e.id
+                 WHERE d.source_type = ?1 AND e.iid = ?2"
+            ),
+            vec![Box::new(entity_type.to_string()), Box::new(iid)],
+        ),
+    };
+
+    let param_refs: Vec<&dyn rusqlite::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+
+    let mut stmt = conn.prepare(&sql)?;
+    let rows: Vec<DocumentRow> = stmt
+        .query_map(param_refs.as_slice(), |row| {
+            Ok(DocumentRow {
+                id: row.get(0)?,
+                source_type: row.get(1)?,
+                source_id: row.get(2)?,
+                project_id: row.get(3)?,
+                title: row.get(4)?,
+                url: row.get(5)?,
+                content_text: row.get(6)?,
+                label_names: row.get(7)?,
+                author_username: row.get(8)?,
+                updated_at: row.get(9)?,
+            })
+        })?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    match rows.len() {
+        0 => Err(LoreError::NotFound(format!(
+            "{entity_type} #{iid} not found (run 'lore sync' first?)"
+        ))),
+        1 => Ok(rows.into_iter().next().unwrap()),
+        _ => Err(LoreError::Ambiguous(format!(
+            "{entity_type} #{iid} exists in multiple projects. Use --project to specify."
+        ))),
+    }
+}
+
+fn get_entity_info(conn: &Connection, entity_type: &str, entity_id: i64) -> Result<EntityInfo> {
+    let table = match entity_type {
+        "issue" => "issues",
+        "merge_request" => "merge_requests",
+        _ => {
+            return Err(LoreError::Other(format!(
+                "Unknown entity type: {entity_type}"
+            )));
+        }
+    };
+
+    let sql = format!(
+        "SELECT e.iid, e.title, p.path_with_namespace
+         FROM {table} e
+         JOIN projects p ON e.project_id = p.id
+         WHERE e.id = ?1"
+    );
+
+    conn.query_row(&sql, [entity_id], |row| {
+        Ok(EntityInfo {
+            iid: row.get(0)?,
+            title: row.get(1)?,
+            project_path: row.get(2)?,
+        })
+    })
+    .map_err(|e| LoreError::NotFound(format!("Entity not found: {e}")))
+}
+
+fn hydrate_result(
+    conn: &Connection,
+    document_id: i64,
+    distance: f64,
+    source_labels: &HashSet<String>,
+) -> Result<Option<RelatedResult>> {
+    let doc: Option<DocumentRow> = conn
+        .query_row(
+            "SELECT d.id, d.source_type, d.source_id, d.project_id, d.title, d.url,
+                    d.content_text, d.label_names, d.author_username, d.updated_at
+             FROM documents d
+             WHERE d.id = ?1",
+            [document_id],
+            |row| {
+                Ok(DocumentRow {
+                    id: row.get(0)?,
+                    source_type: row.get(1)?,
+                    source_id: row.get(2)?,
+                    project_id: row.get(3)?,
+                    title: row.get(4)?,
+                    url: row.get(5)?,
+                    content_text: row.get(6)?,
+                    label_names: row.get(7)?,
+                    author_username: row.get(8)?,
+                    updated_at: row.get(9)?,
+                })
+            },
+        )
+        .ok();
+
+    let Some(doc) = doc else {
+        return Ok(None);
+    };
+
+    // Skip discussion/note documents - we want entities only
+    if doc.source_type == "discussion" || doc.source_type == "note" {
+        return Ok(None);
+    }
+
+    // Get IID from the source entity
+    let table = match doc.source_type.as_str() {
+        "issue" => "issues",
+        "merge_request" => "merge_requests",
+        _ => return Ok(None),
+    };
+
+    // Get IID and title from the source entity - skip gracefully if not found
+    // (this handles orphaned documents where the entity was deleted)
+    let entity_info: Option<(i64, String, String)> = conn
+        .query_row(
+            &format!(
+                "SELECT e.iid, e.title, p.path_with_namespace
+                 FROM {table} e
+                 JOIN projects p ON e.project_id = p.id
+                 WHERE e.id = ?1"
+            ),
+            [doc.source_id],
+            |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
+        )
+        .ok();
+
+    let Some((iid, title, project_path)) = entity_info else {
+        // Entity not found in database - skip this result
+        return Ok(None);
+    };
+
+    // Compute shared labels
+    let result_labels = parse_label_names(&doc.label_names);
+    let shared_labels: Vec<String> = source_labels
+        .intersection(&result_labels)
+        .cloned()
+        .collect();
+
+    Ok(Some(RelatedResult {
+        source_type: doc.source_type,
+        iid,
+        title,
+        url: doc.url.unwrap_or_default(),
+        similarity_score: distance_to_similarity(distance),
+        project_path,
+        shared_labels,
+        author: doc.author_username,
+        updated_at: doc.updated_at.map(ms_to_iso).unwrap_or_default(),
+    }))
+}
+
+// ---------------------------------------------------------------------------
+// Embedding helper
+// ---------------------------------------------------------------------------
+
+async fn embed_text(config: &Config, text: &str) -> Result<Vec<f32>> {
+    let ollama = OllamaClient::new(OllamaConfig {
+        base_url: config.embedding.base_url.clone(),
+        model: config.embedding.model.clone(),
+        timeout_secs: 60,
+    });
+
+    let embeddings = ollama.embed_batch(&[text]).await?;
+    embeddings
+        .into_iter()
+        .next()
+        .ok_or_else(|| LoreError::EmbeddingFailed {
+            document_id: 0,
+            reason: "No embedding returned".to_string(),
+        })
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+/// Convert L2 distance to a 0-1 similarity score.
+/// Uses inverse relationship: closer (lower distance) = higher similarity.
+fn distance_to_similarity(distance: f64) -> f64 {
+    1.0 / (1.0 + distance)
+}
+
+fn parse_label_names(label_names_json: &Option<String>) -> HashSet<String> {
+    label_names_json
+        .as_deref()
+        .and_then(|s| serde_json::from_str::<Vec<String>>(s).ok())
+        .unwrap_or_default()
+        .into_iter()
+        .collect()
+}
+
+// ---------------------------------------------------------------------------
+// Printers
+// ---------------------------------------------------------------------------
+
+pub fn print_related_human(response: &RelatedResponse) {
+    // Header
+    let header = match &response.source {
+        Some(src) => format!("Related to {} #{}: {}", src.source_type, src.iid, src.title),
+        None => format!(
+            "Related to query: \"{}\"",
+            response.query.as_deref().unwrap_or("")
+        ),
+    };
+    println!("{}", Theme::bold().render(&header));
+    println!("{}", "-".repeat(header.len().min(70)));
+    println!();
+
+    if response.results.is_empty() {
+        println!("No related entities found.");
+        return;
+    }
+
+    for (i, result) in response.results.iter().enumerate() {
+        let type_icon = match result.source_type.as_str() {
+            "issue" => Icons::issue_opened(),
+            "merge_request" => Icons::mr_opened(),
+            _ => " ",
+        };
+
+        let score_bar_len = (result.similarity_score * 10.0) as usize;
+        let score_bar: String = "\u{2588}".repeat(score_bar_len);
+
+        println!(
+            "{:>2}. {} {} #{} ({:.0}%) {}",
+            i + 1,
+            type_icon,
+            result.source_type,
+            result.iid,
+            result.similarity_score * 100.0,
+            score_bar
+        );
+        println!("    {}", result.title);
+        println!(
+            "    {} | @{}",
+            result.project_path,
+            result.author.as_deref().unwrap_or("?")
+        );
+
+        if !result.shared_labels.is_empty() {
+            println!("    Labels shared: {}", result.shared_labels.join(", "));
+        }
+        println!();
+    }
+
+    // Warnings
+    for warning in &response.warnings {
+        println!("{} {}", Theme::warning().render(Icons::warning()), warning);
+    }
+}
+
+pub fn print_related_json(response: &RelatedResponse, elapsed_ms: u64) {
+    let meta = RobotMeta { elapsed_ms };
+    let output = serde_json::json!({
+        "ok": true,
+        "data": response,
+        "meta": meta,
+    });
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_distance_to_similarity_identical() {
+        assert!((distance_to_similarity(0.0) - 1.0).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn test_distance_to_similarity_midpoint() {
+        assert!((distance_to_similarity(1.0) - 0.5).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn test_distance_to_similarity_large() {
+        let sim = distance_to_similarity(2.0);
+        assert!(sim > 0.0 && sim < 0.5);
+        assert!((sim - 0.333_333_333_333_333_3).abs() < 0.001);
+    }
+
+    #[test]
+    fn test_distance_to_similarity_range() {
+        for d in [0.0, 0.1, 0.5, 1.0, 2.0, 5.0, 10.0] {
+            let sim = distance_to_similarity(d);
+            assert!(
+                sim > 0.0 && sim <= 1.0,
+                "score {sim} out of range for distance {d}"
+            );
+        }
+    }
+
+    #[test]
+    fn test_parse_label_names_valid() {
+        let json = Some(r#"["bug", "priority::high"]"#.to_string());
+        let labels = parse_label_names(&json);
+        assert!(labels.contains("bug"));
+        assert!(labels.contains("priority::high"));
+        assert_eq!(labels.len(), 2);
+    }
+
+    #[test]
+    fn test_parse_label_names_empty() {
+        let labels = parse_label_names(&None);
+        assert!(labels.is_empty());
+    }
+
+    #[test]
+    fn test_parse_label_names_invalid_json() {
+        let json = Some("not valid json".to_string());
+        let labels = parse_label_names(&json);
+        assert!(labels.is_empty());
+    }
+
+    #[test]
+    fn test_parse_label_names_empty_array() {
+        let json = Some("[]".to_string());
+        let labels = parse_label_names(&json);
+        assert!(labels.is_empty());
+    }
+}

src/cli/commands/search.rs

@@ -439,5 +439,8 @@ pub fn print_search_results_json(
         let expanded = crate::cli::robot::expand_fields_preset(f, "search");
         crate::cli::robot::filter_fields(&mut value, "results", &expanded);
     }
-    println!("{}", serde_json::to_string(&value).unwrap());
+    match serde_json::to_string(&value) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }

src/cli/commands/stats.rs

@@ -585,5 +585,8 @@ pub fn print_stats_json(result: &StatsResult, elapsed_ms: u64) {
         },
         meta: RobotMeta { elapsed_ms },
     };
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }

src/cli/commands/sync.rs

@@ -16,6 +16,7 @@ use super::ingest::{
     DryRunPreview, IngestDisplay, ProjectStatusEnrichment, ProjectSummary, run_ingest,
     run_ingest_dry_run,
 };
+use super::sync_surgical::run_sync_surgical;
 
 #[derive(Debug, Default)]
 pub struct SyncOptions {
@@ -26,6 +27,35 @@ pub struct SyncOptions {
     pub no_events: bool,
     pub robot_mode: bool,
     pub dry_run: bool,
+    pub issue_iids: Vec<u64>,
+    pub mr_iids: Vec<u64>,
+    pub project: Option<String>,
+    pub preflight_only: bool,
+}
+
+impl SyncOptions {
+    pub const MAX_SURGICAL_TARGETS: usize = 100;
+
+    pub fn is_surgical(&self) -> bool {
+        !self.issue_iids.is_empty() || !self.mr_iids.is_empty()
+    }
+}
+
+#[derive(Debug, Default, Serialize)]
+pub struct SurgicalIids {
+    pub issues: Vec<u64>,
+    pub merge_requests: Vec<u64>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct EntitySyncResult {
+    pub entity_type: String,
+    pub iid: u64,
+    pub outcome: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub toctou_reason: Option<String>,
 }
 
 #[derive(Debug, Default, Serialize)]
@@ -45,19 +75,23 @@ pub struct SyncResult {
     pub embedding_failed: usize,
     pub status_enrichment_errors: usize,
     pub statuses_enriched: usize,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub surgical_mode: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub surgical_iids: Option<SurgicalIids>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub entity_results: Option<Vec<EntitySyncResult>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub preflight_only: Option<bool>,
     #[serde(skip)]
     pub issue_projects: Vec<ProjectSummary>,
     #[serde(skip)]
     pub mr_projects: Vec<ProjectSummary>,
 }
 
-/// Apply semantic color to a stage-completion icon glyph.
+/// Alias for [`Theme::color_icon`] to keep call sites concise.
 fn color_icon(icon: &str, has_errors: bool) -> String {
-    if has_errors {
-        Theme::warning().render(icon)
-    } else {
-        Theme::success().render(icon)
-    }
+    Theme::color_icon(icon, has_errors)
 }
 
 pub async fn run_sync(
@@ -66,6 +100,11 @@ pub async fn run_sync(
     run_id: Option<&str>,
     signal: &ShutdownSignal,
 ) -> Result<SyncResult> {
+    // Surgical dispatch: if any IIDs specified, route to surgical pipeline
+    if options.is_surgical() {
+        return run_sync_surgical(config, options, run_id, signal).await;
+    }
+
     let generated_id;
     let run_id = match run_id {
         Some(id) => id,
@@ -746,7 +785,10 @@ pub fn print_sync_json(result: &SyncResult, elapsed_ms: u64, metrics: Option<&Me
             stages,
         },
     };
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 #[derive(Debug, Default, Serialize)]
@@ -880,13 +922,32 @@ pub fn print_sync_dry_run_json(result: &SyncDryRunResult) {
         },
     };
 
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    fn default_options() -> SyncOptions {
+        SyncOptions {
+            full: false,
+            force: false,
+            no_embed: false,
+            no_docs: false,
+            no_events: false,
+            robot_mode: false,
+            dry_run: false,
+            issue_iids: vec![],
+            mr_iids: vec![],
+            project: None,
+            preflight_only: false,
+        }
+    }
+
     #[test]
     fn append_failures_skips_zeroes() {
         let mut summary = "base".to_string();
@@ -1029,4 +1090,112 @@ mod tests {
         assert!(rows[0].contains("0 statuses updated"));
         assert!(rows[0].contains("skipped (disabled)"));
     }
+
+    #[test]
+    fn is_surgical_with_issues() {
+        let opts = SyncOptions {
+            issue_iids: vec![1],
+            ..default_options()
+        };
+        assert!(opts.is_surgical());
+    }
+
+    #[test]
+    fn is_surgical_with_mrs() {
+        let opts = SyncOptions {
+            mr_iids: vec![10],
+            ..default_options()
+        };
+        assert!(opts.is_surgical());
+    }
+
+    #[test]
+    fn is_surgical_empty() {
+        let opts = default_options();
+        assert!(!opts.is_surgical());
+    }
+
+    #[test]
+    fn max_surgical_targets_is_100() {
+        assert_eq!(SyncOptions::MAX_SURGICAL_TARGETS, 100);
+    }
+
+    #[test]
+    fn sync_result_default_omits_surgical_fields() {
+        let result = SyncResult::default();
+        let json = serde_json::to_value(&result).unwrap();
+        assert!(json.get("surgical_mode").is_none());
+        assert!(json.get("surgical_iids").is_none());
+        assert!(json.get("entity_results").is_none());
+        assert!(json.get("preflight_only").is_none());
+    }
+
+    #[test]
+    fn sync_result_with_surgical_fields_serializes_correctly() {
+        let result = SyncResult {
+            surgical_mode: Some(true),
+            surgical_iids: Some(SurgicalIids {
+                issues: vec![7, 42],
+                merge_requests: vec![10],
+            }),
+            entity_results: Some(vec![
+                EntitySyncResult {
+                    entity_type: "issue".to_string(),
+                    iid: 7,
+                    outcome: "synced".to_string(),
+                    error: None,
+                    toctou_reason: None,
+                },
+                EntitySyncResult {
+                    entity_type: "issue".to_string(),
+                    iid: 42,
+                    outcome: "skipped_toctou".to_string(),
+                    error: None,
+                    toctou_reason: Some("updated_at changed".to_string()),
+                },
+            ]),
+            preflight_only: Some(false),
+            ..SyncResult::default()
+        };
+        let json = serde_json::to_value(&result).unwrap();
+        assert_eq!(json["surgical_mode"], true);
+        assert_eq!(json["surgical_iids"]["issues"], serde_json::json!([7, 42]));
+        assert_eq!(json["entity_results"].as_array().unwrap().len(), 2);
+        assert_eq!(json["entity_results"][1]["outcome"], "skipped_toctou");
+        assert_eq!(json["preflight_only"], false);
+    }
+
+    #[test]
+    fn entity_sync_result_omits_none_fields() {
+        let entity = EntitySyncResult {
+            entity_type: "merge_request".to_string(),
+            iid: 10,
+            outcome: "synced".to_string(),
+            error: None,
+            toctou_reason: None,
+        };
+        let json = serde_json::to_value(&entity).unwrap();
+        assert!(json.get("error").is_none());
+        assert!(json.get("toctou_reason").is_none());
+        assert!(json.get("entity_type").is_some());
+    }
+
+    #[test]
+    fn is_surgical_with_both_issues_and_mrs() {
+        let opts = SyncOptions {
+            issue_iids: vec![1, 2],
+            mr_iids: vec![10],
+            ..default_options()
+        };
+        assert!(opts.is_surgical());
+    }
+
+    #[test]
+    fn is_not_surgical_with_only_project() {
+        let opts = SyncOptions {
+            project: Some("group/repo".to_string()),
+            ..default_options()
+        };
+        assert!(!opts.is_surgical());
+    }
 }

src/cli/commands/sync_status.rs

@@ -12,6 +12,10 @@ use crate::core::time::{format_full_datetime, ms_to_iso};
 
 const RECENT_RUNS_LIMIT: usize = 10;
 
+fn is_zero(value: &i64) -> bool {
+    *value == 0
+}
+
 #[derive(Debug)]
 pub struct SyncRunInfo {
     pub id: i64,
@@ -24,6 +28,15 @@ pub struct SyncRunInfo {
     pub total_items_processed: i64,
     pub total_errors: i64,
     pub stages: Option<Vec<StageTiming>>,
+    // Per-entity counts (from migration 027)
+    pub issues_fetched: i64,
+    pub issues_ingested: i64,
+    pub mrs_fetched: i64,
+    pub mrs_ingested: i64,
+    pub skipped_stale: i64,
+    pub docs_regenerated: i64,
+    pub docs_embedded: i64,
+    pub warnings_count: i64,
 }
 
 #[derive(Debug)]
@@ -68,7 +81,9 @@ pub fn run_sync_status(config: &Config) -> Result<SyncStatusResult> {
 fn get_recent_sync_runs(conn: &Connection, limit: usize) -> Result<Vec<SyncRunInfo>> {
     let mut stmt = conn.prepare(
         "SELECT id, started_at, finished_at, status, command, error,
-                run_id, total_items_processed, total_errors, metrics_json
+                run_id, total_items_processed, total_errors, metrics_json,
+                issues_fetched, issues_ingested, mrs_fetched, mrs_ingested,
+                skipped_stale, docs_regenerated, docs_embedded, warnings_count
          FROM sync_runs
          ORDER BY started_at DESC
          LIMIT ?1",
@@ -91,6 +106,14 @@ fn get_recent_sync_runs(conn: &Connection, limit: usize) -> Result<Vec<SyncRunIn
                 total_items_processed: row.get::<_, Option<i64>>(7)?.unwrap_or(0),
                 total_errors: row.get::<_, Option<i64>>(8)?.unwrap_or(0),
                 stages,
+                issues_fetched: row.get::<_, Option<i64>>(10)?.unwrap_or(0),
+                issues_ingested: row.get::<_, Option<i64>>(11)?.unwrap_or(0),
+                mrs_fetched: row.get::<_, Option<i64>>(12)?.unwrap_or(0),
+                mrs_ingested: row.get::<_, Option<i64>>(13)?.unwrap_or(0),
+                skipped_stale: row.get::<_, Option<i64>>(14)?.unwrap_or(0),
+                docs_regenerated: row.get::<_, Option<i64>>(15)?.unwrap_or(0),
+                docs_embedded: row.get::<_, Option<i64>>(16)?.unwrap_or(0),
+                warnings_count: row.get::<_, Option<i64>>(17)?.unwrap_or(0),
             })
         })?
         .collect();
@@ -198,6 +221,23 @@ struct SyncRunJsonInfo {
     error: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     stages: Option<Vec<StageTiming>>,
+    // Per-entity counts
+    #[serde(skip_serializing_if = "is_zero")]
+    issues_fetched: i64,
+    #[serde(skip_serializing_if = "is_zero")]
+    issues_ingested: i64,
+    #[serde(skip_serializing_if = "is_zero")]
+    mrs_fetched: i64,
+    #[serde(skip_serializing_if = "is_zero")]
+    mrs_ingested: i64,
+    #[serde(skip_serializing_if = "is_zero")]
+    skipped_stale: i64,
+    #[serde(skip_serializing_if = "is_zero")]
+    docs_regenerated: i64,
+    #[serde(skip_serializing_if = "is_zero")]
+    docs_embedded: i64,
+    #[serde(skip_serializing_if = "is_zero")]
+    warnings_count: i64,
 }
 
 #[derive(Serialize)]
@@ -237,6 +277,14 @@ pub fn print_sync_status_json(result: &SyncStatusResult, elapsed_ms: u64) {
                 total_errors: run.total_errors,
                 error: run.error.clone(),
                 stages: run.stages.clone(),
+                issues_fetched: run.issues_fetched,
+                issues_ingested: run.issues_ingested,
+                mrs_fetched: run.mrs_fetched,
+                mrs_ingested: run.mrs_ingested,
+                skipped_stale: run.skipped_stale,
+                docs_regenerated: run.docs_regenerated,
+                docs_embedded: run.docs_embedded,
+                warnings_count: run.warnings_count,
             }
         })
         .collect();
@@ -268,7 +316,10 @@ pub fn print_sync_status_json(result: &SyncStatusResult, elapsed_ms: u64) {
         meta: RobotMeta { elapsed_ms },
     };
 
-    println!("{}", serde_json::to_string(&output).unwrap());
+    match serde_json::to_string(&output) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 pub fn print_sync_status(result: &SyncStatusResult) {

src/cli/commands/sync_surgical.rs

@@ -0,0 +1,711 @@
+use std::time::Instant;
+
+use tracing::{Instrument, debug, info, warn};
+
+use crate::Config;
+use crate::cli::commands::sync::{EntitySyncResult, SurgicalIids, SyncOptions, SyncResult};
+use crate::cli::progress::{format_stage_line, stage_spinner_v2};
+use crate::cli::render::{Icons, Theme};
+use crate::core::db::{LATEST_SCHEMA_VERSION, create_connection, get_schema_version};
+use crate::core::error::{LoreError, Result};
+use crate::core::lock::{AppLock, LockOptions};
+use crate::core::paths::get_db_path;
+use crate::core::project::resolve_project;
+use crate::core::shutdown::ShutdownSignal;
+use crate::core::sync_run::SyncRunRecorder;
+use crate::documents::{SourceType, regenerate_dirty_documents_for_sources};
+use crate::embedding::ollama::{OllamaClient, OllamaConfig};
+use crate::embedding::pipeline::{DEFAULT_EMBED_CONCURRENCY, embed_documents_by_ids};
+use crate::gitlab::GitLabClient;
+use crate::ingestion::surgical::{
+    fetch_dependents_for_issue, fetch_dependents_for_mr, ingest_issue_by_iid, ingest_mr_by_iid,
+    preflight_fetch,
+};
+
+pub async fn run_sync_surgical(
+    config: &Config,
+    options: SyncOptions,
+    run_id: Option<&str>,
+    signal: &ShutdownSignal,
+) -> Result<SyncResult> {
+    // ── Generate run_id ──
+    let generated_id;
+    let run_id = match run_id {
+        Some(id) => id,
+        None => {
+            generated_id = uuid::Uuid::new_v4().simple().to_string();
+            &generated_id[..8]
+        }
+    };
+    let span = tracing::info_span!("surgical_sync", %run_id);
+
+    async move {
+        let pipeline_start = Instant::now();
+        let mut result = SyncResult {
+            run_id: run_id.to_string(),
+            surgical_mode: Some(true),
+            surgical_iids: Some(SurgicalIids {
+                issues: options.issue_iids.clone(),
+                merge_requests: options.mr_iids.clone(),
+            }),
+            ..SyncResult::default()
+        };
+        let mut entity_results: Vec<EntitySyncResult> = Vec::new();
+
+        // ── Resolve project ──
+        let project_str = options.project.as_deref().ok_or_else(|| {
+            LoreError::Other(
+                "Surgical sync requires --project. Specify the project path.".to_string(),
+            )
+        })?;
+
+        let db_path = get_db_path(config.storage.db_path.as_deref());
+        let conn = create_connection(&db_path)?;
+
+        let schema_version = get_schema_version(&conn);
+        if schema_version < LATEST_SCHEMA_VERSION {
+            return Err(LoreError::MigrationFailed {
+                version: schema_version,
+                message: format!(
+                    "Database is at schema version {schema_version} but {LATEST_SCHEMA_VERSION} is required. \
+                     Run 'lore sync' first to apply migrations."
+                ),
+                source: None,
+            });
+        }
+
+        let project_id = resolve_project(&conn, project_str)?;
+
+        let gitlab_project_id: i64 = conn.query_row(
+            "SELECT gitlab_project_id FROM projects WHERE id = ?1",
+            [project_id],
+            |row| row.get(0),
+        )?;
+
+        debug!(
+            project_str,
+            project_id,
+            gitlab_project_id,
+            "Resolved project for surgical sync"
+        );
+
+        // ── Start recorder ──
+        let recorder_conn = create_connection(&db_path)?;
+        let recorder = SyncRunRecorder::start(&recorder_conn, "surgical-sync", run_id)?;
+
+        let iids_json = serde_json::to_string(&SurgicalIids {
+            issues: options.issue_iids.clone(),
+            merge_requests: options.mr_iids.clone(),
+        })
+        .unwrap_or_else(|_| "{}".to_string());
+
+        recorder.set_surgical_metadata(&recorder_conn, "surgical", "preflight", &iids_json)?;
+
+        // Wrap recorder in Option for consuming terminal methods
+        let mut recorder = Some(recorder);
+
+        // ── Build GitLab client ──
+        let token = config.gitlab.resolve_token()?;
+        let client = GitLabClient::new(
+            &config.gitlab.base_url,
+            &token,
+            Some(config.sync.requests_per_second),
+        );
+
+        // ── Build targets list ──
+        let mut targets: Vec<(String, i64)> = Vec::new();
+        for iid in &options.issue_iids {
+            targets.push(("issue".to_string(), *iid as i64));
+        }
+        for iid in &options.mr_iids {
+            targets.push(("merge_request".to_string(), *iid as i64));
+        }
+
+        // ── Stage: Preflight ──
+        let stage_start = Instant::now();
+        let spinner =
+            stage_spinner_v2(Icons::sync(), "Preflight", "fetching...", options.robot_mode);
+
+        info!(targets = targets.len(), "Preflight: fetching entities from GitLab");
+        let preflight = preflight_fetch(&client, gitlab_project_id, &targets).await;
+
+        // Record preflight failures
+        for failure in &preflight.failures {
+            let is_not_found = matches!(&failure.error, LoreError::GitLabNotFound { .. });
+            entity_results.push(EntitySyncResult {
+                entity_type: failure.entity_type.clone(),
+                iid: failure.iid as u64,
+                outcome: if is_not_found {
+                    "not_found".to_string()
+                } else {
+                    "preflight_failed".to_string()
+                },
+                error: Some(failure.error.to_string()),
+                toctou_reason: None,
+            });
+            if let Some(ref rec) = recorder {
+                let _ = rec.record_entity_result(&recorder_conn, &failure.entity_type, "warning");
+            }
+        }
+
+        let preflight_summary = format!(
+            "{} issues, {} MRs fetched ({} failed)",
+            preflight.issues.len(),
+            preflight.merge_requests.len(),
+            preflight.failures.len()
+        );
+        let preflight_icon = color_icon(
+            if preflight.failures.is_empty() {
+                Icons::success()
+            } else {
+                Icons::warning()
+            },
+            !preflight.failures.is_empty(),
+        );
+        emit_stage_line(
+            &spinner,
+            &preflight_icon,
+            "Preflight",
+            &preflight_summary,
+            stage_start.elapsed(),
+            options.robot_mode,
+        );
+
+        // ── Preflight-only early return ──
+        if options.preflight_only {
+            result.preflight_only = Some(true);
+            result.entity_results = Some(entity_results);
+            if let Some(rec) = recorder.take() {
+                rec.succeed(&recorder_conn, &[], 0, preflight.failures.len())?;
+            }
+            return Ok(result);
+        }
+
+        // ── Check cancellation ──
+        if signal.is_cancelled() {
+            if let Some(rec) = recorder.take() {
+                rec.cancel(&recorder_conn, "cancelled before ingest")?;
+            }
+            result.entity_results = Some(entity_results);
+            return Ok(result);
+        }
+
+        // ── Acquire lock ──
+        let lock_conn = create_connection(&db_path)?;
+        let mut lock = AppLock::new(
+            lock_conn,
+            LockOptions {
+                name: "sync".to_string(),
+                stale_lock_minutes: config.sync.stale_lock_minutes,
+                heartbeat_interval_seconds: config.sync.heartbeat_interval_seconds,
+            },
+        );
+        lock.acquire(options.force)?;
+
+        // Wrap the rest in a closure-like block to ensure lock release on error
+        let pipeline_result = run_pipeline_stages(
+            &conn,
+            &recorder_conn,
+            config,
+            &client,
+            &options,
+            &preflight,
+            project_id,
+            gitlab_project_id,
+            &mut entity_results,
+            &mut result,
+            recorder.as_ref(),
+            signal,
+        )
+        .await;
+
+        match pipeline_result {
+            Ok(()) => {
+                // ── Finalize: succeed ──
+                if let Some(ref rec) = recorder {
+                    let _ = rec.update_phase(&recorder_conn, "finalize");
+                }
+                let total_items = result.issues_updated
+                    + result.mrs_updated
+                    + result.documents_regenerated
+                    + result.documents_embedded;
+                let total_errors = result.documents_errored
+                    + result.embedding_failed
+                    + entity_results
+                        .iter()
+                        .filter(|e| e.outcome != "synced" && e.outcome != "skipped_stale")
+                        .count();
+                if let Some(rec) = recorder.take() {
+                    rec.succeed(&recorder_conn, &[], total_items, total_errors)?;
+                }
+            }
+            Err(ref e) => {
+                if let Some(rec) = recorder.take() {
+                    let _ = rec.fail(&recorder_conn, &e.to_string(), None);
+                }
+            }
+        }
+
+        lock.release();
+
+        // Propagate error after cleanup
+        pipeline_result?;
+
+        result.entity_results = Some(entity_results);
+
+        let elapsed = pipeline_start.elapsed();
+        debug!(
+            elapsed_ms = elapsed.as_millis(),
+            issues = result.issues_updated,
+            mrs = result.mrs_updated,
+            docs = result.documents_regenerated,
+            embedded = result.documents_embedded,
+            "Surgical sync pipeline complete"
+        );
+
+        Ok(result)
+    }
+    .instrument(span)
+    .await
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn run_pipeline_stages(
+    conn: &rusqlite::Connection,
+    recorder_conn: &rusqlite::Connection,
+    config: &Config,
+    client: &GitLabClient,
+    options: &SyncOptions,
+    preflight: &crate::ingestion::surgical::PreflightResult,
+    project_id: i64,
+    gitlab_project_id: i64,
+    entity_results: &mut Vec<EntitySyncResult>,
+    result: &mut SyncResult,
+    recorder: Option<&SyncRunRecorder>,
+    signal: &ShutdownSignal,
+) -> Result<()> {
+    let mut all_dirty_source_keys: Vec<(SourceType, i64)> = Vec::new();
+
+    // ── Stage: Ingest ──
+    if let Some(rec) = recorder {
+        rec.update_phase(recorder_conn, "ingest")?;
+    }
+
+    let stage_start = Instant::now();
+    let spinner = stage_spinner_v2(Icons::sync(), "Ingest", "processing...", options.robot_mode);
+
+    // Ingest issues
+    for issue in &preflight.issues {
+        match ingest_issue_by_iid(conn, config, project_id, issue) {
+            Ok(ingest_result) => {
+                if ingest_result.skipped_stale {
+                    entity_results.push(EntitySyncResult {
+                        entity_type: "issue".to_string(),
+                        iid: issue.iid as u64,
+                        outcome: "skipped_stale".to_string(),
+                        error: None,
+                        toctou_reason: Some("updated_at not newer than DB".to_string()),
+                    });
+                    if let Some(rec) = recorder {
+                        let _ = rec.record_entity_result(recorder_conn, "issue", "skipped_stale");
+                    }
+                } else {
+                    result.issues_updated += 1;
+                    all_dirty_source_keys.extend(ingest_result.dirty_source_keys);
+                    entity_results.push(EntitySyncResult {
+                        entity_type: "issue".to_string(),
+                        iid: issue.iid as u64,
+                        outcome: "synced".to_string(),
+                        error: None,
+                        toctou_reason: None,
+                    });
+                    if let Some(rec) = recorder {
+                        let _ = rec.record_entity_result(recorder_conn, "issue", "ingested");
+                    }
+                }
+            }
+            Err(e) => {
+                warn!(iid = issue.iid, error = %e, "Failed to ingest issue");
+                entity_results.push(EntitySyncResult {
+                    entity_type: "issue".to_string(),
+                    iid: issue.iid as u64,
+                    outcome: "error".to_string(),
+                    error: Some(e.to_string()),
+                    toctou_reason: None,
+                });
+                if let Some(rec) = recorder {
+                    let _ = rec.record_entity_result(recorder_conn, "issue", "warning");
+                }
+            }
+        }
+    }
+
+    // Ingest MRs
+    for mr in &preflight.merge_requests {
+        match ingest_mr_by_iid(conn, config, project_id, mr) {
+            Ok(ingest_result) => {
+                if ingest_result.skipped_stale {
+                    entity_results.push(EntitySyncResult {
+                        entity_type: "merge_request".to_string(),
+                        iid: mr.iid as u64,
+                        outcome: "skipped_stale".to_string(),
+                        error: None,
+                        toctou_reason: Some("updated_at not newer than DB".to_string()),
+                    });
+                    if let Some(rec) = recorder {
+                        let _ = rec.record_entity_result(recorder_conn, "mr", "skipped_stale");
+                    }
+                } else {
+                    result.mrs_updated += 1;
+                    all_dirty_source_keys.extend(ingest_result.dirty_source_keys);
+                    entity_results.push(EntitySyncResult {
+                        entity_type: "merge_request".to_string(),
+                        iid: mr.iid as u64,
+                        outcome: "synced".to_string(),
+                        error: None,
+                        toctou_reason: None,
+                    });
+                    if let Some(rec) = recorder {
+                        let _ = rec.record_entity_result(recorder_conn, "mr", "ingested");
+                    }
+                }
+            }
+            Err(e) => {
+                warn!(iid = mr.iid, error = %e, "Failed to ingest MR");
+                entity_results.push(EntitySyncResult {
+                    entity_type: "merge_request".to_string(),
+                    iid: mr.iid as u64,
+                    outcome: "error".to_string(),
+                    error: Some(e.to_string()),
+                    toctou_reason: None,
+                });
+                if let Some(rec) = recorder {
+                    let _ = rec.record_entity_result(recorder_conn, "mr", "warning");
+                }
+            }
+        }
+    }
+
+    let ingest_summary = format!(
+        "{} issues, {} MRs ingested",
+        result.issues_updated, result.mrs_updated
+    );
+    let ingest_icon = color_icon(Icons::success(), false);
+    emit_stage_line(
+        &spinner,
+        &ingest_icon,
+        "Ingest",
+        &ingest_summary,
+        stage_start.elapsed(),
+        options.robot_mode,
+    );
+
+    // ── Check cancellation ──
+    if signal.is_cancelled() {
+        debug!("Shutdown requested after ingest stage");
+        return Ok(());
+    }
+
+    // ── Stage: Dependents ──
+    if let Some(rec) = recorder {
+        rec.update_phase(recorder_conn, "dependents")?;
+    }
+
+    let stage_start = Instant::now();
+    let spinner = stage_spinner_v2(
+        Icons::sync(),
+        "Dependents",
+        "fetching...",
+        options.robot_mode,
+    );
+
+    let mut total_discussions: usize = 0;
+    let mut total_events: usize = 0;
+
+    // Fetch dependents for successfully ingested issues
+    for issue in &preflight.issues {
+        // Only fetch dependents for entities that were actually ingested
+        let was_ingested = entity_results.iter().any(|e| {
+            e.entity_type == "issue" && e.iid == issue.iid as u64 && e.outcome == "synced"
+        });
+        if !was_ingested {
+            continue;
+        }
+
+        let local_id: i64 = match conn.query_row(
+            "SELECT id FROM issues WHERE project_id = ?1 AND iid = ?2",
+            (project_id, issue.iid),
+            |row| row.get(0),
+        ) {
+            Ok(id) => id,
+            Err(e) => {
+                warn!(iid = issue.iid, error = %e, "Could not find local issue ID for dependents");
+                continue;
+            }
+        };
+
+        match fetch_dependents_for_issue(
+            client,
+            conn,
+            project_id,
+            gitlab_project_id,
+            issue.iid,
+            local_id,
+            config,
+        )
+        .await
+        {
+            Ok(dep_result) => {
+                total_discussions += dep_result.discussions_fetched;
+                total_events += dep_result.resource_events_fetched;
+                result.discussions_fetched += dep_result.discussions_fetched;
+                result.resource_events_fetched += dep_result.resource_events_fetched;
+            }
+            Err(e) => {
+                warn!(iid = issue.iid, error = %e, "Failed to fetch dependents for issue");
+            }
+        }
+    }
+
+    // Fetch dependents for successfully ingested MRs
+    for mr in &preflight.merge_requests {
+        let was_ingested = entity_results.iter().any(|e| {
+            e.entity_type == "merge_request" && e.iid == mr.iid as u64 && e.outcome == "synced"
+        });
+        if !was_ingested {
+            continue;
+        }
+
+        let local_id: i64 = match conn.query_row(
+            "SELECT id FROM merge_requests WHERE project_id = ?1 AND iid = ?2",
+            (project_id, mr.iid),
+            |row| row.get(0),
+        ) {
+            Ok(id) => id,
+            Err(e) => {
+                warn!(iid = mr.iid, error = %e, "Could not find local MR ID for dependents");
+                continue;
+            }
+        };
+
+        match fetch_dependents_for_mr(
+            client,
+            conn,
+            project_id,
+            gitlab_project_id,
+            mr.iid,
+            local_id,
+            config,
+        )
+        .await
+        {
+            Ok(dep_result) => {
+                total_discussions += dep_result.discussions_fetched;
+                total_events += dep_result.resource_events_fetched;
+                result.discussions_fetched += dep_result.discussions_fetched;
+                result.resource_events_fetched += dep_result.resource_events_fetched;
+                result.mr_diffs_fetched += dep_result.file_changes_stored;
+            }
+            Err(e) => {
+                warn!(iid = mr.iid, error = %e, "Failed to fetch dependents for MR");
+            }
+        }
+    }
+
+    let dep_summary = format!("{} discussions, {} events", total_discussions, total_events);
+    let dep_icon = color_icon(Icons::success(), false);
+    emit_stage_line(
+        &spinner,
+        &dep_icon,
+        "Dependents",
+        &dep_summary,
+        stage_start.elapsed(),
+        options.robot_mode,
+    );
+
+    // ── Check cancellation ──
+    if signal.is_cancelled() {
+        debug!("Shutdown requested after dependents stage");
+        return Ok(());
+    }
+
+    // ── Stage: Docs ──
+    if !options.no_docs && !all_dirty_source_keys.is_empty() {
+        if let Some(rec) = recorder {
+            rec.update_phase(recorder_conn, "docs")?;
+        }
+
+        let stage_start = Instant::now();
+        let spinner =
+            stage_spinner_v2(Icons::sync(), "Docs", "regenerating...", options.robot_mode);
+
+        let docs_result = regenerate_dirty_documents_for_sources(conn, &all_dirty_source_keys)?;
+        result.documents_regenerated = docs_result.regenerated;
+        result.documents_errored = docs_result.errored;
+
+        for _ in 0..docs_result.regenerated {
+            if let Some(rec) = recorder {
+                let _ = rec.record_entity_result(recorder_conn, "doc", "regenerated");
+            }
+        }
+
+        let docs_summary = format!("{} documents regenerated", result.documents_regenerated);
+        let docs_icon = color_icon(
+            if docs_result.errored > 0 {
+                Icons::warning()
+            } else {
+                Icons::success()
+            },
+            docs_result.errored > 0,
+        );
+        emit_stage_line(
+            &spinner,
+            &docs_icon,
+            "Docs",
+            &docs_summary,
+            stage_start.elapsed(),
+            options.robot_mode,
+        );
+
+        // ── Check cancellation ──
+        if signal.is_cancelled() {
+            debug!("Shutdown requested after docs stage");
+            return Ok(());
+        }
+
+        // ── Stage: Embed ──
+        if !options.no_embed && !docs_result.document_ids.is_empty() {
+            if let Some(rec) = recorder {
+                rec.update_phase(recorder_conn, "embed")?;
+            }
+
+            let stage_start = Instant::now();
+            let spinner =
+                stage_spinner_v2(Icons::sync(), "Embed", "embedding...", options.robot_mode);
+
+            let ollama_config = OllamaConfig {
+                base_url: config.embedding.base_url.clone(),
+                model: config.embedding.model.clone(),
+                ..OllamaConfig::default()
+            };
+            let ollama_client = OllamaClient::new(ollama_config);
+
+            let model_name = &config.embedding.model;
+            let concurrency = if config.embedding.concurrency > 0 {
+                config.embedding.concurrency as usize
+            } else {
+                DEFAULT_EMBED_CONCURRENCY
+            };
+
+            match embed_documents_by_ids(
+                conn,
+                &ollama_client,
+                model_name,
+                concurrency,
+                &docs_result.document_ids,
+                signal,
+            )
+            .await
+            {
+                Ok(embed_result) => {
+                    result.documents_embedded = embed_result.docs_embedded;
+                    result.embedding_failed = embed_result.failed;
+
+                    for _ in 0..embed_result.docs_embedded {
+                        if let Some(rec) = recorder {
+                            let _ = rec.record_entity_result(recorder_conn, "doc", "embedded");
+                        }
+                    }
+
+                    let embed_summary = format!("{} chunks embedded", embed_result.chunks_embedded);
+                    let embed_icon = color_icon(
+                        if embed_result.failed > 0 {
+                            Icons::warning()
+                        } else {
+                            Icons::success()
+                        },
+                        embed_result.failed > 0,
+                    );
+                    emit_stage_line(
+                        &spinner,
+                        &embed_icon,
+                        "Embed",
+                        &embed_summary,
+                        stage_start.elapsed(),
+                        options.robot_mode,
+                    );
+                }
+                Err(e) => {
+                    let warn_summary = format!("skipped ({})", e);
+                    let warn_icon = color_icon(Icons::warning(), true);
+                    emit_stage_line(
+                        &spinner,
+                        &warn_icon,
+                        "Embed",
+                        &warn_summary,
+                        stage_start.elapsed(),
+                        options.robot_mode,
+                    );
+                    warn!(error = %e, "Embedding stage failed (Ollama may be unavailable), continuing");
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Alias for [`Theme::color_icon`] to keep call sites concise.
+fn color_icon(icon: &str, has_errors: bool) -> String {
+    Theme::color_icon(icon, has_errors)
+}
+
+fn emit_stage_line(
+    pb: &indicatif::ProgressBar,
+    icon: &str,
+    label: &str,
+    summary: &str,
+    elapsed: std::time::Duration,
+    robot_mode: bool,
+) {
+    pb.finish_and_clear();
+    if !robot_mode {
+        crate::cli::progress::multi().suspend(|| {
+            println!("{}", format_stage_line(icon, label, summary, elapsed));
+        });
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::cli::commands::sync::SyncOptions;
+
+    #[test]
+    fn sync_options_is_surgical_required() {
+        let opts = SyncOptions {
+            issue_iids: vec![1],
+            project: Some("group/repo".to_string()),
+            ..SyncOptions::default()
+        };
+        assert!(opts.is_surgical());
+    }
+
+    #[test]
+    fn sync_options_surgical_with_mrs() {
+        let opts = SyncOptions {
+            mr_iids: vec![10, 20],
+            project: Some("group/repo".to_string()),
+            ..SyncOptions::default()
+        };
+        assert!(opts.is_surgical());
+    }
+
+    #[test]
+    fn sync_options_not_surgical_without_iids() {
+        let opts = SyncOptions {
+            project: Some("group/repo".to_string()),
+            ..SyncOptions::default()
+        };
+        assert!(!opts.is_surgical());
+    }
+}

src/cli/commands/timeline.rs

@@ -175,7 +175,7 @@ pub async fn run_timeline(config: &Config, params: &TimelineParams) -> Result<Ti
         query: params.query.clone(),
         search_mode: seed_result.search_mode,
         events,
-        total_events_before_limit: total_before_limit,
+        total_filtered_events: total_before_limit,
         seed_entities: seed_result.seed_entities,
         expanded_entities: expand_result.expanded_entities,
         unresolved_references: expand_result.unresolved_references,
@@ -342,7 +342,7 @@ fn format_entity_ref(entity_type: &str, iid: i64) -> String {
 /// Render timeline as robot-mode JSON in {ok, data, meta} envelope.
 pub fn print_timeline_json_with_meta(
     result: &TimelineResult,
-    total_events_before_limit: usize,
+    total_filtered_events: usize,
     depth: u32,
     include_mentions: bool,
     fields: Option<&[String]>,
@@ -355,7 +355,7 @@ pub fn print_timeline_json_with_meta(
             expansion_depth: depth,
             include_mentions,
             total_entities: result.seed_entities.len() + result.expanded_entities.len(),
-            total_events: total_events_before_limit,
+            total_events: total_filtered_events,
             evidence_notes_included: count_evidence_notes(&result.events),
             discussion_threads_included: count_discussion_threads(&result.events),
             unresolved_references: result.unresolved_references.len(),
@@ -374,7 +374,10 @@ pub fn print_timeline_json_with_meta(
         let expanded = crate::cli::robot::expand_fields_preset(f, "timeline");
         crate::cli::robot::filter_fields(&mut value, "events", &expanded);
     }
-    println!("{}", serde_json::to_string(&value).unwrap());
+    match serde_json::to_string(&value) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
 }
 
 #[derive(Serialize)]

src/cli/commands/trace.rs

@@ -50,17 +50,23 @@ pub fn print_trace(result: &TraceResult) {
         );
     }
 
+    // Show searched paths when there are renames but no chains
     if result.trace_chains.is_empty() {
         println!(
             "\n  {} {}",
             Icons::info(),
             Theme::dim().render("No trace chains found for this file.")
         );
-        println!(
-            "  {}",
-            Theme::dim()
-                .render("Hint: Run 'lore sync' to fetch MR file changes and cross-references.")
-        );
+        if !result.renames_followed && result.resolved_paths.len() == 1 {
+            println!(
+                "  {} Searched: {}",
+                Icons::info(),
+                Theme::dim().render(&result.resolved_paths[0])
+            );
+        }
+        for hint in &result.hints {
+            println!("  {} {}", Icons::info(), Theme::dim().render(hint));
+        }
         println!();
         return;
     }
@@ -195,6 +201,7 @@ pub fn print_trace_json(result: &TraceResult, elapsed_ms: u64, line_requested: O
             "elapsed_ms": elapsed_ms,
             "total_chains": result.total_chains,
             "renames_followed": result.renames_followed,
+            "hints": if result.hints.is_empty() { None } else { Some(&result.hints) },
         }
     });
 

src/cli/commands/who/active.rs

@@ -0,0 +1,301 @@
+use rusqlite::Connection;
+
+use crate::cli::render::{self, Theme};
+use crate::core::error::Result;
+use crate::core::time::ms_to_iso;
+
+use super::types::*;
+
+pub(super) fn query_active(
+    conn: &Connection,
+    project_id: Option<i64>,
+    since_ms: i64,
+    limit: usize,
+    include_closed: bool,
+) -> Result<ActiveResult> {
+    // Prevent overflow: saturating_add caps at usize::MAX instead of wrapping to 0.
+    // The .min() ensures the value fits in i64 for SQLite's LIMIT clause.
+    let limit_plus_one = limit.saturating_add(1).min(i64::MAX as usize) as i64;
+
+    // State filter for open-entities-only (default behavior)
+    let state_joins = if include_closed {
+        ""
+    } else {
+        " LEFT JOIN issues i ON d.issue_id = i.id
+         LEFT JOIN merge_requests m ON d.merge_request_id = m.id"
+    };
+    let state_filter = if include_closed {
+        ""
+    } else {
+        " AND (i.id IS NULL OR i.state = 'opened')
+           AND (m.id IS NULL OR m.state = 'opened')"
+    };
+
+    // Total unresolved count -- conditionally built
+    let total_sql_global = format!(
+        "SELECT COUNT(*) FROM discussions d
+         {state_joins}
+         WHERE d.resolvable = 1 AND d.resolved = 0
+           AND d.last_note_at >= ?1
+           {state_filter}"
+    );
+    let total_sql_scoped = format!(
+        "SELECT COUNT(*) FROM discussions d
+         {state_joins}
+         WHERE d.resolvable = 1 AND d.resolved = 0
+           AND d.last_note_at >= ?1
+           AND d.project_id = ?2
+           {state_filter}"
+    );
+
+    let total_unresolved_in_window: u32 = match project_id {
+        None => conn.query_row(&total_sql_global, rusqlite::params![since_ms], |row| {
+            row.get(0)
+        })?,
+        Some(pid) => {
+            conn.query_row(&total_sql_scoped, rusqlite::params![since_ms, pid], |row| {
+                row.get(0)
+            })?
+        }
+    };
+
+    // Active discussions with context -- conditionally built SQL
+    let sql_global = format!(
+        "
+        WITH picked AS (
+            SELECT d.id, d.noteable_type, d.issue_id, d.merge_request_id,
+                   d.project_id, d.last_note_at
+            FROM discussions d
+            {state_joins}
+            WHERE d.resolvable = 1 AND d.resolved = 0
+              AND d.last_note_at >= ?1
+              {state_filter}
+            ORDER BY d.last_note_at DESC
+            LIMIT ?2
+        ),
+        note_counts AS (
+            SELECT
+                n.discussion_id,
+                COUNT(*) AS note_count
+            FROM notes n
+            JOIN picked p ON p.id = n.discussion_id
+            WHERE n.is_system = 0
+            GROUP BY n.discussion_id
+        ),
+        participants AS (
+            SELECT
+                x.discussion_id,
+                GROUP_CONCAT(x.author_username, X'1F') AS participants
+            FROM (
+                SELECT DISTINCT n.discussion_id, n.author_username
+                FROM notes n
+                JOIN picked p ON p.id = n.discussion_id
+                WHERE n.is_system = 0 AND n.author_username IS NOT NULL
+            ) x
+            GROUP BY x.discussion_id
+        )
+        SELECT
+            p.id AS discussion_id,
+            p.noteable_type,
+            COALESCE(i.iid, m.iid) AS entity_iid,
+            COALESCE(i.title, m.title) AS entity_title,
+            proj.path_with_namespace,
+            p.last_note_at,
+            COALESCE(nc.note_count, 0) AS note_count,
+            COALESCE(pa.participants, '') AS participants
+        FROM picked p
+        JOIN projects proj ON p.project_id = proj.id
+        LEFT JOIN issues i ON p.issue_id = i.id
+        LEFT JOIN merge_requests m ON p.merge_request_id = m.id
+        LEFT JOIN note_counts nc ON nc.discussion_id = p.id
+        LEFT JOIN participants pa ON pa.discussion_id = p.id
+        ORDER BY p.last_note_at DESC
+    "
+    );
+
+    let sql_scoped = format!(
+        "
+        WITH picked AS (
+            SELECT d.id, d.noteable_type, d.issue_id, d.merge_request_id,
+                   d.project_id, d.last_note_at
+            FROM discussions d
+            {state_joins}
+            WHERE d.resolvable = 1 AND d.resolved = 0
+              AND d.last_note_at >= ?1
+              AND d.project_id = ?2
+              {state_filter}
+            ORDER BY d.last_note_at DESC
+            LIMIT ?3
+        ),
+        note_counts AS (
+            SELECT
+                n.discussion_id,
+                COUNT(*) AS note_count
+            FROM notes n
+            JOIN picked p ON p.id = n.discussion_id
+            WHERE n.is_system = 0
+            GROUP BY n.discussion_id
+        ),
+        participants AS (
+            SELECT
+                x.discussion_id,
+                GROUP_CONCAT(x.author_username, X'1F') AS participants
+            FROM (
+                SELECT DISTINCT n.discussion_id, n.author_username
+                FROM notes n
+                JOIN picked p ON p.id = n.discussion_id
+                WHERE n.is_system = 0 AND n.author_username IS NOT NULL
+            ) x
+            GROUP BY x.discussion_id
+        )
+        SELECT
+            p.id AS discussion_id,
+            p.noteable_type,
+            COALESCE(i.iid, m.iid) AS entity_iid,
+            COALESCE(i.title, m.title) AS entity_title,
+            proj.path_with_namespace,
+            p.last_note_at,
+            COALESCE(nc.note_count, 0) AS note_count,
+            COALESCE(pa.participants, '') AS participants
+        FROM picked p
+        JOIN projects proj ON p.project_id = proj.id
+        LEFT JOIN issues i ON p.issue_id = i.id
+        LEFT JOIN merge_requests m ON p.merge_request_id = m.id
+        LEFT JOIN note_counts nc ON nc.discussion_id = p.id
+        LEFT JOIN participants pa ON pa.discussion_id = p.id
+        ORDER BY p.last_note_at DESC
+    "
+    );
+
+    // Row-mapping closure shared between both variants
+    let map_row = |row: &rusqlite::Row| -> rusqlite::Result<ActiveDiscussion> {
+        let noteable_type: String = row.get(1)?;
+        let entity_type = if noteable_type == "MergeRequest" {
+            "MR"
+        } else {
+            "Issue"
+        };
+        let participants_csv: Option<String> = row.get(7)?;
+        // Sort participants for deterministic output -- GROUP_CONCAT order is undefined
+        let mut participants: Vec<String> = participants_csv
+            .as_deref()
+            .filter(|s| !s.is_empty())
+            .map(|csv| csv.split('\x1F').map(String::from).collect())
+            .unwrap_or_default();
+        participants.sort();
+
+        const MAX_PARTICIPANTS: usize = 50;
+        let participants_total = participants.len() as u32;
+        let participants_truncated = participants.len() > MAX_PARTICIPANTS;
+        if participants_truncated {
+            participants.truncate(MAX_PARTICIPANTS);
+        }
+
+        Ok(ActiveDiscussion {
+            discussion_id: row.get(0)?,
+            entity_type: entity_type.to_string(),
+            entity_iid: row.get(2)?,
+            entity_title: row.get(3)?,
+            project_path: row.get(4)?,
+            last_note_at: row.get(5)?,
+            note_count: row.get(6)?,
+            participants,
+            participants_total,
+            participants_truncated,
+        })
+    };
+
+    // Select variant first, then prepare exactly one statement
+    let discussions: Vec<ActiveDiscussion> = match project_id {
+        None => {
+            let mut stmt = conn.prepare_cached(&sql_global)?;
+            stmt.query_map(rusqlite::params![since_ms, limit_plus_one], &map_row)?
+                .collect::<std::result::Result<Vec<_>, _>>()?
+        }
+        Some(pid) => {
+            let mut stmt = conn.prepare_cached(&sql_scoped)?;
+            stmt.query_map(rusqlite::params![since_ms, pid, limit_plus_one], &map_row)?
+                .collect::<std::result::Result<Vec<_>, _>>()?
+        }
+    };
+
+    let truncated = discussions.len() > limit;
+    let discussions: Vec<ActiveDiscussion> = discussions.into_iter().take(limit).collect();
+
+    Ok(ActiveResult {
+        discussions,
+        total_unresolved_in_window,
+        truncated,
+    })
+}
+
+pub(super) fn print_active_human(r: &ActiveResult, project_path: Option<&str>) {
+    println!();
+    println!(
+        "{}",
+        Theme::bold().render(&format!(
+            "Active Discussions ({} unresolved in window)",
+            r.total_unresolved_in_window
+        ))
+    );
+    println!("{}", "\u{2500}".repeat(60));
+    super::print_scope_hint(project_path);
+    println!();
+
+    if r.discussions.is_empty() {
+        println!(
+            "  {}",
+            Theme::dim().render("No active unresolved discussions in this time window.")
+        );
+        println!();
+        return;
+    }
+
+    for disc in &r.discussions {
+        let prefix = if disc.entity_type == "MR" { "!" } else { "#" };
+        let participants_str = disc
+            .participants
+            .iter()
+            .map(|p| format!("@{p}"))
+            .collect::<Vec<_>>()
+            .join(", ");
+
+        println!(
+            "  {} {} {}  {} notes  {}",
+            Theme::info().render(&format!("{prefix}{}", disc.entity_iid)),
+            render::truncate(&disc.entity_title, 40),
+            Theme::dim().render(&render::format_relative_time(disc.last_note_at)),
+            disc.note_count,
+            Theme::dim().render(&disc.project_path),
+        );
+        if !participants_str.is_empty() {
+            println!("    {}", Theme::dim().render(&participants_str));
+        }
+    }
+    if r.truncated {
+        println!(
+            "  {}",
+            Theme::dim().render("(showing first -n; rerun with a higher --limit)")
+        );
+    }
+    println!();
+}
+
+pub(super) fn active_to_json(r: &ActiveResult) -> serde_json::Value {
+    serde_json::json!({
+        "total_unresolved_in_window": r.total_unresolved_in_window,
+        "truncated": r.truncated,
+        "discussions": r.discussions.iter().map(|d| serde_json::json!({
+            "discussion_id": d.discussion_id,
+            "entity_type": d.entity_type,
+            "entity_iid": d.entity_iid,
+            "entity_title": d.entity_title,
+            "project_path": d.project_path,
+            "last_note_at": ms_to_iso(d.last_note_at),
+            "note_count": d.note_count,
+            "participants": d.participants,
+            "participants_total": d.participants_total,
+            "participants_truncated": d.participants_truncated,
+        })).collect::<Vec<_>>(),
+    })
+}

src/cli/commands/who/expert.rs

@@ -0,0 +1,839 @@
+use std::collections::{HashMap, HashSet};
+
+use rusqlite::Connection;
+
+use crate::cli::render::{self, Icons, Theme};
+use crate::core::config::ScoringConfig;
+use crate::core::error::Result;
+use crate::core::path_resolver::{PathQuery, build_path_query};
+use crate::core::time::ms_to_iso;
+
+use super::types::*;
+
+pub(super) fn half_life_decay(elapsed_ms: i64, half_life_days: u32) -> f64 {
+    let days = (elapsed_ms as f64 / 86_400_000.0).max(0.0);
+    let hl = f64::from(half_life_days);
+    if hl <= 0.0 {
+        return 0.0;
+    }
+    2.0_f64.powf(-days / hl)
+}
+
+// ─── Query: Expert Mode ─────────────────────────────────────────────────────
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn query_expert(
+    conn: &Connection,
+    path: &str,
+    project_id: Option<i64>,
+    since_ms: i64,
+    as_of_ms: i64,
+    limit: usize,
+    scoring: &ScoringConfig,
+    detail: bool,
+    explain_score: bool,
+    include_bots: bool,
+) -> Result<ExpertResult> {
+    let pq = build_path_query(conn, path, project_id)?;
+
+    let sql = build_expert_sql_v2(pq.is_prefix);
+    let mut stmt = conn.prepare_cached(&sql)?;
+
+    // Params: ?1=path, ?2=since_ms, ?3=project_id, ?4=as_of_ms,
+    //         ?5=closed_mr_multiplier, ?6=reviewer_min_note_chars
+    let rows = stmt.query_map(
+        rusqlite::params![
+            pq.value,
+            since_ms,
+            project_id,
+            as_of_ms,
+            scoring.closed_mr_multiplier,
+            scoring.reviewer_min_note_chars,
+        ],
+        |row| {
+            Ok(SignalRow {
+                username: row.get(0)?,
+                signal: row.get(1)?,
+                mr_id: row.get(2)?,
+                qty: row.get(3)?,
+                ts: row.get(4)?,
+                state_mult: row.get(5)?,
+            })
+        },
+    )?;
+
+    // Per-user accumulator keyed by username.
+    let mut accum: HashMap<String, UserAccum> = HashMap::new();
+
+    for row_result in rows {
+        let r = row_result?;
+        let entry = accum
+            .entry(r.username.clone())
+            .or_insert_with(|| UserAccum {
+                contributions: Vec::new(),
+                last_seen_ms: 0,
+                mr_ids_author: HashSet::new(),
+                mr_ids_reviewer: HashSet::new(),
+                note_count: 0,
+            });
+
+        if r.ts > entry.last_seen_ms {
+            entry.last_seen_ms = r.ts;
+        }
+
+        match r.signal.as_str() {
+            "diffnote_author" | "file_author" => {
+                entry.mr_ids_author.insert(r.mr_id);
+            }
+            "file_reviewer_participated" | "file_reviewer_assigned" => {
+                entry.mr_ids_reviewer.insert(r.mr_id);
+            }
+            "note_group" => {
+                entry.note_count += r.qty as u32;
+                // DiffNote reviewers are also reviewer activity.
+                entry.mr_ids_reviewer.insert(r.mr_id);
+            }
+            _ => {}
+        }
+
+        entry.contributions.push(Contribution {
+            signal: r.signal,
+            mr_id: r.mr_id,
+            qty: r.qty,
+            ts: r.ts,
+            state_mult: r.state_mult,
+        });
+    }
+
+    // Bot filtering: exclude configured bot usernames (case-insensitive).
+    if !include_bots && !scoring.excluded_usernames.is_empty() {
+        let excluded: HashSet<String> = scoring
+            .excluded_usernames
+            .iter()
+            .map(|u| u.to_lowercase())
+            .collect();
+        accum.retain(|username, _| !excluded.contains(&username.to_lowercase()));
+    }
+
+    // Compute decayed scores with deterministic ordering.
+    let mut scored: Vec<ScoredUser> = accum
+        .into_iter()
+        .map(|(username, mut ua)| {
+            // Sort contributions by mr_id ASC for deterministic f64 summation.
+            ua.contributions.sort_by_key(|c| c.mr_id);
+
+            let mut comp_author = 0.0_f64;
+            let mut comp_reviewer_participated = 0.0_f64;
+            let mut comp_reviewer_assigned = 0.0_f64;
+            let mut comp_notes = 0.0_f64;
+
+            for c in &ua.contributions {
+                let elapsed = as_of_ms - c.ts;
+                match c.signal.as_str() {
+                    "diffnote_author" | "file_author" => {
+                        let decay = half_life_decay(elapsed, scoring.author_half_life_days);
+                        comp_author += scoring.author_weight as f64 * decay * c.state_mult;
+                    }
+                    "file_reviewer_participated" => {
+                        let decay = half_life_decay(elapsed, scoring.reviewer_half_life_days);
+                        comp_reviewer_participated +=
+                            scoring.reviewer_weight as f64 * decay * c.state_mult;
+                    }
+                    "file_reviewer_assigned" => {
+                        let decay =
+                            half_life_decay(elapsed, scoring.reviewer_assignment_half_life_days);
+                        comp_reviewer_assigned +=
+                            scoring.reviewer_assignment_weight as f64 * decay * c.state_mult;
+                    }
+                    "note_group" => {
+                        let decay = half_life_decay(elapsed, scoring.note_half_life_days);
+                        // Diminishing returns: log2(1 + count) per MR.
+                        let note_value = (1.0 + c.qty as f64).log2();
+                        comp_notes += scoring.note_bonus as f64 * note_value * decay * c.state_mult;
+                    }
+                    _ => {}
+                }
+            }
+
+            let raw_score =
+                comp_author + comp_reviewer_participated + comp_reviewer_assigned + comp_notes;
+            ScoredUser {
+                username,
+                raw_score,
+                components: ScoreComponents {
+                    author: comp_author,
+                    reviewer_participated: comp_reviewer_participated,
+                    reviewer_assigned: comp_reviewer_assigned,
+                    notes: comp_notes,
+                },
+                accum: ua,
+            }
+        })
+        .collect();
+
+    // Sort: raw_score DESC, last_seen DESC, username ASC (deterministic tiebreaker).
+    scored.sort_by(|a, b| {
+        b.raw_score
+            .partial_cmp(&a.raw_score)
+            .unwrap_or(std::cmp::Ordering::Equal)
+            .then_with(|| b.accum.last_seen_ms.cmp(&a.accum.last_seen_ms))
+            .then_with(|| a.username.cmp(&b.username))
+    });
+
+    let truncated = scored.len() > limit;
+    scored.truncate(limit);
+
+    // Build Expert structs with MR refs.
+    let mut experts: Vec<Expert> = scored
+        .into_iter()
+        .map(|su| {
+            let mut mr_refs = build_mr_refs_for_user(conn, &su.accum);
+            mr_refs.sort();
+            let mr_refs_total = mr_refs.len() as u32;
+            let mr_refs_truncated = mr_refs.len() > MAX_MR_REFS_PER_USER;
+            if mr_refs_truncated {
+                mr_refs.truncate(MAX_MR_REFS_PER_USER);
+            }
+            Expert {
+                username: su.username,
+                score: su.raw_score.round() as i64,
+                score_raw: if explain_score {
+                    Some(su.raw_score)
+                } else {
+                    None
+                },
+                components: if explain_score {
+                    Some(su.components)
+                } else {
+                    None
+                },
+                review_mr_count: su.accum.mr_ids_reviewer.len() as u32,
+                review_note_count: su.accum.note_count,
+                author_mr_count: su.accum.mr_ids_author.len() as u32,
+                last_seen_ms: su.accum.last_seen_ms,
+                mr_refs,
+                mr_refs_total,
+                mr_refs_truncated,
+                details: None,
+            }
+        })
+        .collect();
+
+    // Populate per-MR detail when --detail is requested
+    if detail && !experts.is_empty() {
+        let details_map = query_expert_details(conn, &pq, &experts, since_ms, project_id)?;
+        for expert in &mut experts {
+            expert.details = details_map.get(&expert.username).cloned();
+        }
+    }
+
+    Ok(ExpertResult {
+        path_query: if pq.is_prefix {
+            // Use raw input (unescaped) for display — pq.value has LIKE escaping.
+            path.trim_end_matches('/').to_string()
+        } else {
+            // For exact matches (including suffix-resolved), show the resolved path.
+            pq.value.clone()
+        },
+        path_match: if pq.is_prefix { "prefix" } else { "exact" }.to_string(),
+        experts,
+        truncated,
+    })
+}
+
+struct SignalRow {
+    username: String,
+    signal: String,
+    mr_id: i64,
+    qty: i64,
+    ts: i64,
+    state_mult: f64,
+}
+
+/// Per-user signal accumulator used during Rust-side scoring.
+struct UserAccum {
+    contributions: Vec<Contribution>,
+    last_seen_ms: i64,
+    mr_ids_author: HashSet<i64>,
+    mr_ids_reviewer: HashSet<i64>,
+    note_count: u32,
+}
+
+/// A single contribution to a user's score (one signal row).
+struct Contribution {
+    signal: String,
+    mr_id: i64,
+    qty: i64,
+    ts: i64,
+    state_mult: f64,
+}
+
+/// Intermediate scored user before building Expert structs.
+struct ScoredUser {
+    username: String,
+    raw_score: f64,
+    components: ScoreComponents,
+    accum: UserAccum,
+}
+
+/// Build MR refs (e.g. "group/project!123") for a user from their accumulated MR IDs.
+fn build_mr_refs_for_user(conn: &Connection, ua: &UserAccum) -> Vec<String> {
+    let all_mr_ids: HashSet<i64> = ua
+        .mr_ids_author
+        .iter()
+        .chain(ua.mr_ids_reviewer.iter())
+        .copied()
+        .chain(ua.contributions.iter().map(|c| c.mr_id))
+        .collect();
+
+    if all_mr_ids.is_empty() {
+        return Vec::new();
+    }
+
+    let placeholders: Vec<String> = (1..=all_mr_ids.len()).map(|i| format!("?{i}")).collect();
+    let sql = format!(
+        "SELECT p.path_with_namespace || '!' || CAST(m.iid AS TEXT)
+         FROM merge_requests m
+         JOIN projects p ON m.project_id = p.id
+         WHERE m.id IN ({})",
+        placeholders.join(",")
+    );
+
+    let mut stmt = match conn.prepare(&sql) {
+        Ok(s) => s,
+        Err(_) => return Vec::new(),
+    };
+
+    let mut mr_ids_vec: Vec<i64> = all_mr_ids.into_iter().collect();
+    mr_ids_vec.sort_unstable();
+    let params: Vec<&dyn rusqlite::types::ToSql> = mr_ids_vec
+        .iter()
+        .map(|id| id as &dyn rusqlite::types::ToSql)
+        .collect();
+
+    stmt.query_map(&*params, |row| row.get::<_, String>(0))
+        .map(|rows| rows.filter_map(|r| r.ok()).collect())
+        .unwrap_or_default()
+}
+
+/// Build the CTE-based expert SQL for time-decay scoring (v2).
+///
+/// Returns raw signal rows `(username, signal, mr_id, qty, ts, state_mult)` that
+/// Rust aggregates with per-signal decay and `log2(1+count)` for note groups.
+///
+/// Parameters: `?1` = path, `?2` = since_ms, `?3` = project_id (nullable),
+///             `?4` = as_of_ms, `?5` = closed_mr_multiplier, `?6` = reviewer_min_note_chars
+pub(super) fn build_expert_sql_v2(is_prefix: bool) -> String {
+    let path_op = if is_prefix {
+        "LIKE ?1 ESCAPE '\\'"
+    } else {
+        "= ?1"
+    };
+    // INDEXED BY hints for each branch:
+    // - new_path branch: idx_notes_diffnote_path_created (existing)
+    // - old_path branch: idx_notes_old_path_author (migration 026)
+    format!(
+        "
+WITH matched_notes_raw AS (
+  -- Branch 1: match on position_new_path
+  SELECT n.id, n.discussion_id, n.author_username, n.created_at, n.project_id
+  FROM notes n INDEXED BY idx_notes_diffnote_path_created
+  WHERE n.note_type = 'DiffNote'
+    AND n.is_system = 0
+    AND n.author_username IS NOT NULL
+    AND n.created_at >= ?2
+    AND n.created_at < ?4
+    AND (?3 IS NULL OR n.project_id = ?3)
+    AND n.position_new_path {path_op}
+  UNION ALL
+  -- Branch 2: match on position_old_path
+  SELECT n.id, n.discussion_id, n.author_username, n.created_at, n.project_id
+  FROM notes n INDEXED BY idx_notes_old_path_author
+  WHERE n.note_type = 'DiffNote'
+    AND n.is_system = 0
+    AND n.author_username IS NOT NULL
+    AND n.created_at >= ?2
+    AND n.created_at < ?4
+    AND (?3 IS NULL OR n.project_id = ?3)
+    AND n.position_old_path IS NOT NULL
+    AND n.position_old_path {path_op}
+),
+matched_notes AS (
+  -- Dedup: prevent double-counting when old_path = new_path (no rename)
+  SELECT DISTINCT id, discussion_id, author_username, created_at, project_id
+  FROM matched_notes_raw
+),
+matched_file_changes_raw AS (
+  -- Branch 1: match on new_path
+  SELECT fc.merge_request_id, fc.project_id
+  FROM mr_file_changes fc INDEXED BY idx_mfc_new_path_project_mr
+  WHERE (?3 IS NULL OR fc.project_id = ?3)
+    AND fc.new_path {path_op}
+  UNION ALL
+  -- Branch 2: match on old_path
+  SELECT fc.merge_request_id, fc.project_id
+  FROM mr_file_changes fc INDEXED BY idx_mfc_old_path_project_mr
+  WHERE (?3 IS NULL OR fc.project_id = ?3)
+    AND fc.old_path IS NOT NULL
+    AND fc.old_path {path_op}
+),
+matched_file_changes AS (
+  -- Dedup: prevent double-counting when old_path = new_path (no rename)
+  SELECT DISTINCT merge_request_id, project_id
+  FROM matched_file_changes_raw
+),
+mr_activity AS (
+  -- Centralized state-aware timestamps and state multiplier.
+  -- Scoped to MRs matched by file changes to avoid materializing the full MR table.
+  SELECT DISTINCT
+    m.id AS mr_id,
+    m.author_username,
+    m.state,
+    CASE
+      WHEN m.state = 'merged' THEN COALESCE(m.merged_at, m.created_at)
+      WHEN m.state = 'closed' THEN COALESCE(m.closed_at, m.created_at)
+      ELSE COALESCE(m.updated_at, m.created_at)
+    END AS activity_ts,
+    CASE WHEN m.state = 'closed' THEN ?5 ELSE 1.0 END AS state_mult
+  FROM merge_requests m
+  JOIN matched_file_changes mfc ON mfc.merge_request_id = m.id
+  WHERE m.state IN ('opened','merged','closed')
+),
+reviewer_participation AS (
+  -- Precompute which (mr_id, username) pairs have substantive DiffNote participation.
+  SELECT DISTINCT d.merge_request_id AS mr_id, mn.author_username AS username
+  FROM matched_notes mn
+  JOIN discussions d ON mn.discussion_id = d.id
+  JOIN notes n_body ON mn.id = n_body.id
+  WHERE d.merge_request_id IS NOT NULL
+    AND LENGTH(TRIM(COALESCE(n_body.body, ''))) >= ?6
+),
+raw AS (
+  -- Signal 1: DiffNote reviewer (individual notes for note_cnt)
+  SELECT mn.author_username AS username, 'diffnote_reviewer' AS signal,
+         m.id AS mr_id, mn.id AS note_id, mn.created_at AS seen_at,
+         CASE WHEN m.state = 'closed' THEN ?5 ELSE 1.0 END AS state_mult
+  FROM matched_notes mn
+  JOIN discussions d ON mn.discussion_id = d.id
+  JOIN merge_requests m ON d.merge_request_id = m.id
+  WHERE (m.author_username IS NULL OR mn.author_username != m.author_username)
+    AND m.state IN ('opened','merged','closed')
+
+  UNION ALL
+
+  -- Signal 2: DiffNote MR author
+  SELECT m.author_username AS username, 'diffnote_author' AS signal,
+         m.id AS mr_id, NULL AS note_id, MAX(mn.created_at) AS seen_at,
+         CASE WHEN m.state = 'closed' THEN ?5 ELSE 1.0 END AS state_mult
+  FROM merge_requests m
+  JOIN discussions d ON d.merge_request_id = m.id
+  JOIN matched_notes mn ON mn.discussion_id = d.id
+  WHERE m.author_username IS NOT NULL
+    AND m.state IN ('opened','merged','closed')
+  GROUP BY m.author_username, m.id
+
+  UNION ALL
+
+  -- Signal 3: MR author via file changes (uses mr_activity CTE)
+  SELECT a.author_username AS username, 'file_author' AS signal,
+         a.mr_id, NULL AS note_id,
+         a.activity_ts AS seen_at, a.state_mult
+  FROM mr_activity a
+  WHERE a.author_username IS NOT NULL
+    AND a.activity_ts >= ?2
+    AND a.activity_ts < ?4
+
+  UNION ALL
+
+  -- Signal 4a: Reviewer participated (in mr_reviewers AND left DiffNotes on path)
+  SELECT r.username AS username, 'file_reviewer_participated' AS signal,
+         a.mr_id, NULL AS note_id,
+         a.activity_ts AS seen_at, a.state_mult
+  FROM mr_activity a
+  JOIN mr_reviewers r ON r.merge_request_id = a.mr_id
+  JOIN reviewer_participation rp ON rp.mr_id = a.mr_id AND rp.username = r.username
+  WHERE r.username IS NOT NULL
+    AND (a.author_username IS NULL OR r.username != a.author_username)
+    AND a.activity_ts >= ?2
+    AND a.activity_ts < ?4
+
+  UNION ALL
+
+  -- Signal 4b: Reviewer assigned-only (in mr_reviewers, NO DiffNotes on path)
+  SELECT r.username AS username, 'file_reviewer_assigned' AS signal,
+         a.mr_id, NULL AS note_id,
+         a.activity_ts AS seen_at, a.state_mult
+  FROM mr_activity a
+  JOIN mr_reviewers r ON r.merge_request_id = a.mr_id
+  LEFT JOIN reviewer_participation rp ON rp.mr_id = a.mr_id AND rp.username = r.username
+  WHERE rp.username IS NULL
+    AND r.username IS NOT NULL
+    AND (a.author_username IS NULL OR r.username != a.author_username)
+    AND a.activity_ts >= ?2
+    AND a.activity_ts < ?4
+),
+aggregated AS (
+  -- MR-level signals: 1 row per (username, signal_class, mr_id) with MAX(ts)
+  SELECT username, signal, mr_id, 1 AS qty, MAX(seen_at) AS ts, MAX(state_mult) AS state_mult
+  FROM raw WHERE signal != 'diffnote_reviewer'
+  GROUP BY username, signal, mr_id
+  UNION ALL
+  -- Note signals: 1 row per (username, mr_id) with note_count and max_ts
+  SELECT username, 'note_group' AS signal, mr_id, COUNT(*) AS qty, MAX(seen_at) AS ts,
+         MAX(state_mult) AS state_mult
+  FROM raw WHERE signal = 'diffnote_reviewer' AND note_id IS NOT NULL
+  GROUP BY username, mr_id
+)
+SELECT username, signal, mr_id, qty, ts, state_mult FROM aggregated WHERE username IS NOT NULL
+        "
+    )
+}
+
+/// Query per-MR detail for a set of experts. Returns a map of username -> Vec<ExpertMrDetail>.
+pub(super) fn query_expert_details(
+    conn: &Connection,
+    pq: &PathQuery,
+    experts: &[Expert],
+    since_ms: i64,
+    project_id: Option<i64>,
+) -> Result<HashMap<String, Vec<ExpertMrDetail>>> {
+    let path_op = if pq.is_prefix {
+        "LIKE ?1 ESCAPE '\\'"
+    } else {
+        "= ?1"
+    };
+
+    // Build IN clause for usernames
+    let placeholders: Vec<String> = experts
+        .iter()
+        .enumerate()
+        .map(|(i, _)| format!("?{}", i + 4))
+        .collect();
+    let in_clause = placeholders.join(",");
+
+    let sql = format!(
+        "
+        WITH signals AS (
+            -- 1. DiffNote reviewer (matches both new_path and old_path for renamed files)
+            SELECT
+                n.author_username AS username,
+                'reviewer' AS role,
+                m.id AS mr_id,
+                (p.path_with_namespace || '!' || CAST(m.iid AS TEXT)) AS mr_ref,
+                m.title AS title,
+                COUNT(*) AS note_count,
+                MAX(n.created_at) AS last_activity
+            FROM notes n
+            JOIN discussions d ON n.discussion_id = d.id
+            JOIN merge_requests m ON d.merge_request_id = m.id
+            JOIN projects p ON m.project_id = p.id
+            WHERE n.note_type = 'DiffNote'
+              AND n.is_system = 0
+              AND n.author_username IS NOT NULL
+              AND (m.author_username IS NULL OR n.author_username != m.author_username)
+              AND m.state IN ('opened','merged','closed')
+              AND (n.position_new_path {path_op}
+                   OR (n.position_old_path IS NOT NULL AND n.position_old_path {path_op}))
+              AND n.created_at >= ?2
+              AND (?3 IS NULL OR n.project_id = ?3)
+              AND n.author_username IN ({in_clause})
+            GROUP BY n.author_username, m.id
+
+            UNION ALL
+
+            -- 2. DiffNote MR author (matches both new_path and old_path for renamed files)
+            SELECT
+                m.author_username AS username,
+                'author' AS role,
+                m.id AS mr_id,
+                (p.path_with_namespace || '!' || CAST(m.iid AS TEXT)) AS mr_ref,
+                m.title AS title,
+                0 AS note_count,
+                MAX(n.created_at) AS last_activity
+            FROM merge_requests m
+            JOIN discussions d ON d.merge_request_id = m.id
+            JOIN notes n ON n.discussion_id = d.id
+            JOIN projects p ON m.project_id = p.id
+            WHERE n.note_type = 'DiffNote'
+              AND n.is_system = 0
+              AND m.author_username IS NOT NULL
+              AND m.state IN ('opened','merged','closed')
+              AND (n.position_new_path {path_op}
+                   OR (n.position_old_path IS NOT NULL AND n.position_old_path {path_op}))
+              AND n.created_at >= ?2
+              AND (?3 IS NULL OR n.project_id = ?3)
+              AND m.author_username IN ({in_clause})
+            GROUP BY m.author_username, m.id
+
+            UNION ALL
+
+            -- 3. MR author via file changes (matches both new_path and old_path)
+            SELECT
+                m.author_username AS username,
+                'author' AS role,
+                m.id AS mr_id,
+                (p.path_with_namespace || '!' || CAST(m.iid AS TEXT)) AS mr_ref,
+                m.title AS title,
+                0 AS note_count,
+                m.updated_at AS last_activity
+            FROM mr_file_changes fc
+            JOIN merge_requests m ON fc.merge_request_id = m.id
+            JOIN projects p ON m.project_id = p.id
+            WHERE m.author_username IS NOT NULL
+              AND m.state IN ('opened','merged','closed')
+              AND (fc.new_path {path_op}
+                   OR (fc.old_path IS NOT NULL AND fc.old_path {path_op}))
+              AND m.updated_at >= ?2
+              AND (?3 IS NULL OR fc.project_id = ?3)
+              AND m.author_username IN ({in_clause})
+
+            UNION ALL
+
+            -- 4. MR reviewer via file changes + mr_reviewers (matches both new_path and old_path)
+            SELECT
+                r.username AS username,
+                'reviewer' AS role,
+                m.id AS mr_id,
+                (p.path_with_namespace || '!' || CAST(m.iid AS TEXT)) AS mr_ref,
+                m.title AS title,
+                0 AS note_count,
+                m.updated_at AS last_activity
+            FROM mr_file_changes fc
+            JOIN merge_requests m ON fc.merge_request_id = m.id
+            JOIN projects p ON m.project_id = p.id
+            JOIN mr_reviewers r ON r.merge_request_id = m.id
+            WHERE r.username IS NOT NULL
+              AND (m.author_username IS NULL OR r.username != m.author_username)
+              AND m.state IN ('opened','merged','closed')
+              AND (fc.new_path {path_op}
+                   OR (fc.old_path IS NOT NULL AND fc.old_path {path_op}))
+              AND m.updated_at >= ?2
+              AND (?3 IS NULL OR fc.project_id = ?3)
+              AND r.username IN ({in_clause})
+        )
+        SELECT
+            username,
+            mr_ref,
+            title,
+            GROUP_CONCAT(DISTINCT role) AS roles,
+            SUM(note_count) AS total_notes,
+            MAX(last_activity) AS last_activity
+        FROM signals
+        GROUP BY username, mr_ref
+        ORDER BY username ASC, last_activity DESC
+        "
+    );
+
+    // prepare() not prepare_cached(): the IN clause varies by expert count,
+    // so the SQL shape changes per invocation and caching wastes memory.
+    let mut stmt = conn.prepare(&sql)?;
+
+    // Build params: ?1=path, ?2=since_ms, ?3=project_id, ?4..=usernames
+    let mut params: Vec<Box<dyn rusqlite::types::ToSql>> = Vec::new();
+    params.push(Box::new(pq.value.clone()));
+    params.push(Box::new(since_ms));
+    params.push(Box::new(project_id));
+    for expert in experts {
+        params.push(Box::new(expert.username.clone()));
+    }
+    let param_refs: Vec<&dyn rusqlite::types::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+
+    let rows: Vec<(String, String, String, String, u32, i64)> = stmt
+        .query_map(param_refs.as_slice(), |row| {
+            Ok((
+                row.get(0)?,
+                row.get(1)?,
+                row.get(2)?,
+                row.get::<_, String>(3)?,
+                row.get(4)?,
+                row.get(5)?,
+            ))
+        })?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    let mut map: HashMap<String, Vec<ExpertMrDetail>> = HashMap::new();
+    for (username, mr_ref, title, roles_csv, note_count, last_activity) in rows {
+        let has_author = roles_csv.contains("author");
+        let has_reviewer = roles_csv.contains("reviewer");
+        let role = match (has_author, has_reviewer) {
+            (true, true) => "A+R",
+            (true, false) => "A",
+            (false, true) => "R",
+            _ => "?",
+        }
+        .to_string();
+        map.entry(username).or_default().push(ExpertMrDetail {
+            mr_ref,
+            title,
+            role,
+            note_count,
+            last_activity_ms: last_activity,
+        });
+    }
+
+    Ok(map)
+}
+
+pub(super) fn print_expert_human(r: &ExpertResult, project_path: Option<&str>) {
+    println!();
+    println!(
+        "{}",
+        Theme::bold().render(&format!("Experts for {}", r.path_query))
+    );
+    println!("{}", "\u{2500}".repeat(60));
+    println!(
+        "  {}",
+        Theme::dim().render(&format!(
+            "(matching {} {})",
+            r.path_match,
+            if r.path_match == "exact" {
+                "file"
+            } else {
+                "directory prefix"
+            }
+        ))
+    );
+    super::print_scope_hint(project_path);
+    println!();
+
+    if r.experts.is_empty() {
+        println!(
+            "  {}",
+            Theme::dim().render("No experts found for this path.")
+        );
+        println!();
+        return;
+    }
+
+    println!(
+        "  {:<16} {:>6} {:>12} {:>6} {:>12}  {}  {}",
+        Theme::bold().render("Username"),
+        Theme::bold().render("Score"),
+        Theme::bold().render("Reviewed(MRs)"),
+        Theme::bold().render("Notes"),
+        Theme::bold().render("Authored(MRs)"),
+        Theme::bold().render("Last Seen"),
+        Theme::bold().render("MR Refs"),
+    );
+
+    for expert in &r.experts {
+        let reviews = if expert.review_mr_count > 0 {
+            expert.review_mr_count.to_string()
+        } else {
+            "-".to_string()
+        };
+        let notes = if expert.review_note_count > 0 {
+            expert.review_note_count.to_string()
+        } else {
+            "-".to_string()
+        };
+        let authored = if expert.author_mr_count > 0 {
+            expert.author_mr_count.to_string()
+        } else {
+            "-".to_string()
+        };
+        let mr_str = expert
+            .mr_refs
+            .iter()
+            .take(5)
+            .cloned()
+            .collect::<Vec<_>>()
+            .join(", ");
+        let overflow = if expert.mr_refs_total > 5 {
+            format!(" +{}", expert.mr_refs_total - 5)
+        } else {
+            String::new()
+        };
+        println!(
+            "  {:<16} {:>6} {:>12} {:>6} {:>12}  {:<12}{}{}",
+            Theme::info().render(&format!("{} {}", Icons::user(), expert.username)),
+            expert.score,
+            reviews,
+            notes,
+            authored,
+            render::format_relative_time(expert.last_seen_ms),
+            if mr_str.is_empty() {
+                String::new()
+            } else {
+                format!("  {mr_str}")
+            },
+            overflow,
+        );
+
+        // Print detail sub-rows when populated
+        if let Some(details) = &expert.details {
+            const MAX_DETAIL_DISPLAY: usize = 10;
+            for d in details.iter().take(MAX_DETAIL_DISPLAY) {
+                let notes_str = if d.note_count > 0 {
+                    format!("{} notes", d.note_count)
+                } else {
+                    String::new()
+                };
+                println!(
+                    "     {:<3} {:<30} {:>30}  {:>10}  {}",
+                    Theme::dim().render(&d.role),
+                    d.mr_ref,
+                    render::truncate(&format!("\"{}\"", d.title), 30),
+                    notes_str,
+                    Theme::dim().render(&render::format_relative_time(d.last_activity_ms)),
+                );
+            }
+            if details.len() > MAX_DETAIL_DISPLAY {
+                println!(
+                    "     {}",
+                    Theme::dim().render(&format!("+{} more", details.len() - MAX_DETAIL_DISPLAY))
+                );
+            }
+        }
+    }
+    if r.truncated {
+        println!(
+            "  {}",
+            Theme::dim().render("(showing first -n; rerun with a higher --limit)")
+        );
+    }
+    println!();
+}
+
+pub(super) fn expert_to_json(r: &ExpertResult) -> serde_json::Value {
+    serde_json::json!({
+        "path_query": r.path_query,
+        "path_match": r.path_match,
+        "scoring_model_version": 2,
+        "truncated": r.truncated,
+        "experts": r.experts.iter().map(|e| {
+            let mut obj = serde_json::json!({
+                "username": e.username,
+                "score": e.score,
+                "review_mr_count": e.review_mr_count,
+                "review_note_count": e.review_note_count,
+                "author_mr_count": e.author_mr_count,
+                "last_seen_at": ms_to_iso(e.last_seen_ms),
+                "mr_refs": e.mr_refs,
+                "mr_refs_total": e.mr_refs_total,
+                "mr_refs_truncated": e.mr_refs_truncated,
+            });
+            if let Some(raw) = e.score_raw {
+                obj["score_raw"] = serde_json::json!(raw);
+            }
+            if let Some(comp) = &e.components {
+                obj["components"] = serde_json::json!({
+                    "author": comp.author,
+                    "reviewer_participated": comp.reviewer_participated,
+                    "reviewer_assigned": comp.reviewer_assigned,
+                    "notes": comp.notes,
+                });
+            }
+            if let Some(details) = &e.details {
+                obj["details"] = serde_json::json!(details.iter().map(|d| serde_json::json!({
+                    "mr_ref": d.mr_ref,
+                    "title": d.title,
+                    "role": d.role,
+                    "note_count": d.note_count,
+                    "last_activity_at": ms_to_iso(d.last_activity_ms),
+                })).collect::<Vec<_>>());
+            }
+            obj
+        }).collect::<Vec<_>>(),
+    })
+}

src/cli/commands/who/mod.rs

@@ -0,0 +1,429 @@
+mod active;
+mod expert;
+mod overlap;
+mod reviews;
+pub mod types;
+mod workload;
+
+pub use types::*;
+
+// Re-export submodule functions for tests (tests use `use super::*`).
+#[cfg(test)]
+use active::query_active;
+#[cfg(test)]
+use expert::{build_expert_sql_v2, half_life_decay, query_expert};
+#[cfg(test)]
+use overlap::{format_overlap_role, query_overlap};
+#[cfg(test)]
+use reviews::{normalize_review_prefix, query_reviews};
+#[cfg(test)]
+use workload::query_workload;
+
+use rusqlite::Connection;
+use serde::Serialize;
+
+use crate::Config;
+use crate::cli::WhoArgs;
+use crate::cli::render::Theme;
+use crate::cli::robot::RobotMeta;
+use crate::core::db::create_connection;
+use crate::core::error::{LoreError, Result};
+use crate::core::path_resolver::normalize_repo_path;
+use crate::core::paths::get_db_path;
+use crate::core::project::resolve_project;
+use crate::core::time::{ms_to_iso, now_ms, parse_since, parse_since_from};
+
+#[cfg(test)]
+use crate::core::config::ScoringConfig;
+#[cfg(test)]
+use crate::core::path_resolver::{SuffixResult, build_path_query, escape_like, suffix_probe};
+
+// ─── Mode Discrimination ────────────────────────────────────────────────────
+
+/// Determines which query mode to run based on args.
+/// Path variants own their strings because path normalization produces new `String`s.
+/// Username variants borrow from args since no normalization is needed.
+enum WhoMode<'a> {
+    /// lore who <file-path>  OR  lore who --path <path>
+    Expert { path: String },
+    /// lore who <username>
+    Workload { username: &'a str },
+    /// lore who <username> --reviews
+    Reviews { username: &'a str },
+    /// lore who --active
+    Active,
+    /// lore who --overlap <path>
+    Overlap { path: String },
+}
+
+fn resolve_mode<'a>(args: &'a WhoArgs) -> Result<WhoMode<'a>> {
+    // Explicit --path flag always wins (handles root files like README.md,
+    // LICENSE, Makefile -- anything without a / that can't be auto-detected)
+    if let Some(p) = &args.path {
+        return Ok(WhoMode::Expert {
+            path: normalize_repo_path(p),
+        });
+    }
+    if args.active {
+        return Ok(WhoMode::Active);
+    }
+    if let Some(path) = &args.overlap {
+        return Ok(WhoMode::Overlap {
+            path: normalize_repo_path(path),
+        });
+    }
+    if let Some(target) = &args.target {
+        let clean = target.strip_prefix('@').unwrap_or(target);
+        if args.reviews {
+            return Ok(WhoMode::Reviews { username: clean });
+        }
+        // Disambiguation: if target contains '/', it's a file path.
+        // GitLab usernames never contain '/'.
+        // Root files (no '/') require --path.
+        if clean.contains('/') {
+            return Ok(WhoMode::Expert {
+                path: normalize_repo_path(clean),
+            });
+        }
+        return Ok(WhoMode::Workload { username: clean });
+    }
+    Err(LoreError::Other(
+        "Provide a username, file path, --active, or --overlap <path>.\n\n\
+         Examples:\n  \
+         lore who src/features/auth/\n  \
+         lore who @username\n  \
+         lore who --active\n  \
+         lore who --overlap src/features/\n  \
+         lore who --path README.md\n  \
+         lore who --path Makefile"
+            .to_string(),
+    ))
+}
+
+fn validate_mode_flags(mode: &WhoMode<'_>, args: &WhoArgs) -> Result<()> {
+    if args.detail && !matches!(mode, WhoMode::Expert { .. }) {
+        return Err(LoreError::Other(
+            "--detail is only supported in expert mode (`lore who --path <path>` or `lore who <path/with/slash>`).".to_string(),
+        ));
+    }
+    Ok(())
+}
+
+// ─── Entry Point ─────────────────────────────────────────────────────────────
+
+/// Main entry point. Resolves mode + resolved inputs once, then dispatches.
+pub fn run_who(config: &Config, args: &WhoArgs) -> Result<WhoRun> {
+    let db_path = get_db_path(config.storage.db_path.as_deref());
+    let conn = create_connection(&db_path)?;
+
+    let project_id = args
+        .project
+        .as_deref()
+        .map(|p| resolve_project(&conn, p))
+        .transpose()?;
+
+    let project_path = project_id
+        .map(|id| lookup_project_path(&conn, id))
+        .transpose()?;
+
+    let mode = resolve_mode(args)?;
+    validate_mode_flags(&mode, args)?;
+
+    // since_mode semantics:
+    // - expert/reviews/active/overlap: default window applies if args.since is None -> "default"
+    // - workload: no default window; args.since None => "none"
+    let since_mode_for_defaulted = if args.since.is_some() {
+        "explicit"
+    } else {
+        "default"
+    };
+    let since_mode_for_workload = if args.since.is_some() {
+        "explicit"
+    } else {
+        "none"
+    };
+
+    let limit = args.limit.map_or(usize::MAX, usize::from);
+
+    match mode {
+        WhoMode::Expert { path } => {
+            // Compute as_of first so --since durations are relative to it.
+            let as_of_ms = match &args.as_of {
+                Some(v) => parse_since(v).ok_or_else(|| {
+                    LoreError::Other(format!(
+                        "Invalid --as-of value: '{v}'. Use a duration (30d, 6m) or date (2024-01-15)"
+                    ))
+                })?,
+                None => now_ms(),
+            };
+            let since_ms = if args.all_history {
+                0
+            } else {
+                resolve_since_from(args.since.as_deref(), "24m", as_of_ms)?
+            };
+            let result = expert::query_expert(
+                &conn,
+                &path,
+                project_id,
+                since_ms,
+                as_of_ms,
+                limit,
+                &config.scoring,
+                args.detail,
+                args.explain_score,
+                args.include_bots,
+            )?;
+            Ok(WhoRun {
+                resolved_input: WhoResolvedInput {
+                    mode: "expert".to_string(),
+                    project_id,
+                    project_path,
+                    since_ms: Some(since_ms),
+                    since_iso: Some(ms_to_iso(since_ms)),
+                    since_mode: since_mode_for_defaulted.to_string(),
+                    limit: args.limit,
+                },
+                result: WhoResult::Expert(result),
+            })
+        }
+        WhoMode::Workload { username } => {
+            let since_ms = args
+                .since
+                .as_deref()
+                .map(resolve_since_required)
+                .transpose()?;
+
+            let result = workload::query_workload(
+                &conn,
+                username,
+                project_id,
+                since_ms,
+                limit,
+                args.include_closed,
+            )?;
+            Ok(WhoRun {
+                resolved_input: WhoResolvedInput {
+                    mode: "workload".to_string(),
+                    project_id,
+                    project_path,
+                    since_ms,
+                    since_iso: since_ms.map(ms_to_iso),
+                    since_mode: since_mode_for_workload.to_string(),
+                    limit: args.limit,
+                },
+                result: WhoResult::Workload(result),
+            })
+        }
+        WhoMode::Reviews { username } => {
+            let since_ms = resolve_since(args.since.as_deref(), "6m")?;
+            let result = reviews::query_reviews(&conn, username, project_id, since_ms)?;
+            Ok(WhoRun {
+                resolved_input: WhoResolvedInput {
+                    mode: "reviews".to_string(),
+                    project_id,
+                    project_path,
+                    since_ms: Some(since_ms),
+                    since_iso: Some(ms_to_iso(since_ms)),
+                    since_mode: since_mode_for_defaulted.to_string(),
+                    limit: args.limit,
+                },
+                result: WhoResult::Reviews(result),
+            })
+        }
+        WhoMode::Active => {
+            let since_ms = resolve_since(args.since.as_deref(), "7d")?;
+
+            let result =
+                active::query_active(&conn, project_id, since_ms, limit, args.include_closed)?;
+            Ok(WhoRun {
+                resolved_input: WhoResolvedInput {
+                    mode: "active".to_string(),
+                    project_id,
+                    project_path,
+                    since_ms: Some(since_ms),
+                    since_iso: Some(ms_to_iso(since_ms)),
+                    since_mode: since_mode_for_defaulted.to_string(),
+                    limit: args.limit,
+                },
+                result: WhoResult::Active(result),
+            })
+        }
+        WhoMode::Overlap { path } => {
+            let since_ms = resolve_since(args.since.as_deref(), "30d")?;
+
+            let result = overlap::query_overlap(&conn, &path, project_id, since_ms, limit)?;
+            Ok(WhoRun {
+                resolved_input: WhoResolvedInput {
+                    mode: "overlap".to_string(),
+                    project_id,
+                    project_path,
+                    since_ms: Some(since_ms),
+                    since_iso: Some(ms_to_iso(since_ms)),
+                    since_mode: since_mode_for_defaulted.to_string(),
+                    limit: args.limit,
+                },
+                result: WhoResult::Overlap(result),
+            })
+        }
+    }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/// Look up the project path for a resolved project ID.
+fn lookup_project_path(conn: &Connection, project_id: i64) -> Result<String> {
+    conn.query_row(
+        "SELECT path_with_namespace FROM projects WHERE id = ?1",
+        rusqlite::params![project_id],
+        |row| row.get(0),
+    )
+    .map_err(|e| LoreError::Other(format!("Failed to look up project path: {e}")))
+}
+
+/// Parse --since with a default fallback.
+fn resolve_since(input: Option<&str>, default: &str) -> Result<i64> {
+    let s = input.unwrap_or(default);
+    parse_since(s).ok_or_else(|| {
+        LoreError::Other(format!(
+            "Invalid --since value: '{s}'. Use a duration (7d, 2w, 6m) or date (2024-01-15)"
+        ))
+    })
+}
+
+/// Parse --since with a default fallback, relative to a reference timestamp.
+/// Durations (7d, 2w, 6m) are computed from `reference_ms` instead of now.
+fn resolve_since_from(input: Option<&str>, default: &str, reference_ms: i64) -> Result<i64> {
+    let s = input.unwrap_or(default);
+    parse_since_from(s, reference_ms).ok_or_else(|| {
+        LoreError::Other(format!(
+            "Invalid --since value: '{s}'. Use a duration (7d, 2w, 6m) or date (2024-01-15)"
+        ))
+    })
+}
+
+/// Parse --since without a default (returns error if invalid).
+fn resolve_since_required(input: &str) -> Result<i64> {
+    parse_since(input).ok_or_else(|| {
+        LoreError::Other(format!(
+            "Invalid --since value: '{input}'. Use a duration (7d, 2w, 6m) or date (2024-01-15)"
+        ))
+    })
+}
+
+// ─── Human Output ────────────────────────────────────────────────────────────
+
+pub fn print_who_human(result: &WhoResult, project_path: Option<&str>) {
+    match result {
+        WhoResult::Expert(r) => expert::print_expert_human(r, project_path),
+        WhoResult::Workload(r) => workload::print_workload_human(r),
+        WhoResult::Reviews(r) => reviews::print_reviews_human(r),
+        WhoResult::Active(r) => active::print_active_human(r, project_path),
+        WhoResult::Overlap(r) => overlap::print_overlap_human(r, project_path),
+    }
+}
+
+/// Print a dim hint when results aggregate across all projects.
+pub(super) fn print_scope_hint(project_path: Option<&str>) {
+    if project_path.is_none() {
+        println!(
+            "  {}",
+            Theme::dim().render("(aggregated across all projects; use -p to scope)")
+        );
+    }
+}
+
+// ─── Robot JSON Output ───────────────────────────────────────────────────────
+
+pub fn print_who_json(run: &WhoRun, args: &WhoArgs, elapsed_ms: u64) {
+    let (mode, data) = match &run.result {
+        WhoResult::Expert(r) => ("expert", expert::expert_to_json(r)),
+        WhoResult::Workload(r) => ("workload", workload::workload_to_json(r)),
+        WhoResult::Reviews(r) => ("reviews", reviews::reviews_to_json(r)),
+        WhoResult::Active(r) => ("active", active::active_to_json(r)),
+        WhoResult::Overlap(r) => ("overlap", overlap::overlap_to_json(r)),
+    };
+
+    // Raw CLI args -- what the user typed
+    let input = serde_json::json!({
+        "target": args.target,
+        "path": args.path,
+        "project": args.project,
+        "since": args.since,
+        "limit": args.limit,
+        "detail": args.detail,
+        "as_of": args.as_of,
+        "explain_score": args.explain_score,
+        "include_bots": args.include_bots,
+        "all_history": args.all_history,
+    });
+
+    // Resolved/computed values -- what actually ran
+    let resolved_input = serde_json::json!({
+        "mode": run.resolved_input.mode,
+        "project_id": run.resolved_input.project_id,
+        "project_path": run.resolved_input.project_path,
+        "since_ms": run.resolved_input.since_ms,
+        "since_iso": run.resolved_input.since_iso,
+        "since_mode": run.resolved_input.since_mode,
+        "limit": run.resolved_input.limit,
+    });
+
+    let output = WhoJsonEnvelope {
+        ok: true,
+        data: WhoJsonData {
+            mode: mode.to_string(),
+            input,
+            resolved_input,
+            result: data,
+        },
+        meta: RobotMeta { elapsed_ms },
+    };
+
+    let mut value = serde_json::to_value(&output).unwrap_or_else(|e| {
+        serde_json::json!({"ok":false,"error":{"code":"INTERNAL_ERROR","message":format!("JSON serialization failed: {e}")}})
+    });
+
+    if let Some(f) = &args.fields {
+        let preset_key = format!("who_{mode}");
+        let expanded = crate::cli::robot::expand_fields_preset(f, &preset_key);
+        // Each who mode uses a different array key; try all possible keys
+        for key in &[
+            "experts",
+            "assigned_issues",
+            "authored_mrs",
+            "review_mrs",
+            "categories",
+            "discussions",
+            "users",
+        ] {
+            crate::cli::robot::filter_fields(&mut value, key, &expanded);
+        }
+    }
+
+    match serde_json::to_string(&value) {
+        Ok(json) => println!("{json}"),
+        Err(e) => eprintln!("Error serializing to JSON: {e}"),
+    }
+}
+
+#[derive(Serialize)]
+struct WhoJsonEnvelope {
+    ok: bool,
+    data: WhoJsonData,
+    meta: RobotMeta,
+}
+
+#[derive(Serialize)]
+struct WhoJsonData {
+    mode: String,
+    input: serde_json::Value,
+    resolved_input: serde_json::Value,
+    #[serde(flatten)]
+    result: serde_json::Value,
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+#[path = "../who_tests.rs"]
+mod tests;

src/cli/commands/who/overlap.rs

@@ -0,0 +1,323 @@
+use std::collections::{HashMap, HashSet};
+
+use rusqlite::Connection;
+
+use crate::cli::render::{self, Icons, Theme};
+use crate::core::error::Result;
+use crate::core::path_resolver::build_path_query;
+use crate::core::time::ms_to_iso;
+
+use super::types::*;
+
+pub(super) fn query_overlap(
+    conn: &Connection,
+    path: &str,
+    project_id: Option<i64>,
+    since_ms: i64,
+    limit: usize,
+) -> Result<OverlapResult> {
+    let pq = build_path_query(conn, path, project_id)?;
+
+    // Build SQL with 4 signal sources, matching the expert query expansion.
+    // Each row produces (username, role, mr_id, mr_ref, seen_at) for Rust-side accumulation.
+    let path_op = if pq.is_prefix {
+        "LIKE ?1 ESCAPE '\\'"
+    } else {
+        "= ?1"
+    };
+    // Match both new_path and old_path to capture activity on renamed files.
+    // INDEXED BY removed to allow OR across path columns; overlap runs once
+    // per command so the minor plan difference is acceptable.
+    let sql = format!(
+        "SELECT username, role, touch_count, last_seen_at, mr_refs FROM (
+            -- 1. DiffNote reviewer (matches both new_path and old_path)
+            SELECT
+                n.author_username AS username,
+                'reviewer' AS role,
+                COUNT(DISTINCT m.id) AS touch_count,
+                MAX(n.created_at) AS last_seen_at,
+                GROUP_CONCAT(DISTINCT (p.path_with_namespace || '!' || m.iid)) AS mr_refs
+            FROM notes n
+            JOIN discussions d ON n.discussion_id = d.id
+            JOIN merge_requests m ON d.merge_request_id = m.id
+            JOIN projects p ON m.project_id = p.id
+            WHERE n.note_type = 'DiffNote'
+              AND (n.position_new_path {path_op}
+                   OR (n.position_old_path IS NOT NULL AND n.position_old_path {path_op}))
+              AND n.is_system = 0
+              AND n.author_username IS NOT NULL
+              AND (m.author_username IS NULL OR n.author_username != m.author_username)
+              AND m.state IN ('opened','merged','closed')
+              AND n.created_at >= ?2
+              AND (?3 IS NULL OR n.project_id = ?3)
+            GROUP BY n.author_username
+
+            UNION ALL
+
+            -- 2. DiffNote MR author (matches both new_path and old_path)
+            SELECT
+                m.author_username AS username,
+                'author' AS role,
+                COUNT(DISTINCT m.id) AS touch_count,
+                MAX(n.created_at) AS last_seen_at,
+                GROUP_CONCAT(DISTINCT (p.path_with_namespace || '!' || m.iid)) AS mr_refs
+            FROM notes n
+            JOIN discussions d ON n.discussion_id = d.id
+            JOIN merge_requests m ON d.merge_request_id = m.id
+            JOIN projects p ON m.project_id = p.id
+            WHERE n.note_type = 'DiffNote'
+              AND (n.position_new_path {path_op}
+                   OR (n.position_old_path IS NOT NULL AND n.position_old_path {path_op}))
+              AND n.is_system = 0
+              AND m.state IN ('opened','merged','closed')
+              AND m.author_username IS NOT NULL
+              AND n.created_at >= ?2
+              AND (?3 IS NULL OR n.project_id = ?3)
+            GROUP BY m.author_username
+
+            UNION ALL
+
+            -- 3. MR author via file changes (matches both new_path and old_path)
+            SELECT
+                m.author_username AS username,
+                'author' AS role,
+                COUNT(DISTINCT m.id) AS touch_count,
+                MAX(m.updated_at) AS last_seen_at,
+                GROUP_CONCAT(DISTINCT (p.path_with_namespace || '!' || m.iid)) AS mr_refs
+            FROM mr_file_changes fc
+            JOIN merge_requests m ON fc.merge_request_id = m.id
+            JOIN projects p ON m.project_id = p.id
+            WHERE m.author_username IS NOT NULL
+              AND m.state IN ('opened','merged','closed')
+              AND (fc.new_path {path_op}
+                   OR (fc.old_path IS NOT NULL AND fc.old_path {path_op}))
+              AND m.updated_at >= ?2
+              AND (?3 IS NULL OR fc.project_id = ?3)
+            GROUP BY m.author_username
+
+            UNION ALL
+
+            -- 4. MR reviewer via file changes + mr_reviewers (matches both new_path and old_path)
+            SELECT
+                r.username AS username,
+                'reviewer' AS role,
+                COUNT(DISTINCT m.id) AS touch_count,
+                MAX(m.updated_at) AS last_seen_at,
+                GROUP_CONCAT(DISTINCT (p.path_with_namespace || '!' || m.iid)) AS mr_refs
+            FROM mr_file_changes fc
+            JOIN merge_requests m ON fc.merge_request_id = m.id
+            JOIN projects p ON m.project_id = p.id
+            JOIN mr_reviewers r ON r.merge_request_id = m.id
+            WHERE r.username IS NOT NULL
+              AND (m.author_username IS NULL OR r.username != m.author_username)
+              AND m.state IN ('opened','merged','closed')
+              AND (fc.new_path {path_op}
+                   OR (fc.old_path IS NOT NULL AND fc.old_path {path_op}))
+              AND m.updated_at >= ?2
+              AND (?3 IS NULL OR fc.project_id = ?3)
+            GROUP BY r.username
+        )"
+    );
+
+    let mut stmt = conn.prepare_cached(&sql)?;
+    let rows: Vec<(String, String, u32, i64, Option<String>)> = stmt
+        .query_map(rusqlite::params![pq.value, since_ms, project_id], |row| {
+            Ok((
+                row.get(0)?,
+                row.get(1)?,
+                row.get(2)?,
+                row.get(3)?,
+                row.get(4)?,
+            ))
+        })?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    // Internal accumulator uses HashSet for MR refs from the start
+    struct OverlapAcc {
+        username: String,
+        author_touch_count: u32,
+        review_touch_count: u32,
+        touch_count: u32,
+        last_seen_at: i64,
+        mr_refs: HashSet<String>,
+    }
+
+    let mut user_map: HashMap<String, OverlapAcc> = HashMap::new();
+    for (username, role, count, last_seen, mr_refs_csv) in &rows {
+        let mr_refs: Vec<String> = mr_refs_csv
+            .as_deref()
+            .map(|csv| csv.split(',').map(|s| s.trim().to_string()).collect())
+            .unwrap_or_default();
+
+        let entry = user_map
+            .entry(username.clone())
+            .or_insert_with(|| OverlapAcc {
+                username: username.clone(),
+                author_touch_count: 0,
+                review_touch_count: 0,
+                touch_count: 0,
+                last_seen_at: 0,
+                mr_refs: HashSet::new(),
+            });
+        entry.touch_count += count;
+        if role == "author" {
+            entry.author_touch_count += count;
+        } else {
+            entry.review_touch_count += count;
+        }
+        if *last_seen > entry.last_seen_at {
+            entry.last_seen_at = *last_seen;
+        }
+        for r in mr_refs {
+            entry.mr_refs.insert(r);
+        }
+    }
+
+    // Convert accumulators to output structs
+    let mut users: Vec<OverlapUser> = user_map
+        .into_values()
+        .map(|a| {
+            let mut mr_refs: Vec<String> = a.mr_refs.into_iter().collect();
+            mr_refs.sort();
+            let mr_refs_total = mr_refs.len() as u32;
+            let mr_refs_truncated = mr_refs.len() > MAX_MR_REFS_PER_USER;
+            if mr_refs_truncated {
+                mr_refs.truncate(MAX_MR_REFS_PER_USER);
+            }
+            OverlapUser {
+                username: a.username,
+                author_touch_count: a.author_touch_count,
+                review_touch_count: a.review_touch_count,
+                touch_count: a.touch_count,
+                last_seen_at: a.last_seen_at,
+                mr_refs,
+                mr_refs_total,
+                mr_refs_truncated,
+            }
+        })
+        .collect();
+
+    // Stable sort with full tie-breakers for deterministic output
+    users.sort_by(|a, b| {
+        b.touch_count
+            .cmp(&a.touch_count)
+            .then_with(|| b.last_seen_at.cmp(&a.last_seen_at))
+            .then_with(|| a.username.cmp(&b.username))
+    });
+
+    let truncated = users.len() > limit;
+    users.truncate(limit);
+
+    Ok(OverlapResult {
+        path_query: if pq.is_prefix {
+            path.trim_end_matches('/').to_string()
+        } else {
+            pq.value.clone()
+        },
+        path_match: if pq.is_prefix { "prefix" } else { "exact" }.to_string(),
+        users,
+        truncated,
+    })
+}
+
+/// Format overlap role for display: "A", "R", or "A+R".
+pub(super) fn format_overlap_role(user: &OverlapUser) -> &'static str {
+    match (user.author_touch_count > 0, user.review_touch_count > 0) {
+        (true, true) => "A+R",
+        (true, false) => "A",
+        (false, true) => "R",
+        (false, false) => "-",
+    }
+}
+
+pub(super) fn print_overlap_human(r: &OverlapResult, project_path: Option<&str>) {
+    println!();
+    println!(
+        "{}",
+        Theme::bold().render(&format!("Overlap for {}", r.path_query))
+    );
+    println!("{}", "\u{2500}".repeat(60));
+    println!(
+        "  {}",
+        Theme::dim().render(&format!(
+            "(matching {} {})",
+            r.path_match,
+            if r.path_match == "exact" {
+                "file"
+            } else {
+                "directory prefix"
+            }
+        ))
+    );
+    super::print_scope_hint(project_path);
+    println!();
+
+    if r.users.is_empty() {
+        println!(
+            "  {}",
+            Theme::dim().render("No overlapping users found for this path.")
+        );
+        println!();
+        return;
+    }
+
+    println!(
+        "  {:<16} {:<6} {:>7}  {:<12}  {}",
+        Theme::bold().render("Username"),
+        Theme::bold().render("Role"),
+        Theme::bold().render("MRs"),
+        Theme::bold().render("Last Seen"),
+        Theme::bold().render("MR Refs"),
+    );
+
+    for user in &r.users {
+        let mr_str = user
+            .mr_refs
+            .iter()
+            .take(5)
+            .cloned()
+            .collect::<Vec<_>>()
+            .join(", ");
+        let overflow = if user.mr_refs.len() > 5 {
+            format!(" +{}", user.mr_refs.len() - 5)
+        } else {
+            String::new()
+        };
+
+        println!(
+            "  {:<16} {:<6} {:>7}  {:<12}  {}{}",
+            Theme::info().render(&format!("{} {}", Icons::user(), user.username)),
+            format_overlap_role(user),
+            user.touch_count,
+            render::format_relative_time(user.last_seen_at),
+            mr_str,
+            overflow,
+        );
+    }
+    if r.truncated {
+        println!(
+            "  {}",
+            Theme::dim().render("(showing first -n; rerun with a higher --limit)")
+        );
+    }
+    println!();
+}
+
+pub(super) fn overlap_to_json(r: &OverlapResult) -> serde_json::Value {
+    serde_json::json!({
+        "path_query": r.path_query,
+        "path_match": r.path_match,
+        "truncated": r.truncated,
+        "users": r.users.iter().map(|u| serde_json::json!({
+            "username": u.username,
+            "role": format_overlap_role(u),
+            "author_touch_count": u.author_touch_count,
+            "review_touch_count": u.review_touch_count,
+            "touch_count": u.touch_count,
+            "last_seen_at": ms_to_iso(u.last_seen_at),
+            "mr_refs": u.mr_refs,
+            "mr_refs_total": u.mr_refs_total,
+            "mr_refs_truncated": u.mr_refs_truncated,
+        })).collect::<Vec<_>>(),
+    })
+}

src/cli/commands/who/reviews.rs

@@ -0,0 +1,214 @@
+use std::collections::HashMap;
+
+use rusqlite::Connection;
+
+use crate::cli::render::{Icons, Theme};
+use crate::core::error::Result;
+
+use super::types::*;
+
+// ─── Query: Reviews Mode ────────────────────────────────────────────────────
+
+pub(super) fn query_reviews(
+    conn: &Connection,
+    username: &str,
+    project_id: Option<i64>,
+    since_ms: i64,
+) -> Result<ReviewsResult> {
+    // Force the partial index on DiffNote queries (same rationale as expert mode).
+    // COUNT + COUNT(DISTINCT) + category extraction all benefit from 26K DiffNote
+    // scan vs 282K notes full scan: measured 25x speedup.
+    let total_sql = "SELECT COUNT(*) FROM notes n
+         INDEXED BY idx_notes_diffnote_path_created
+         JOIN discussions d ON n.discussion_id = d.id
+         JOIN merge_requests m ON d.merge_request_id = m.id
+         WHERE n.author_username = ?1
+           AND n.note_type = 'DiffNote'
+           AND n.is_system = 0
+           AND (m.author_username IS NULL OR m.author_username != ?1)
+           AND n.created_at >= ?2
+           AND (?3 IS NULL OR n.project_id = ?3)";
+
+    let total_diffnotes: u32 = conn.query_row(
+        total_sql,
+        rusqlite::params![username, since_ms, project_id],
+        |row| row.get(0),
+    )?;
+
+    // Count distinct MRs reviewed
+    let mrs_sql = "SELECT COUNT(DISTINCT m.id) FROM notes n
+         INDEXED BY idx_notes_diffnote_path_created
+         JOIN discussions d ON n.discussion_id = d.id
+         JOIN merge_requests m ON d.merge_request_id = m.id
+         WHERE n.author_username = ?1
+           AND n.note_type = 'DiffNote'
+           AND n.is_system = 0
+           AND (m.author_username IS NULL OR m.author_username != ?1)
+           AND n.created_at >= ?2
+           AND (?3 IS NULL OR n.project_id = ?3)";
+
+    let mrs_reviewed: u32 = conn.query_row(
+        mrs_sql,
+        rusqlite::params![username, since_ms, project_id],
+        |row| row.get(0),
+    )?;
+
+    // Extract prefixed categories: body starts with **prefix**
+    let cat_sql = "SELECT
+            SUBSTR(ltrim(n.body), 3, INSTR(SUBSTR(ltrim(n.body), 3), '**') - 1) AS raw_prefix,
+            COUNT(*) AS cnt
+         FROM notes n INDEXED BY idx_notes_diffnote_path_created
+         JOIN discussions d ON n.discussion_id = d.id
+         JOIN merge_requests m ON d.merge_request_id = m.id
+         WHERE n.author_username = ?1
+           AND n.note_type = 'DiffNote'
+           AND n.is_system = 0
+           AND (m.author_username IS NULL OR m.author_username != ?1)
+           AND ltrim(n.body) LIKE '**%**%'
+           AND n.created_at >= ?2
+           AND (?3 IS NULL OR n.project_id = ?3)
+         GROUP BY raw_prefix
+         ORDER BY cnt DESC";
+
+    let mut stmt = conn.prepare_cached(cat_sql)?;
+    let raw_categories: Vec<(String, u32)> = stmt
+        .query_map(rusqlite::params![username, since_ms, project_id], |row| {
+            Ok((row.get::<_, String>(0)?, row.get(1)?))
+        })?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    // Normalize categories: lowercase, strip trailing colon/space,
+    // merge nit/nitpick variants, merge (non-blocking) variants
+    let mut merged: HashMap<String, u32> = HashMap::new();
+    for (raw, count) in &raw_categories {
+        let normalized = normalize_review_prefix(raw);
+        if !normalized.is_empty() {
+            *merged.entry(normalized).or_insert(0) += count;
+        }
+    }
+
+    let categorized_count: u32 = merged.values().sum();
+
+    let mut categories: Vec<ReviewCategory> = merged
+        .into_iter()
+        .map(|(name, count)| {
+            let percentage = if categorized_count > 0 {
+                f64::from(count) / f64::from(categorized_count) * 100.0
+            } else {
+                0.0
+            };
+            ReviewCategory {
+                name,
+                count,
+                percentage,
+            }
+        })
+        .collect();
+
+    categories.sort_by_key(|b| std::cmp::Reverse(b.count));
+
+    Ok(ReviewsResult {
+        username: username.to_string(),
+        total_diffnotes,
+        categorized_count,
+        mrs_reviewed,
+        categories,
+    })
+}
+
+/// Normalize a raw review prefix like "Suggestion (non-blocking):" into "suggestion".
+pub(super) fn normalize_review_prefix(raw: &str) -> String {
+    let s = raw.trim().trim_end_matches(':').trim().to_lowercase();
+
+    // Strip "(non-blocking)" and similar parentheticals
+    let s = if let Some(idx) = s.find('(') {
+        s[..idx].trim().to_string()
+    } else {
+        s
+    };
+
+    // Merge nit/nitpick variants
+    match s.as_str() {
+        "nitpick" | "nit" => "nit".to_string(),
+        other => other.to_string(),
+    }
+}
+
+// ─── Human Renderer ─────────────────────────────────────────────────────────
+
+pub(super) fn print_reviews_human(r: &ReviewsResult) {
+    println!();
+    println!(
+        "{}",
+        Theme::bold().render(&format!(
+            "{} {} -- Review Patterns",
+            Icons::user(),
+            r.username
+        ))
+    );
+    println!("{}", "\u{2500}".repeat(60));
+    println!();
+
+    if r.total_diffnotes == 0 {
+        println!(
+            "  {}",
+            Theme::dim().render("No review comments found for this user.")
+        );
+        println!();
+        return;
+    }
+
+    println!(
+        "  {} DiffNotes across {} MRs ({} categorized)",
+        Theme::bold().render(&r.total_diffnotes.to_string()),
+        Theme::bold().render(&r.mrs_reviewed.to_string()),
+        Theme::bold().render(&r.categorized_count.to_string()),
+    );
+    println!();
+
+    if !r.categories.is_empty() {
+        println!(
+            "  {:<16} {:>6} {:>6}",
+            Theme::bold().render("Category"),
+            Theme::bold().render("Count"),
+            Theme::bold().render("%"),
+        );
+
+        for cat in &r.categories {
+            println!(
+                "  {:<16} {:>6} {:>5.1}%",
+                Theme::info().render(&cat.name),
+                cat.count,
+                cat.percentage,
+            );
+        }
+    }
+
+    let uncategorized = r.total_diffnotes - r.categorized_count;
+    if uncategorized > 0 {
+        println!();
+        println!(
+            "  {} {} uncategorized (no **prefix** convention)",
+            Theme::dim().render("Note:"),
+            uncategorized,
+        );
+    }
+
+    println!();
+}
+
+// ─── Robot Renderer ─────────────────────────────────────────────────────────
+
+pub(super) fn reviews_to_json(r: &ReviewsResult) -> serde_json::Value {
+    serde_json::json!({
+        "username": r.username,
+        "total_diffnotes": r.total_diffnotes,
+        "categorized_count": r.categorized_count,
+        "mrs_reviewed": r.mrs_reviewed,
+        "categories": r.categories.iter().map(|c| serde_json::json!({
+            "name": c.name,
+            "count": c.count,
+            "percentage": (c.percentage * 10.0).round() / 10.0,
+        })).collect::<Vec<_>>(),
+    })
+}

src/cli/commands/who/types.rs

@@ -0,0 +1,185 @@
+// ─── Result Types ────────────────────────────────────────────────────────────
+//
+// All pub result structs and enums for the `who` command family.
+// Zero logic — pure data definitions.
+
+/// Top-level run result: carries resolved inputs + the mode-specific result.
+pub struct WhoRun {
+    pub resolved_input: WhoResolvedInput,
+    pub result: WhoResult,
+}
+
+/// Resolved query parameters -- computed once, used for robot JSON reproducibility.
+pub struct WhoResolvedInput {
+    pub mode: String,
+    pub project_id: Option<i64>,
+    pub project_path: Option<String>,
+    pub since_ms: Option<i64>,
+    pub since_iso: Option<String>,
+    /// "default" (mode default applied), "explicit" (user provided --since), "none" (no window)
+    pub since_mode: String,
+    pub limit: Option<u16>,
+}
+
+/// Top-level result enum -- one variant per mode.
+pub enum WhoResult {
+    Expert(ExpertResult),
+    Workload(WorkloadResult),
+    Reviews(ReviewsResult),
+    Active(ActiveResult),
+    Overlap(OverlapResult),
+}
+
+// --- Expert ---
+
+pub struct ExpertResult {
+    pub path_query: String,
+    /// "exact" or "prefix" -- how the path was matched in SQL.
+    pub path_match: String,
+    pub experts: Vec<Expert>,
+    pub truncated: bool,
+}
+
+pub struct Expert {
+    pub username: String,
+    pub score: i64,
+    /// Unrounded f64 score (only populated when explain_score is set).
+    pub score_raw: Option<f64>,
+    /// Per-component score breakdown (only populated when explain_score is set).
+    pub components: Option<ScoreComponents>,
+    pub review_mr_count: u32,
+    pub review_note_count: u32,
+    pub author_mr_count: u32,
+    pub last_seen_ms: i64,
+    /// Stable MR references like "group/project!123"
+    pub mr_refs: Vec<String>,
+    pub mr_refs_total: u32,
+    pub mr_refs_truncated: bool,
+    /// Per-MR detail breakdown (only populated when --detail is set)
+    pub details: Option<Vec<ExpertMrDetail>>,
+}
+
+/// Per-component score breakdown for explain mode.
+pub struct ScoreComponents {
+    pub author: f64,
+    pub reviewer_participated: f64,
+    pub reviewer_assigned: f64,
+    pub notes: f64,
+}
+
+#[derive(Clone)]
+pub struct ExpertMrDetail {
+    pub mr_ref: String,
+    pub title: String,
+    /// "R", "A", or "A+R"
+    pub role: String,
+    pub note_count: u32,
+    pub last_activity_ms: i64,
+}
+
+// --- Workload ---
+
+pub struct WorkloadResult {
+    pub username: String,
+    pub assigned_issues: Vec<WorkloadIssue>,
+    pub authored_mrs: Vec<WorkloadMr>,
+    pub reviewing_mrs: Vec<WorkloadMr>,
+    pub unresolved_discussions: Vec<WorkloadDiscussion>,
+    pub assigned_issues_truncated: bool,
+    pub authored_mrs_truncated: bool,
+    pub reviewing_mrs_truncated: bool,
+    pub unresolved_discussions_truncated: bool,
+}
+
+pub struct WorkloadIssue {
+    pub iid: i64,
+    /// Canonical reference: `group/project#iid`
+    pub ref_: String,
+    pub title: String,
+    pub project_path: String,
+    pub updated_at: i64,
+}
+
+pub struct WorkloadMr {
+    pub iid: i64,
+    /// Canonical reference: `group/project!iid`
+    pub ref_: String,
+    pub title: String,
+    pub draft: bool,
+    pub project_path: String,
+    pub author_username: Option<String>,
+    pub updated_at: i64,
+}
+
+pub struct WorkloadDiscussion {
+    pub entity_type: String,
+    pub entity_iid: i64,
+    /// Canonical reference: `group/project!iid` or `group/project#iid`
+    pub ref_: String,
+    pub entity_title: String,
+    pub project_path: String,
+    pub last_note_at: i64,
+}
+
+// --- Reviews ---
+
+pub struct ReviewsResult {
+    pub username: String,
+    pub total_diffnotes: u32,
+    pub categorized_count: u32,
+    pub mrs_reviewed: u32,
+    pub categories: Vec<ReviewCategory>,
+}
+
+pub struct ReviewCategory {
+    pub name: String,
+    pub count: u32,
+    pub percentage: f64,
+}
+
+// --- Active ---
+
+pub struct ActiveResult {
+    pub discussions: Vec<ActiveDiscussion>,
+    /// Count of unresolved discussions *within the time window*, not total across all time.
+    pub total_unresolved_in_window: u32,
+    pub truncated: bool,
+}
+
+pub struct ActiveDiscussion {
+    pub discussion_id: i64,
+    pub entity_type: String,
+    pub entity_iid: i64,
+    pub entity_title: String,
+    pub project_path: String,
+    pub last_note_at: i64,
+    pub note_count: u32,
+    pub participants: Vec<String>,
+    pub participants_total: u32,
+    pub participants_truncated: bool,
+}
+
+// --- Overlap ---
+
+pub struct OverlapResult {
+    pub path_query: String,
+    /// "exact" or "prefix" -- how the path was matched in SQL.
+    pub path_match: String,
+    pub users: Vec<OverlapUser>,
+    pub truncated: bool,
+}
+
+pub struct OverlapUser {
+    pub username: String,
+    pub author_touch_count: u32,
+    pub review_touch_count: u32,
+    pub touch_count: u32,
+    pub last_seen_at: i64,
+    /// Stable MR references like "group/project!123"
+    pub mr_refs: Vec<String>,
+    pub mr_refs_total: u32,
+    pub mr_refs_truncated: bool,
+}
+
+/// Maximum MR references to retain per user in output (shared across modes).
+pub const MAX_MR_REFS_PER_USER: usize = 50;

src/cli/commands/who/workload.rs

@@ -0,0 +1,372 @@
+use rusqlite::Connection;
+
+use crate::cli::render::{self, Icons, Theme};
+use crate::core::error::Result;
+use crate::core::time::ms_to_iso;
+
+use super::types::*;
+
+// ─── Query: Workload Mode ───────────────────────────────────────────────────
+
+pub(super) fn query_workload(
+    conn: &Connection,
+    username: &str,
+    project_id: Option<i64>,
+    since_ms: Option<i64>,
+    limit: usize,
+    include_closed: bool,
+) -> Result<WorkloadResult> {
+    // Prevent overflow: saturating_add caps at usize::MAX instead of wrapping to 0.
+    // The .min() ensures the value fits in i64 for SQLite's LIMIT clause.
+    let limit_plus_one = limit.saturating_add(1).min(i64::MAX as usize) as i64;
+
+    // Query 1: Open issues assigned to user
+    let issues_sql = "SELECT i.iid,
+                (p.path_with_namespace || '#' || i.iid) AS ref,
+                i.title, p.path_with_namespace, i.updated_at
+         FROM issues i
+         JOIN issue_assignees ia ON ia.issue_id = i.id
+         JOIN projects p ON i.project_id = p.id
+         WHERE ia.username = ?1
+           AND i.state = 'opened'
+           AND (?2 IS NULL OR i.project_id = ?2)
+           AND (?3 IS NULL OR i.updated_at >= ?3)
+         ORDER BY i.updated_at DESC
+         LIMIT ?4";
+
+    let mut stmt = conn.prepare_cached(issues_sql)?;
+    let assigned_issues: Vec<WorkloadIssue> = stmt
+        .query_map(
+            rusqlite::params![username, project_id, since_ms, limit_plus_one],
+            |row| {
+                Ok(WorkloadIssue {
+                    iid: row.get(0)?,
+                    ref_: row.get(1)?,
+                    title: row.get(2)?,
+                    project_path: row.get(3)?,
+                    updated_at: row.get(4)?,
+                })
+            },
+        )?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    // Query 2: Open MRs authored
+    let authored_sql = "SELECT m.iid,
+                (p.path_with_namespace || '!' || m.iid) AS ref,
+                m.title, m.draft, p.path_with_namespace, m.updated_at
+         FROM merge_requests m
+         JOIN projects p ON m.project_id = p.id
+         WHERE m.author_username = ?1
+           AND m.state = 'opened'
+           AND (?2 IS NULL OR m.project_id = ?2)
+           AND (?3 IS NULL OR m.updated_at >= ?3)
+         ORDER BY m.updated_at DESC
+         LIMIT ?4";
+    let mut stmt = conn.prepare_cached(authored_sql)?;
+    let authored_mrs: Vec<WorkloadMr> = stmt
+        .query_map(
+            rusqlite::params![username, project_id, since_ms, limit_plus_one],
+            |row| {
+                Ok(WorkloadMr {
+                    iid: row.get(0)?,
+                    ref_: row.get(1)?,
+                    title: row.get(2)?,
+                    draft: row.get::<_, i32>(3)? != 0,
+                    project_path: row.get(4)?,
+                    author_username: None,
+                    updated_at: row.get(5)?,
+                })
+            },
+        )?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    // Query 3: Open MRs where user is reviewer
+    let reviewing_sql = "SELECT m.iid,
+                (p.path_with_namespace || '!' || m.iid) AS ref,
+                m.title, m.draft, p.path_with_namespace,
+                m.author_username, m.updated_at
+         FROM merge_requests m
+         JOIN mr_reviewers r ON r.merge_request_id = m.id
+         JOIN projects p ON m.project_id = p.id
+         WHERE r.username = ?1
+           AND m.state = 'opened'
+           AND (?2 IS NULL OR m.project_id = ?2)
+           AND (?3 IS NULL OR m.updated_at >= ?3)
+         ORDER BY m.updated_at DESC
+         LIMIT ?4";
+    let mut stmt = conn.prepare_cached(reviewing_sql)?;
+    let reviewing_mrs: Vec<WorkloadMr> = stmt
+        .query_map(
+            rusqlite::params![username, project_id, since_ms, limit_plus_one],
+            |row| {
+                Ok(WorkloadMr {
+                    iid: row.get(0)?,
+                    ref_: row.get(1)?,
+                    title: row.get(2)?,
+                    draft: row.get::<_, i32>(3)? != 0,
+                    project_path: row.get(4)?,
+                    author_username: row.get(5)?,
+                    updated_at: row.get(6)?,
+                })
+            },
+        )?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    // Query 4: Unresolved discussions where user participated
+    let state_filter = if include_closed {
+        ""
+    } else {
+        " AND (i.id IS NULL OR i.state = 'opened')
+           AND (m.id IS NULL OR m.state = 'opened')"
+    };
+    let disc_sql = format!(
+        "SELECT d.noteable_type,
+                COALESCE(i.iid, m.iid) AS entity_iid,
+                (p.path_with_namespace ||
+                 CASE WHEN d.noteable_type = 'MergeRequest' THEN '!' ELSE '#' END ||
+                 COALESCE(i.iid, m.iid)) AS ref,
+                COALESCE(i.title, m.title) AS entity_title,
+                p.path_with_namespace,
+                d.last_note_at
+         FROM discussions d
+         JOIN projects p ON d.project_id = p.id
+         LEFT JOIN issues i ON d.issue_id = i.id
+         LEFT JOIN merge_requests m ON d.merge_request_id = m.id
+         WHERE d.resolvable = 1 AND d.resolved = 0
+           AND EXISTS (
+             SELECT 1 FROM notes n
+             WHERE n.discussion_id = d.id
+             AND n.author_username = ?1
+             AND n.is_system = 0
+           )
+           AND (?2 IS NULL OR d.project_id = ?2)
+           AND (?3 IS NULL OR d.last_note_at >= ?3)
+           {state_filter}
+         ORDER BY d.last_note_at DESC
+         LIMIT ?4"
+    );
+
+    let mut stmt = conn.prepare_cached(&disc_sql)?;
+    let unresolved_discussions: Vec<WorkloadDiscussion> = stmt
+        .query_map(
+            rusqlite::params![username, project_id, since_ms, limit_plus_one],
+            |row| {
+                let noteable_type: String = row.get(0)?;
+                let entity_type = if noteable_type == "MergeRequest" {
+                    "MR"
+                } else {
+                    "Issue"
+                };
+                Ok(WorkloadDiscussion {
+                    entity_type: entity_type.to_string(),
+                    entity_iid: row.get(1)?,
+                    ref_: row.get(2)?,
+                    entity_title: row.get(3)?,
+                    project_path: row.get(4)?,
+                    last_note_at: row.get(5)?,
+                })
+            },
+        )?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    // Truncation detection
+    let assigned_issues_truncated = assigned_issues.len() > limit;
+    let authored_mrs_truncated = authored_mrs.len() > limit;
+    let reviewing_mrs_truncated = reviewing_mrs.len() > limit;
+    let unresolved_discussions_truncated = unresolved_discussions.len() > limit;
+
+    let assigned_issues: Vec<WorkloadIssue> = assigned_issues.into_iter().take(limit).collect();
+    let authored_mrs: Vec<WorkloadMr> = authored_mrs.into_iter().take(limit).collect();
+    let reviewing_mrs: Vec<WorkloadMr> = reviewing_mrs.into_iter().take(limit).collect();
+    let unresolved_discussions: Vec<WorkloadDiscussion> =
+        unresolved_discussions.into_iter().take(limit).collect();
+
+    Ok(WorkloadResult {
+        username: username.to_string(),
+        assigned_issues,
+        authored_mrs,
+        reviewing_mrs,
+        unresolved_discussions,
+        assigned_issues_truncated,
+        authored_mrs_truncated,
+        reviewing_mrs_truncated,
+        unresolved_discussions_truncated,
+    })
+}
+
+// ─── Human Renderer: Workload ───────────────────────────────────────────────
+
+pub(super) fn print_workload_human(r: &WorkloadResult) {
+    println!();
+    println!(
+        "{}",
+        Theme::bold().render(&format!(
+            "{} {} -- Workload Summary",
+            Icons::user(),
+            r.username
+        ))
+    );
+    println!("{}", "\u{2500}".repeat(60));
+
+    if !r.assigned_issues.is_empty() {
+        println!(
+            "{}",
+            render::section_divider(&format!("Assigned Issues ({})", r.assigned_issues.len()))
+        );
+        for item in &r.assigned_issues {
+            println!(
+                "    {} {}  {}",
+                Theme::info().render(&item.ref_),
+                render::truncate(&item.title, 40),
+                Theme::dim().render(&render::format_relative_time(item.updated_at)),
+            );
+        }
+        if r.assigned_issues_truncated {
+            println!(
+                "    {}",
+                Theme::dim().render("(truncated; rerun with a higher --limit)")
+            );
+        }
+    }
+
+    if !r.authored_mrs.is_empty() {
+        println!(
+            "{}",
+            render::section_divider(&format!("Authored MRs ({})", r.authored_mrs.len()))
+        );
+        for mr in &r.authored_mrs {
+            let draft = if mr.draft { " [draft]" } else { "" };
+            println!(
+                "    {} {}{}  {}",
+                Theme::info().render(&mr.ref_),
+                render::truncate(&mr.title, 35),
+                Theme::dim().render(draft),
+                Theme::dim().render(&render::format_relative_time(mr.updated_at)),
+            );
+        }
+        if r.authored_mrs_truncated {
+            println!(
+                "    {}",
+                Theme::dim().render("(truncated; rerun with a higher --limit)")
+            );
+        }
+    }
+
+    if !r.reviewing_mrs.is_empty() {
+        println!(
+            "{}",
+            render::section_divider(&format!("Reviewing MRs ({})", r.reviewing_mrs.len()))
+        );
+        for mr in &r.reviewing_mrs {
+            let author = mr
+                .author_username
+                .as_deref()
+                .map(|a| format!(" by @{a}"))
+                .unwrap_or_default();
+            println!(
+                "    {} {}{}  {}",
+                Theme::info().render(&mr.ref_),
+                render::truncate(&mr.title, 30),
+                Theme::dim().render(&author),
+                Theme::dim().render(&render::format_relative_time(mr.updated_at)),
+            );
+        }
+        if r.reviewing_mrs_truncated {
+            println!(
+                "    {}",
+                Theme::dim().render("(truncated; rerun with a higher --limit)")
+            );
+        }
+    }
+
+    if !r.unresolved_discussions.is_empty() {
+        println!(
+            "{}",
+            render::section_divider(&format!(
+                "Unresolved Discussions ({})",
+                r.unresolved_discussions.len()
+            ))
+        );
+        for disc in &r.unresolved_discussions {
+            println!(
+                "    {} {} {}  {}",
+                Theme::dim().render(&disc.entity_type),
+                Theme::info().render(&disc.ref_),
+                render::truncate(&disc.entity_title, 35),
+                Theme::dim().render(&render::format_relative_time(disc.last_note_at)),
+            );
+        }
+        if r.unresolved_discussions_truncated {
+            println!(
+                "    {}",
+                Theme::dim().render("(truncated; rerun with a higher --limit)")
+            );
+        }
+    }
+
+    if r.assigned_issues.is_empty()
+        && r.authored_mrs.is_empty()
+        && r.reviewing_mrs.is_empty()
+        && r.unresolved_discussions.is_empty()
+    {
+        println!();
+        println!(
+            "  {}",
+            Theme::dim().render("No open work items found for this user.")
+        );
+    }
+
+    println!();
+}
+
+// ─── JSON Renderer: Workload ────────────────────────────────────────────────
+
+pub(super) fn workload_to_json(r: &WorkloadResult) -> serde_json::Value {
+    serde_json::json!({
+        "username": r.username,
+        "assigned_issues": r.assigned_issues.iter().map(|i| serde_json::json!({
+            "iid": i.iid,
+            "ref": i.ref_,
+            "title": i.title,
+            "project_path": i.project_path,
+            "updated_at": ms_to_iso(i.updated_at),
+        })).collect::<Vec<_>>(),
+        "authored_mrs": r.authored_mrs.iter().map(|m| serde_json::json!({
+            "iid": m.iid,
+            "ref": m.ref_,
+            "title": m.title,
+            "draft": m.draft,
+            "project_path": m.project_path,
+            "updated_at": ms_to_iso(m.updated_at),
+        })).collect::<Vec<_>>(),
+        "reviewing_mrs": r.reviewing_mrs.iter().map(|m| serde_json::json!({
+            "iid": m.iid,
+            "ref": m.ref_,
+            "title": m.title,
+            "draft": m.draft,
+            "project_path": m.project_path,
+            "author_username": m.author_username,
+            "updated_at": ms_to_iso(m.updated_at),
+        })).collect::<Vec<_>>(),
+        "unresolved_discussions": r.unresolved_discussions.iter().map(|d| serde_json::json!({
+            "entity_type": d.entity_type,
+            "entity_iid": d.entity_iid,
+            "ref": d.ref_,
+            "entity_title": d.entity_title,
+            "project_path": d.project_path,
+            "last_note_at": ms_to_iso(d.last_note_at),
+        })).collect::<Vec<_>>(),
+        "summary": {
+            "assigned_issue_count": r.assigned_issues.len(),
+            "authored_mr_count": r.authored_mrs.len(),
+            "reviewing_mr_count": r.reviewing_mrs.len(),
+            "unresolved_discussion_count": r.unresolved_discussions.len(),
+        },
+        "truncation": {
+            "assigned_issues_truncated": r.assigned_issues_truncated,
+            "authored_mrs_truncated": r.authored_mrs_truncated,
+            "reviewing_mrs_truncated": r.reviewing_mrs_truncated,
+            "unresolved_discussions_truncated": r.unresolved_discussions_truncated,
+        }
+    })
+}

src/cli/commands/who_tests.rs

@@ -286,7 +286,7 @@ fn test_is_file_path_discrimination() {
             reviews: false,
             since: None,
             project: None,
-            limit: 20,
+            limit: None,
             detail: false,
             no_detail: false,
             fields: None,
@@ -310,7 +310,7 @@ fn test_is_file_path_discrimination() {
             reviews: false,
             since: None,
             project: None,
-            limit: 20,
+            limit: None,
             detail: false,
             no_detail: false,
             fields: None,
@@ -334,7 +334,7 @@ fn test_is_file_path_discrimination() {
             reviews: false,
             since: None,
             project: None,
-            limit: 20,
+            limit: None,
             detail: false,
             no_detail: false,
             fields: None,
@@ -358,7 +358,7 @@ fn test_is_file_path_discrimination() {
             reviews: true,
             since: None,
             project: None,
-            limit: 20,
+            limit: None,
             detail: false,
             no_detail: false,
             fields: None,
@@ -382,7 +382,7 @@ fn test_is_file_path_discrimination() {
             reviews: false,
             since: None,
             project: None,
-            limit: 20,
+            limit: None,
             detail: false,
             no_detail: false,
             fields: None,
@@ -406,7 +406,7 @@ fn test_is_file_path_discrimination() {
             reviews: false,
             since: None,
             project: None,
-            limit: 20,
+            limit: None,
             detail: false,
             no_detail: false,
             fields: None,
@@ -431,7 +431,7 @@ fn test_detail_rejected_outside_expert_mode() {
         reviews: false,
         since: None,
         project: None,
-        limit: 20,
+        limit: None,
         detail: true,
         no_detail: false,
         fields: None,
@@ -460,7 +460,7 @@ fn test_detail_allowed_in_expert_mode() {
         reviews: false,
         since: None,
         project: None,
-        limit: 20,
+        limit: None,
         detail: true,
         no_detail: false,
         fields: None,
@@ -3394,3 +3394,38 @@ fn active_excludes_closed_entity_discussions() {
     assert_eq!(result.discussions.len(), 2);
     assert_eq!(result.total_unresolved_in_window, 2);
 }
+
+// ─── Regression: Unlimited limit must not overflow ─────────────────────────
+
+#[test]
+fn workload_unlimited_limit_returns_results() {
+    // Regression test for integer overflow bug: when limit=usize::MAX, the
+    // expression (limit + 1) wrapped to 0, causing LIMIT 0 to return no rows.
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 1, 1, 100, "alice");
+    insert_assignee(&conn, 1, "alice");
+
+    // usize::MAX simulates the "unlimited" default when --limit is omitted
+    let result = query_workload(&conn, "alice", None, None, usize::MAX, false).unwrap();
+    assert!(
+        !result.assigned_issues.is_empty(),
+        "usize::MAX limit should return results, not overflow to LIMIT 0"
+    );
+}
+
+#[test]
+fn active_unlimited_limit_returns_results() {
+    // Same regression test for query_active
+    let conn = setup_test_db();
+    insert_project(&conn, 1, "group/repo");
+    insert_issue(&conn, 1, 1, 100, "alice");
+    insert_discussion(&conn, 1, 1, None, Some(1), true, false);
+    insert_note(&conn, 1, 1, 1, "alice");
+
+    let result = query_active(&conn, None, 0, usize::MAX, false).unwrap();
+    assert!(
+        !result.discussions.is_empty(),
+        "usize::MAX limit should return results, not overflow to LIMIT 0"
+    );
+}

src/cli/mod.rs

@@ -4,7 +4,7 @@ pub mod progress;
 pub mod render;
 pub mod robot;
 
-use clap::{Parser, Subcommand};
+use clap::{Args, Parser, Subcommand};
 use std::io::IsTerminal;
 
 #[derive(Parser)]
@@ -16,7 +16,9 @@ use std::io::IsTerminal;
   GITLAB_TOKEN       GitLab personal access token (or name set in config)
   LORE_ROBOT         Enable robot/JSON mode (non-empty, non-zero value)
   LORE_CONFIG_PATH   Override config file location
-  NO_COLOR           Disable color output (any non-empty value)")]
+  NO_COLOR           Disable color output (any non-empty value)
+  LORE_ICONS         Override icon set: nerd, unicode, or ascii
+  NERD_FONTS         Enable Nerd Font icons when set to a non-empty value")]
 pub struct Cli {
     /// Path to config file
     #[arg(short = 'c', long, global = true, help = "Path to config file")]
@@ -135,19 +137,35 @@ pub enum Commands {
     Count(CountArgs),
 
     /// Show sync state
-    #[command(visible_alias = "st")]
+    #[command(
+        visible_alias = "st",
+        after_help = "\x1b[1mExamples:\x1b[0m
+  lore status                             # Show last sync times per project
+  lore --robot status                     # JSON output for automation"
+    )]
     Status,
 
     /// Verify GitLab authentication
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore auth                               # Verify token and show user info
+  lore --robot auth                       # JSON output for automation")]
     Auth,
 
     /// Check environment health
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore doctor                             # Check config, token, database, Ollama
+  lore --robot doctor                     # JSON output for automation")]
     Doctor,
 
     /// Show version information
     Version,
 
     /// Initialize configuration and database
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore init                                                   # Interactive setup
+  lore init --force                                           # Overwrite existing config
+  lore --robot init --gitlab-url https://gitlab.com \\
+    --token-env-var GITLAB_TOKEN --projects group/repo        # Non-interactive setup")]
     Init {
         /// Skip overwrite confirmation
         #[arg(short = 'f', long)]
@@ -174,11 +192,14 @@ pub enum Commands {
         default_project: Option<String>,
     },
 
+    /// Back up local database (not yet implemented)
     #[command(hide = true)]
     Backup,
 
+    /// Reset local database (not yet implemented)
     #[command(hide = true)]
     Reset {
+        /// Skip confirmation prompt
         #[arg(short = 'y', long)]
         yes: bool,
     },
@@ -202,9 +223,15 @@ pub enum Commands {
     Sync(SyncArgs),
 
     /// Run pending database migrations
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore migrate                            # Apply pending migrations
+  lore --robot migrate                    # JSON output for automation")]
     Migrate,
 
     /// Quick health check: config, database, schema version
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore health                             # Quick pre-flight check (exit 0 = healthy)
+  lore --robot health                     # JSON output for automation")]
     Health,
 
     /// Machine-readable command manifest for agent self-discovery
@@ -234,6 +261,9 @@ pub enum Commands {
     /// People intelligence: experts, workload, active discussions, overlap
     Who(WhoArgs),
 
+    /// Personal work dashboard: open issues, authored/reviewing MRs, activity
+    Me(MeArgs),
+
     /// Show MRs that touched a file, with linked discussions
     #[command(name = "file-history")]
     FileHistory(FileHistoryArgs),
@@ -242,6 +272,10 @@ pub enum Commands {
     Trace(TraceArgs),
 
     /// Detect discussion divergence from original intent
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore drift issues 42                    # Check drift on issue #42
+  lore drift issues 42 --threshold 0.3    # Custom similarity threshold
+  lore --robot drift issues 42 -p group/repo  # JSON output, scoped to project")]
     Drift {
         /// Entity type (currently only "issues" supported)
         #[arg(value_parser = ["issues"])]
@@ -259,6 +293,45 @@ pub enum Commands {
         project: Option<String>,
     },
 
+    /// Find semantically related entities via vector search
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  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 --robot related issues 42 -n 5     # JSON output, limit 5 results")]
+    Related {
+        /// Entity type (issues, mrs) or free text query
+        query_or_type: String,
+
+        /// Entity IID (required when first arg is entity type)
+        iid: Option<i64>,
+
+        /// Maximum results
+        #[arg(short = 'n', long, default_value = "10")]
+        limit: usize,
+
+        /// Scope to project (fuzzy match)
+        #[arg(short, long)]
+        project: Option<String>,
+    },
+
+    /// Manage cron-based automatic syncing
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore cron install                       # Install cron job (every 8 minutes)
+  lore cron install --interval 15         # Custom interval
+  lore cron status                        # Check if cron is installed
+  lore cron uninstall                     # Remove cron job")]
+    Cron(CronArgs),
+
+    /// Manage stored GitLab token
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  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")]
+    Token(TokenArgs),
+
     #[command(hide = true)]
     List {
         #[arg(value_parser = ["issues", "mrs"])]
@@ -344,7 +417,7 @@ pub struct IssuesArgs {
     pub fields: Option<Vec<String>>,
 
     /// Filter by state (opened, closed, all)
-    #[arg(short = 's', long, help_heading = "Filters")]
+    #[arg(short = 's', long, help_heading = "Filters", value_parser = ["opened", "closed", "all"])]
     pub state: Option<String>,
 
     /// Filter by project path
@@ -438,7 +511,7 @@ pub struct MrsArgs {
     pub fields: Option<Vec<String>>,
 
     /// Filter by state (opened, merged, closed, locked, all)
-    #[arg(short = 's', long, help_heading = "Filters")]
+    #[arg(short = 's', long, help_heading = "Filters", value_parser = ["opened", "merged", "closed", "locked", "all"])]
     pub state: Option<String>,
 
     /// Filter by project path
@@ -535,15 +608,6 @@ pub struct NotesArgs {
     #[arg(long, help_heading = "Output", value_delimiter = ',')]
     pub fields: Option<Vec<String>>,
 
-    /// Output format (table, json, jsonl, csv)
-    #[arg(
-        long,
-        default_value = "table",
-        value_parser = ["table", "json", "jsonl", "csv"],
-        help_heading = "Output"
-    )]
-    pub format: String,
-
     /// Filter by author username
     #[arg(short = 'a', long, help_heading = "Filters")]
     pub author: Option<String>,
@@ -655,6 +719,11 @@ pub struct IngestArgs {
 }
 
 #[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore stats                              # Show document and index statistics
+  lore stats --check                      # Run integrity checks
+  lore stats --repair --dry-run           # Preview what repair would fix
+  lore --robot stats                      # JSON output for automation")]
 pub struct StatsArgs {
     /// Run integrity checks
     #[arg(long, overrides_with = "no_check")]
@@ -743,6 +812,10 @@ pub struct SearchArgs {
 }
 
 #[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore generate-docs                      # Generate docs for dirty entities
+  lore generate-docs --full               # Full rebuild of all documents
+  lore generate-docs --full -p group/repo # Full rebuild for one project")]
 pub struct GenerateDocsArgs {
     /// Full rebuild: seed all entities into dirty queue, then drain
     #[arg(long)]
@@ -759,7 +832,9 @@ pub struct GenerateDocsArgs {
   lore sync --no-embed                  # Skip embedding step
   lore sync --no-status                 # Skip work-item status enrichment
   lore sync --full --force              # Full re-sync, override stale lock
-  lore sync --dry-run                   # Preview what would change")]
+  lore sync --dry-run                   # Preview what would change
+  lore sync --issue 42 -p group/repo    # Surgically sync one issue
+  lore sync --mr 10 --mr 20 -p g/r     # Surgically sync two MRs")]
 pub struct SyncArgs {
     /// Reset cursors, fetch everything
     #[arg(long, overrides_with = "no_full")]
@@ -805,9 +880,33 @@ pub struct SyncArgs {
     /// Show detailed timing breakdown for sync stages
     #[arg(short = 't', long = "timings")]
     pub timings: bool,
+
+    /// Acquire file lock before syncing (skip if another sync is running)
+    #[arg(long)]
+    pub lock: bool,
+
+    /// Surgically sync specific issues by IID (repeatable, must be positive)
+    #[arg(long, value_parser = clap::value_parser!(u64).range(1..), action = clap::ArgAction::Append)]
+    pub issue: Vec<u64>,
+
+    /// Surgically sync specific merge requests by IID (repeatable, must be positive)
+    #[arg(long, value_parser = clap::value_parser!(u64).range(1..), action = clap::ArgAction::Append)]
+    pub mr: Vec<u64>,
+
+    /// Scope to a single project (required when --issue or --mr is used)
+    #[arg(short = 'p', long)]
+    pub project: Option<String>,
+
+    /// Validate remote entities exist without DB writes (preflight only)
+    #[arg(long)]
+    pub preflight_only: bool,
 }
 
 #[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore embed                              # Embed new/changed documents
+  lore embed --full                       # Re-embed all documents from scratch
+  lore embed --retry-failed               # Retry previously failed embeddings")]
 pub struct EmbedArgs {
     /// Re-embed all documents (clears existing embeddings first)
     #[arg(long, overrides_with = "no_full")]
@@ -926,15 +1025,14 @@ pub struct WhoArgs {
     #[arg(short = 'p', long, help_heading = "Filters")]
     pub project: Option<String>,
 
-    /// Maximum results per section (1..=500, bounded for output safety)
+    /// Maximum results per section (1..=500); omit for unlimited
     #[arg(
         short = 'n',
         long = "limit",
-        default_value = "20",
         value_parser = clap::value_parser!(u16).range(1..=500),
         help_heading = "Output"
     )]
-    pub limit: u16,
+    pub limit: Option<u16>,
 
     /// Select output fields (comma-separated, or 'minimal' preset; varies by mode)
     #[arg(long, help_heading = "Output", value_delimiter = ',')]
@@ -977,6 +1075,61 @@ pub struct WhoArgs {
     pub all_history: bool,
 }
 
+#[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore me                                 # Full dashboard (default project or all)
+  lore me --issues                        # Issues section only
+  lore me --mrs                           # MRs section only
+  lore me --activity                      # Activity feed only
+  lore me --all                           # All synced projects
+  lore me --since 2d                      # Activity window (default: 30d)
+  lore me --project group/repo            # Scope to one project
+  lore me --user jdoe                     # Override configured username")]
+pub struct MeArgs {
+    /// Show open issues section
+    #[arg(long, help_heading = "Sections")]
+    pub issues: bool,
+
+    /// Show authored + reviewing MRs section
+    #[arg(long, help_heading = "Sections")]
+    pub mrs: bool,
+
+    /// Show activity feed section
+    #[arg(long, help_heading = "Sections")]
+    pub activity: bool,
+
+    /// Activity window (e.g. 7d, 2w, 30d). Default: 30d. Only affects activity section.
+    #[arg(long, help_heading = "Filters")]
+    pub since: Option<String>,
+
+    /// Scope to a project (supports fuzzy matching)
+    #[arg(short = 'p', long, help_heading = "Filters", conflicts_with = "all")]
+    pub project: Option<String>,
+
+    /// Show all synced projects (overrides default_project)
+    #[arg(long, help_heading = "Filters", conflicts_with = "project")]
+    pub all: bool,
+
+    /// Override configured username
+    #[arg(long = "user", help_heading = "Filters")]
+    pub user: Option<String>,
+
+    /// Select output fields (comma-separated, or 'minimal' preset)
+    #[arg(long, help_heading = "Output", value_delimiter = ',')]
+    pub fields: Option<Vec<String>>,
+
+    /// Reset the since-last-check cursor (next run shows no new events)
+    #[arg(long, help_heading = "Output")]
+    pub reset_cursor: bool,
+}
+
+impl MeArgs {
+    /// Returns true if no section flags were passed (show all sections).
+    pub fn show_all_sections(&self) -> bool {
+        !self.issues && !self.mrs && !self.activity
+    }
+}
+
 #[derive(Parser)]
 #[command(after_help = "\x1b[1mExamples:\x1b[0m
   lore file-history src/main.rs                  # MRs that touched this file
@@ -1046,6 +1199,10 @@ pub struct TraceArgs {
 }
 
 #[derive(Parser)]
+#[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore count issues                       # Total issues in local database
+  lore count notes --for mr               # Notes on merge requests only
+  lore count discussions --for issue       # Discussions on issues only")]
 pub struct CountArgs {
     /// Entity type to count (issues, mrs, discussions, notes, events)
     #[arg(value_parser = ["issues", "mrs", "discussions", "notes", "events"])]
@@ -1055,3 +1212,48 @@ pub struct CountArgs {
     #[arg(short = 'f', long = "for", value_parser = ["issue", "mr"])]
     pub for_entity: Option<String>,
 }
+
+#[derive(Parser)]
+pub struct CronArgs {
+    #[command(subcommand)]
+    pub action: CronAction,
+}
+
+#[derive(Subcommand)]
+pub enum CronAction {
+    /// Install cron job for automatic syncing
+    Install {
+        /// Sync interval in minutes (default: 8)
+        #[arg(long, default_value = "8")]
+        interval: u32,
+    },
+
+    /// Remove cron job
+    Uninstall,
+
+    /// Show current cron configuration
+    Status,
+}
+
+#[derive(Args)]
+pub struct TokenArgs {
+    #[command(subcommand)]
+    pub action: TokenAction,
+}
+
+#[derive(Subcommand)]
+pub enum TokenAction {
+    /// Store a GitLab token in the config file
+    Set {
+        /// Token value (reads from stdin if omitted in non-interactive mode)
+        #[arg(long)]
+        token: Option<String>,
+    },
+
+    /// Show the current token (masked by default)
+    Show {
+        /// Show the full unmasked token
+        #[arg(long)]
+        unmask: bool,
+    },
+}

src/cli/render.rs

@@ -263,6 +263,11 @@ impl LoreRenderer {
             .expect("LoreRenderer::init must be called before get")
     }
 
+    /// Try to get the global renderer. Returns `None` if `init` hasn't been called.
+    pub fn try_get() -> Option<&'static LoreRenderer> {
+        RENDERER.get()
+    }
+
     /// Whether color output is enabled.
     pub fn colors_enabled(&self) -> bool {
         self.colors
@@ -448,6 +453,15 @@ impl Theme {
             Style::new()
         }
     }
+
+    /// Apply semantic color to a stage-completion icon glyph.
+    pub fn color_icon(icon: &str, has_errors: bool) -> String {
+        if has_errors {
+            Self::warning().render(icon)
+        } else {
+            Self::success().render(icon)
+        }
+    }
 }
 
 // ─── Shared Formatters ───────────────────────────────────────────────────────
@@ -518,6 +532,43 @@ pub fn format_datetime(ms: i64) -> String {
         .unwrap_or_else(|| "unknown".to_string())
 }
 
+/// Detect terminal width. Checks `COLUMNS` env, then stderr ioctl, falls back to 80.
+pub fn terminal_width() -> usize {
+    // 1. Explicit COLUMNS env (set by some shells, resized terminals)
+    if let Ok(val) = std::env::var("COLUMNS")
+        && let Ok(w) = val.parse::<usize>()
+        && w > 0
+    {
+        return w;
+    }
+
+    // 2. ioctl on stderr (works even when stdout is piped)
+    #[cfg(unix)]
+    {
+        use std::mem::MaybeUninit;
+        #[allow(non_camel_case_types)]
+        #[repr(C)]
+        struct winsize {
+            ws_row: libc::c_ushort,
+            ws_col: libc::c_ushort,
+            ws_xpixel: libc::c_ushort,
+            ws_ypixel: libc::c_ushort,
+        }
+        let mut ws = MaybeUninit::<winsize>::uninit();
+        // SAFETY: ioctl with TIOCGWINSZ writes into the winsize struct.
+        // stderr (fd 2) is used because stdout may be piped.
+        if unsafe { libc::ioctl(2, libc::TIOCGWINSZ, ws.as_mut_ptr()) } == 0 {
+            let ws = unsafe { ws.assume_init() };
+            let w = ws.ws_col as usize;
+            if w > 0 {
+                return w;
+            }
+        }
+    }
+
+    80
+}
+
 /// Truncate a string to `max` characters, appending "..." if truncated.
 pub fn truncate(s: &str, max: usize) -> String {
     if max < 4 {
@@ -531,6 +582,17 @@ pub fn truncate(s: &str, max: usize) -> String {
     }
 }
 
+/// Truncate and right-pad to exactly `width` visible characters.
+pub fn truncate_pad(s: &str, width: usize) -> String {
+    let t = truncate(s, width);
+    let count = t.chars().count();
+    if count < width {
+        format!("{t}{}", " ".repeat(width - count))
+    } else {
+        t
+    }
+}
+
 /// Word-wrap text to `width`, prepending `indent` to continuation lines.
 /// Returns a single string with embedded newlines.
 pub fn wrap_indent(text: &str, width: usize, indent: &str) -> String {
@@ -589,7 +651,10 @@ pub fn wrap_lines(text: &str, width: usize) -> Vec<String> {
 
 /// Render a section divider: `── Title ──────────────────────`
 pub fn section_divider(title: &str) -> String {
-    let rule_len = 40_usize.saturating_sub(title.len() + 4);
+    // prefix: 2 indent + 2 box-drawing + 1 space = 5
+    // suffix: 1 space + trailing box-drawing
+    let used = 5 + title.len() + 1;
+    let rule_len = terminal_width().saturating_sub(used);
     format!(
         "\n  {} {} {}",
         Theme::dim().render("\u{2500}\u{2500}"),
@@ -720,6 +785,8 @@ pub struct Table {
     rows: Vec<Vec<StyledCell>>,
     alignments: Vec<Align>,
     max_widths: Vec<Option<usize>>,
+    col_count: usize,
+    indent: usize,
 }
 
 impl Table {
@@ -730,9 +797,23 @@ impl Table {
     /// Set column headers.
     pub fn headers(mut self, h: &[&str]) -> Self {
         self.headers = h.iter().map(|s| (*s).to_string()).collect();
-        // Initialize alignments and max_widths to match column count
-        self.alignments.resize(self.headers.len(), Align::Left);
-        self.max_widths.resize(self.headers.len(), None);
+        self.col_count = self.headers.len();
+        self.alignments.resize(self.col_count, Align::Left);
+        self.max_widths.resize(self.col_count, None);
+        self
+    }
+
+    /// Set column count without headers (headerless table).
+    pub fn columns(mut self, n: usize) -> Self {
+        self.col_count = n;
+        self.alignments.resize(n, Align::Left);
+        self.max_widths.resize(n, None);
+        self
+    }
+
+    /// Set indent (number of spaces) prepended to each row.
+    pub fn indent(mut self, spaces: usize) -> Self {
+        self.indent = spaces;
         self
     }
 
@@ -759,15 +840,20 @@ impl Table {
 
     /// Render the table to a string.
     pub fn render(&self) -> String {
-        if self.headers.is_empty() {
+        let col_count = self.col_count;
+        if col_count == 0 {
             return String::new();
         }
 
-        let col_count = self.headers.len();
         let gap = "  "; // 2-space gap between columns
+        let indent_str = " ".repeat(self.indent);
 
-        // Compute column widths from content
-        let mut widths: Vec<usize> = self.headers.iter().map(|h| h.chars().count()).collect();
+        // Compute column widths from headers (if any) and all row cells
+        let mut widths: Vec<usize> = if self.headers.is_empty() {
+            vec![0; col_count]
+        } else {
+            self.headers.iter().map(|h| h.chars().count()).collect()
+        };
 
         for row in &self.rows {
             for (i, cell) in row.iter().enumerate() {
@@ -788,29 +874,32 @@ impl Table {
 
         let mut out = String::new();
 
-        // Header row (bold)
-        let header_parts: Vec<String> = self
-            .headers
-            .iter()
-            .enumerate()
-            .map(|(i, h)| {
-                let w = widths.get(i).copied().unwrap_or(0);
-                let text = truncate(h, w);
-                pad_cell(
-                    &text,
-                    w,
-                    self.alignments.get(i).copied().unwrap_or(Align::Left),
-                )
-            })
-            .collect();
-        out.push_str(&Theme::header().render(&header_parts.join(gap)));
-        out.push('\n');
+        // Header row + separator (only when headers are set)
+        if !self.headers.is_empty() {
+            let header_parts: Vec<String> = self
+                .headers
+                .iter()
+                .enumerate()
+                .map(|(i, h)| {
+                    let w = widths.get(i).copied().unwrap_or(0);
+                    let text = truncate(h, w);
+                    pad_cell(
+                        &text,
+                        w,
+                        self.alignments.get(i).copied().unwrap_or(Align::Left),
+                    )
+                })
+                .collect();
+            out.push_str(&indent_str);
+            out.push_str(&Theme::header().render(&header_parts.join(gap)));
+            out.push('\n');
 
-        // Separator
-        let total_width: usize =
-            widths.iter().sum::<usize>() + gap.len() * col_count.saturating_sub(1);
-        out.push_str(&Theme::dim().render(&"\u{2500}".repeat(total_width)));
-        out.push('\n');
+            let total_width: usize =
+                widths.iter().sum::<usize>() + gap.len() * col_count.saturating_sub(1);
+            out.push_str(&indent_str);
+            out.push_str(&Theme::dim().render(&"\u{2500}".repeat(total_width)));
+            out.push('\n');
+        }
 
         // Data rows
         for row in &self.rows {
@@ -842,6 +931,7 @@ impl Table {
                     parts.push(" ".repeat(w));
                 }
             }
+            out.push_str(&indent_str);
             out.push_str(&parts.join(gap));
             out.push('\n');
         }

src/cli/robot.rs

@@ -68,6 +68,14 @@ pub fn expand_fields_preset(fields: &[String], entity: &str) -> Vec<String> {
                 .iter()
                 .map(|s| (*s).to_string())
                 .collect(),
+            "me_items" => ["iid", "title", "attention_state", "updated_at_iso"]
+                .iter()
+                .map(|s| (*s).to_string())
+                .collect(),
+            "me_activity" => ["timestamp_iso", "event_type", "entity_iid", "actor"]
+                .iter()
+                .map(|s| (*s).to_string())
+                .collect(),
             _ => fields.to_vec(),
         }
     } else {

src/core/config.rs

@@ -12,6 +12,48 @@ pub struct GitLabConfig {
 
     #[serde(rename = "tokenEnvVar", default = "default_token_env_var")]
     pub token_env_var: String,
+
+    /// Optional stored token (env var takes priority when both are set).
+    #[serde(default)]
+    pub token: Option<String>,
+
+    /// Optional GitLab username for `lore me` personal dashboard.
+    #[serde(default)]
+    pub username: Option<String>,
+}
+
+impl GitLabConfig {
+    /// Resolve token with priority: env var > config file.
+    pub fn resolve_token(&self) -> Result<String> {
+        if let Ok(val) = std::env::var(&self.token_env_var)
+            && !val.trim().is_empty()
+        {
+            return Ok(val.trim().to_string());
+        }
+        if let Some(ref t) = self.token
+            && !t.trim().is_empty()
+        {
+            return Ok(t.trim().to_string());
+        }
+        Err(LoreError::TokenNotSet {
+            env_var: self.token_env_var.clone(),
+        })
+    }
+
+    /// Returns a human-readable label for where the token was found, or `None`.
+    pub fn token_source(&self) -> Option<&'static str> {
+        if let Ok(val) = std::env::var(&self.token_env_var)
+            && !val.trim().is_empty()
+        {
+            return Some("environment variable");
+        }
+        if let Some(ref t) = self.token
+            && !t.trim().is_empty()
+        {
+            return Some("config file");
+        }
+        None
+    }
 }
 
 fn default_token_env_var() -> String {
@@ -531,6 +573,8 @@ mod tests {
             gitlab: GitLabConfig {
                 base_url: "https://gitlab.example.com".to_string(),
                 token_env_var: "GITLAB_TOKEN".to_string(),
+                token: None,
+                username: None,
             },
             projects: vec![ProjectConfig {
                 path: "group/project".to_string(),
@@ -554,6 +598,8 @@ mod tests {
             gitlab: GitLabConfig {
                 base_url: "https://gitlab.example.com".to_string(),
                 token_env_var: "GITLAB_TOKEN".to_string(),
+                token: None,
+                username: None,
             },
             projects: vec![ProjectConfig {
                 path: "group/project".to_string(),
@@ -574,6 +620,8 @@ mod tests {
             gitlab: GitLabConfig {
                 base_url: "https://gitlab.example.com".to_string(),
                 token_env_var: "GITLAB_TOKEN".to_string(),
+                token: None,
+                username: None,
             },
             projects: vec![ProjectConfig {
                 path: "group/project".to_string(),
@@ -786,4 +834,120 @@ mod tests {
         };
         validate_scoring(&scoring).unwrap();
     }
+
+    // ── token_source / resolve_token ────────────────────────────────
+
+    /// Build a `GitLabConfig` that reads from the given unique env var name
+    /// so parallel tests never collide.
+    fn gitlab_cfg_with_env(env_var: &str, token: Option<&str>) -> GitLabConfig {
+        GitLabConfig {
+            base_url: "https://gitlab.example.com".to_string(),
+            token_env_var: env_var.to_string(),
+            token: token.map(ToString::to_string),
+            username: None,
+        }
+    }
+
+    #[test]
+    fn test_token_source_env_wins_over_config() {
+        const VAR: &str = "LORE_TEST_TS_ENV_WINS";
+        // SAFETY: unique var name, no other code reads it.
+        unsafe { std::env::set_var(VAR, "env-tok") };
+        let cfg = gitlab_cfg_with_env(VAR, Some("config-tok"));
+        assert_eq!(cfg.token_source(), Some("environment variable"));
+        unsafe { std::env::remove_var(VAR) };
+    }
+
+    #[test]
+    fn test_token_source_falls_back_to_config() {
+        const VAR: &str = "LORE_TEST_TS_FALLBACK";
+        unsafe { std::env::remove_var(VAR) };
+        let cfg = gitlab_cfg_with_env(VAR, Some("config-tok"));
+        assert_eq!(cfg.token_source(), Some("config file"));
+    }
+
+    #[test]
+    fn test_token_source_none_when_both_absent() {
+        const VAR: &str = "LORE_TEST_TS_NONE";
+        unsafe { std::env::remove_var(VAR) };
+        let cfg = gitlab_cfg_with_env(VAR, None);
+        assert_eq!(cfg.token_source(), None);
+    }
+
+    #[test]
+    fn test_token_source_ignores_whitespace_only_env() {
+        const VAR: &str = "LORE_TEST_TS_WS_ENV";
+        unsafe { std::env::set_var(VAR, "   ") };
+        let cfg = gitlab_cfg_with_env(VAR, Some("real"));
+        assert_eq!(cfg.token_source(), Some("config file"));
+        unsafe { std::env::remove_var(VAR) };
+    }
+
+    #[test]
+    fn test_token_source_ignores_whitespace_only_config() {
+        const VAR: &str = "LORE_TEST_TS_WS_CFG";
+        unsafe { std::env::remove_var(VAR) };
+        let cfg = gitlab_cfg_with_env(VAR, Some("  \t  "));
+        assert_eq!(cfg.token_source(), None);
+    }
+
+    #[test]
+    fn test_resolve_token_env_wins_over_config() {
+        const VAR: &str = "LORE_TEST_RT_ENV_WINS";
+        unsafe { std::env::set_var(VAR, "  env-tok  ") };
+        let cfg = gitlab_cfg_with_env(VAR, Some("config-tok"));
+        assert_eq!(cfg.resolve_token().unwrap(), "env-tok");
+        unsafe { std::env::remove_var(VAR) };
+    }
+
+    #[test]
+    fn test_resolve_token_config_fallback() {
+        const VAR: &str = "LORE_TEST_RT_FALLBACK";
+        unsafe { std::env::remove_var(VAR) };
+        let cfg = gitlab_cfg_with_env(VAR, Some("  config-tok  "));
+        assert_eq!(cfg.resolve_token().unwrap(), "config-tok");
+    }
+
+    #[test]
+    fn test_resolve_token_err_when_both_absent() {
+        const VAR: &str = "LORE_TEST_RT_NONE";
+        unsafe { std::env::remove_var(VAR) };
+        let cfg = gitlab_cfg_with_env(VAR, None);
+        assert!(cfg.resolve_token().is_err());
+    }
+
+    // ── gitlab.username ─────────────────────────────────────────────
+
+    #[test]
+    fn test_config_loads_with_username() {
+        let dir = TempDir::new().unwrap();
+        let path = dir.path().join("config.json");
+        let config = r#"{
+  "gitlab": {
+    "baseUrl": "https://gitlab.example.com",
+    "tokenEnvVar": "GITLAB_TOKEN",
+    "username": "jdoe"
+  },
+  "projects": [{ "path": "group/project" }]
+}"#;
+        fs::write(&path, config).unwrap();
+        let cfg = Config::load_from_path(&path).unwrap();
+        assert_eq!(cfg.gitlab.username.as_deref(), Some("jdoe"));
+    }
+
+    #[test]
+    fn test_config_loads_without_username() {
+        let dir = TempDir::new().unwrap();
+        let path = dir.path().join("config.json");
+        let config = r#"{
+  "gitlab": {
+    "baseUrl": "https://gitlab.example.com",
+    "tokenEnvVar": "GITLAB_TOKEN"
+  },
+  "projects": [{ "path": "group/project" }]
+}"#;
+        fs::write(&path, config).unwrap();
+        let cfg = Config::load_from_path(&path).unwrap();
+        assert_eq!(cfg.gitlab.username, None);
+    }
 }

src/core/cron.rs

@@ -0,0 +1,369 @@
+use std::fs::{self, File};
+use std::io::{self, Write};
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use serde::Serialize;
+
+use super::error::{LoreError, Result};
+use super::paths::get_data_dir;
+
+const CRON_TAG: &str = "# lore-sync";
+
+// ── File-based sync lock (fcntl F_SETLK) ──
+
+/// RAII guard that holds an `fcntl` write lock on a file.
+/// The lock is released when the guard is dropped.
+pub struct SyncLockGuard {
+    _file: File,
+}
+
+/// Try to acquire an exclusive file lock (non-blocking).
+///
+/// Returns `Ok(Some(guard))` if the lock was acquired, `Ok(None)` if another
+/// process holds it, or `Err` on I/O failure.
+#[cfg(unix)]
+pub fn acquire_sync_lock() -> Result<Option<SyncLockGuard>> {
+    acquire_sync_lock_at(&lock_path())
+}
+
+fn lock_path() -> PathBuf {
+    get_data_dir().join("sync.lock")
+}
+
+#[cfg(unix)]
+fn acquire_sync_lock_at(path: &Path) -> Result<Option<SyncLockGuard>> {
+    use std::os::unix::io::AsRawFd;
+
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+
+    let file = File::options()
+        .create(true)
+        .truncate(false)
+        .write(true)
+        .open(path)?;
+
+    let fd = file.as_raw_fd();
+
+    // SAFETY: zeroed memory is valid for libc::flock (all-zero is a valid
+    // representation on every Unix platform). We then set only the fields we need.
+    let mut flock = unsafe { std::mem::zeroed::<libc::flock>() };
+    flock.l_type = libc::F_WRLCK as libc::c_short;
+    flock.l_whence = libc::SEEK_SET as libc::c_short;
+
+    // SAFETY: fd is a valid open file descriptor; flock is stack-allocated.
+    let rc = unsafe { libc::fcntl(fd, libc::F_SETLK, &mut flock) };
+    if rc == -1 {
+        let err = io::Error::last_os_error();
+        if err.kind() == io::ErrorKind::WouldBlock
+            || err.raw_os_error() == Some(libc::EAGAIN)
+            || err.raw_os_error() == Some(libc::EACCES)
+        {
+            return Ok(None);
+        }
+        return Err(LoreError::Io(err));
+    }
+
+    Ok(Some(SyncLockGuard { _file: file }))
+}
+
+// ── Crontab management ──
+
+/// The crontab entry that `lore cron install` writes.
+///
+/// Paths are single-quoted so spaces in binary or log paths don't break
+/// the cron expression.
+pub fn build_cron_entry(interval_minutes: u32) -> String {
+    let binary = std::env::current_exe()
+        .unwrap_or_else(|_| PathBuf::from("lore"))
+        .display()
+        .to_string();
+    let log_path = sync_log_path();
+    format!(
+        "*/{interval_minutes} * * * * '{binary}' sync -q --lock >> '{log}' 2>&1 {CRON_TAG}",
+        log = log_path.display(),
+    )
+}
+
+/// Path where cron-triggered sync output is appended.
+pub fn sync_log_path() -> PathBuf {
+    get_data_dir().join("sync.log")
+}
+
+/// Read the current user crontab. Returns empty string when no crontab exists.
+fn read_crontab() -> Result<String> {
+    let output = Command::new("crontab").arg("-l").output()?;
+    if output.status.success() {
+        Ok(String::from_utf8_lossy(&output.stdout).into_owned())
+    } else {
+        // exit 1 with "no crontab for <user>" is normal — treat as empty
+        Ok(String::new())
+    }
+}
+
+/// Write a full crontab string. Replaces the current crontab entirely.
+fn write_crontab(content: &str) -> Result<()> {
+    let mut child = Command::new("crontab")
+        .arg("-")
+        .stdin(std::process::Stdio::piped())
+        .spawn()?;
+    if let Some(ref mut stdin) = child.stdin {
+        stdin.write_all(content.as_bytes())?;
+    }
+    let status = child.wait()?;
+    if !status.success() {
+        return Err(LoreError::Other(format!(
+            "crontab exited with status {status}"
+        )));
+    }
+    Ok(())
+}
+
+/// Install (or update) the lore-sync crontab entry.
+pub fn install_cron(interval_minutes: u32) -> Result<CronInstallResult> {
+    let entry = build_cron_entry(interval_minutes);
+
+    let existing = read_crontab()?;
+    let replaced = existing.contains(CRON_TAG);
+
+    // Strip ALL old lore-sync lines first, then append one new entry.
+    // This is idempotent even if the crontab somehow has duplicate tagged lines.
+    let mut filtered: String = existing
+        .lines()
+        .filter(|line| !line.contains(CRON_TAG))
+        .collect::<Vec<_>>()
+        .join("\n");
+    if !filtered.is_empty() && !filtered.ends_with('\n') {
+        filtered.push('\n');
+    }
+    filtered.push_str(&entry);
+    filtered.push('\n');
+
+    write_crontab(&filtered)?;
+
+    Ok(CronInstallResult {
+        entry,
+        interval_minutes,
+        log_path: sync_log_path(),
+        replaced,
+    })
+}
+
+/// Remove the lore-sync crontab entry.
+pub fn uninstall_cron() -> Result<CronUninstallResult> {
+    let existing = read_crontab()?;
+    if !existing.contains(CRON_TAG) {
+        return Ok(CronUninstallResult {
+            was_installed: false,
+        });
+    }
+
+    let new_crontab: String = existing
+        .lines()
+        .filter(|line| !line.contains(CRON_TAG))
+        .collect::<Vec<_>>()
+        .join("\n")
+        + "\n";
+
+    // If the crontab would be empty (only whitespace), remove it entirely
+    if new_crontab.trim().is_empty() {
+        let status = Command::new("crontab").arg("-r").status()?;
+        if !status.success() {
+            return Err(LoreError::Other("crontab -r failed".to_string()));
+        }
+    } else {
+        write_crontab(&new_crontab)?;
+    }
+
+    Ok(CronUninstallResult {
+        was_installed: true,
+    })
+}
+
+/// Inspect the current crontab for a lore-sync entry.
+pub fn cron_status() -> Result<CronStatusResult> {
+    let existing = read_crontab()?;
+    let lore_line = existing.lines().find(|l| l.contains(CRON_TAG));
+
+    match lore_line {
+        Some(line) => {
+            let interval = parse_interval(line);
+            let binary_path = parse_binary_path(line);
+
+            let current_exe = std::env::current_exe()
+                .ok()
+                .map(|p| p.display().to_string());
+            let binary_mismatch = current_exe
+                .as_ref()
+                .zip(binary_path.as_ref())
+                .is_some_and(|(current, cron)| current != cron);
+
+            Ok(CronStatusResult {
+                installed: true,
+                interval_minutes: interval,
+                binary_path,
+                current_binary: current_exe,
+                binary_mismatch,
+                log_path: Some(sync_log_path()),
+                cron_entry: Some(line.to_string()),
+            })
+        }
+        None => Ok(CronStatusResult {
+            installed: false,
+            interval_minutes: None,
+            binary_path: None,
+            current_binary: std::env::current_exe()
+                .ok()
+                .map(|p| p.display().to_string()),
+            binary_mismatch: false,
+            log_path: None,
+            cron_entry: None,
+        }),
+    }
+}
+
+/// Parse the interval from a cron expression like `*/8 * * * * ...`
+fn parse_interval(line: &str) -> Option<u32> {
+    let first_field = line.split_whitespace().next()?;
+    if let Some(n) = first_field.strip_prefix("*/") {
+        n.parse().ok()
+    } else {
+        None
+    }
+}
+
+/// Parse the binary path from the cron entry after the 5 time fields.
+///
+/// Handles both quoted (`'/path with spaces/lore'`) and unquoted paths.
+/// We skip the time fields manually to avoid `split_whitespace` breaking
+/// on spaces inside single-quoted paths.
+fn parse_binary_path(line: &str) -> Option<String> {
+    // Skip the 5 cron time fields (min hour dom month dow).
+    // These never contain spaces, so whitespace-splitting is safe here.
+    let mut rest = line;
+    for _ in 0..5 {
+        rest = rest.trim_start();
+        let end = rest.find(char::is_whitespace)?;
+        rest = &rest[end..];
+    }
+    rest = rest.trim_start();
+
+    // The command starts here — it may be single-quoted.
+    if let Some(after_quote) = rest.strip_prefix('\'') {
+        let end = after_quote.find('\'')?;
+        Some(after_quote[..end].to_string())
+    } else {
+        let end = rest.find(char::is_whitespace).unwrap_or(rest.len());
+        Some(rest[..end].to_string())
+    }
+}
+
+// ── Result types ──
+
+#[derive(Serialize)]
+pub struct CronInstallResult {
+    pub entry: String,
+    pub interval_minutes: u32,
+    pub log_path: PathBuf,
+    pub replaced: bool,
+}
+
+#[derive(Serialize)]
+pub struct CronUninstallResult {
+    pub was_installed: bool,
+}
+
+#[derive(Serialize)]
+pub struct CronStatusResult {
+    pub installed: bool,
+    pub interval_minutes: Option<u32>,
+    pub binary_path: Option<String>,
+    pub current_binary: Option<String>,
+    pub binary_mismatch: bool,
+    pub log_path: Option<PathBuf>,
+    pub cron_entry: Option<String>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn build_cron_entry_formats_correctly() {
+        let entry = build_cron_entry(8);
+        assert!(entry.starts_with("*/8 * * * * "));
+        assert!(entry.contains("sync -q --lock"));
+        assert!(entry.ends_with(CRON_TAG));
+    }
+
+    #[test]
+    fn parse_interval_extracts_number() {
+        assert_eq!(parse_interval("*/8 * * * * /usr/bin/lore sync"), Some(8));
+        assert_eq!(parse_interval("*/15 * * * * /usr/bin/lore sync"), Some(15));
+        assert_eq!(parse_interval("0 * * * * /usr/bin/lore sync"), None);
+    }
+
+    #[test]
+    fn parse_binary_path_extracts_sixth_field() {
+        // Unquoted path
+        assert_eq!(
+            parse_binary_path(
+                "*/8 * * * * /usr/local/bin/lore sync -q --lock >> /tmp/log 2>&1 # lore-sync"
+            ),
+            Some("/usr/local/bin/lore".to_string())
+        );
+        // Single-quoted path without spaces
+        assert_eq!(
+            parse_binary_path(
+                "*/8 * * * * '/usr/local/bin/lore' sync -q --lock >> '/tmp/log' 2>&1 # lore-sync"
+            ),
+            Some("/usr/local/bin/lore".to_string())
+        );
+        // Single-quoted path WITH spaces (common on macOS)
+        assert_eq!(
+            parse_binary_path(
+                "*/8 * * * * '/Users/Taylor Eernisse/.cargo/bin/lore' sync -q --lock >> '/tmp/log' 2>&1 # lore-sync"
+            ),
+            Some("/Users/Taylor Eernisse/.cargo/bin/lore".to_string())
+        );
+    }
+
+    #[test]
+    fn sync_lock_at_nonexistent_dir_creates_parents() {
+        let dir = tempfile::tempdir().unwrap();
+        let lock_file = dir.path().join("nested").join("deep").join("sync.lock");
+        let guard = acquire_sync_lock_at(&lock_file).unwrap();
+        assert!(guard.is_some());
+        assert!(lock_file.exists());
+    }
+
+    #[test]
+    fn sync_lock_is_exclusive_across_processes() {
+        // POSIX fcntl locks are per-process, so same-process re-lock always
+        // succeeds. We verify cross-process exclusion using a Python child
+        // that attempts the same fcntl F_SETLK.
+        let dir = tempfile::tempdir().unwrap();
+        let lock_file = dir.path().join("sync.lock");
+        let _guard = acquire_sync_lock_at(&lock_file).unwrap().unwrap();
+
+        let script = r#"
+import fcntl, struct, sys
+fd = open(sys.argv[1], "w")
+try:
+    fcntl.fcntl(fd, fcntl.F_SETLK, struct.pack("hhllhh", fcntl.F_WRLCK, 0, 0, 0, 0, 0))
+    sys.exit(0)
+except (IOError, OSError):
+    sys.exit(1)
+"#;
+        let status = std::process::Command::new("python3")
+            .args(["-c", script, &lock_file.display().to_string()])
+            .status()
+            .unwrap();
+        assert!(
+            !status.success(),
+            "child process should fail to acquire fcntl lock held by parent"
+        );
+    }
+}

src/core/cursor.rs

@@ -0,0 +1,152 @@
+// ─── Me Cursor Persistence ──────────────────────────────────────────────────
+//
+// File-based cursor for the "since last check" section of `lore me`.
+// Stores per-user timestamps in ~/.local/share/lore/me_cursor_<username>.json.
+
+use std::io;
+use std::io::Write;
+
+use serde::{Deserialize, Serialize};
+
+use super::paths::get_cursor_path;
+
+#[derive(Serialize, Deserialize)]
+struct CursorFile {
+    last_check_ms: i64,
+}
+
+/// Read the last-check cursor. Returns `None` if the file doesn't exist or is corrupt.
+pub fn read_cursor(username: &str) -> Option<i64> {
+    let path = get_cursor_path(username);
+    let data = std::fs::read_to_string(path).ok()?;
+    let cursor: CursorFile = serde_json::from_str(&data).ok()?;
+    Some(cursor.last_check_ms)
+}
+
+/// Write the last-check cursor atomically.
+pub fn write_cursor(username: &str, timestamp_ms: i64) -> io::Result<()> {
+    let path = get_cursor_path(username);
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+        let cursor = CursorFile {
+            last_check_ms: timestamp_ms,
+        };
+        let json = serde_json::to_string(&cursor).map_err(io::Error::other)?;
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0);
+        let file_name = path
+            .file_name()
+            .and_then(|name| name.to_str())
+            .unwrap_or("me_cursor.json");
+        let temp_path = parent.join(format!(".{file_name}.{nonce}.tmp"));
+        {
+            let mut temp_file = std::fs::File::create(&temp_path)?;
+            temp_file.write_all(json.as_bytes())?;
+            temp_file.sync_all()?;
+        }
+        std::fs::rename(&temp_path, &path)?;
+        return Ok(());
+    }
+
+    Err(io::Error::new(
+        io::ErrorKind::InvalidInput,
+        "cursor path has no parent directory",
+    ))
+}
+
+/// Reset the cursor by deleting the file. No-op if it doesn't exist.
+pub fn reset_cursor(username: &str) -> io::Result<()> {
+    let path = get_cursor_path(username);
+    match std::fs::remove_file(path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(e),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::{Mutex, OnceLock};
+
+    fn env_lock() -> &'static Mutex<()> {
+        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+        LOCK.get_or_init(|| Mutex::new(()))
+    }
+
+    fn with_temp_xdg_data_home<T>(f: impl FnOnce() -> T) -> T {
+        let _guard = env_lock().lock().unwrap();
+        let previous = std::env::var_os("XDG_DATA_HOME");
+        let dir = tempfile::tempdir().unwrap();
+        // SAFETY: test-only scoped env override.
+        unsafe { std::env::set_var("XDG_DATA_HOME", dir.path()) };
+        let result = f();
+        match previous {
+            Some(value) => {
+                // SAFETY: restoring prior environment for test isolation.
+                unsafe { std::env::set_var("XDG_DATA_HOME", value) };
+            }
+            None => {
+                // SAFETY: restoring prior environment for test isolation.
+                unsafe { std::env::remove_var("XDG_DATA_HOME") };
+            }
+        }
+        result
+    }
+
+    #[test]
+    fn read_cursor_returns_none_when_missing() {
+        with_temp_xdg_data_home(|| {
+            assert_eq!(read_cursor("alice"), None);
+        });
+    }
+
+    #[test]
+    fn cursor_roundtrip() {
+        with_temp_xdg_data_home(|| {
+            write_cursor("alice", 1_700_000_000_000).unwrap();
+            assert_eq!(read_cursor("alice"), Some(1_700_000_000_000));
+        });
+    }
+
+    #[test]
+    fn cursor_isolated_per_user() {
+        with_temp_xdg_data_home(|| {
+            write_cursor("alice", 100).unwrap();
+            write_cursor("bob", 200).unwrap();
+            assert_eq!(read_cursor("alice"), Some(100));
+            assert_eq!(read_cursor("bob"), Some(200));
+        });
+    }
+
+    #[test]
+    fn reset_cursor_only_affects_target_user() {
+        with_temp_xdg_data_home(|| {
+            write_cursor("alice", 100).unwrap();
+            write_cursor("bob", 200).unwrap();
+            reset_cursor("alice").unwrap();
+            assert_eq!(read_cursor("alice"), None);
+            assert_eq!(read_cursor("bob"), Some(200));
+        });
+    }
+
+    #[test]
+    fn cursor_write_keeps_valid_json() {
+        with_temp_xdg_data_home(|| {
+            write_cursor("alice", 111).unwrap();
+            write_cursor("alice", 222).unwrap();
+            let data = std::fs::read_to_string(get_cursor_path("alice")).unwrap();
+            let parsed: CursorFile = serde_json::from_str(&data).unwrap();
+            assert_eq!(parsed.last_check_ms, 222);
+        });
+    }
+
+    #[test]
+    fn parse_corrupt_json_returns_none() {
+        let bad_json = "not json at all";
+        let parsed: Option<CursorFile> = serde_json::from_str(bad_json).ok();
+        assert!(parsed.is_none());
+    }
+}

src/core/db.rs

@@ -89,6 +89,14 @@ const MIGRATIONS: &[(&str, &str)] = &[
         "026",
         include_str!("../../migrations/026_scoring_indexes.sql"),
     ),
+    (
+        "027",
+        include_str!("../../migrations/027_surgical_sync_runs.sql"),
+    ),
+    (
+        "028",
+        include_str!("../../migrations/028_discussions_mr_fk.sql"),
+    ),
 ];
 
 pub fn create_connection(db_path: &Path) -> Result<Connection> {
@@ -126,21 +134,20 @@ pub fn create_connection(db_path: &Path) -> Result<Connection> {
 }
 
 pub fn run_migrations(conn: &Connection) -> Result<()> {
-    let has_version_table: bool = conn
-        .query_row(
-            "SELECT COUNT(*) > 0 FROM sqlite_master WHERE type='table' AND name='schema_version'",
-            [],
-            |row| row.get(0),
-        )
-        .unwrap_or(false);
+    // Note: sqlite_master always exists, so errors here indicate real DB problems
+    // (corruption, locked, etc.) - we must not silently treat them as "fresh DB"
+    let has_version_table: bool = conn.query_row(
+        "SELECT COUNT(*) > 0 FROM sqlite_master WHERE type='table' AND name='schema_version'",
+        [],
+        |row| row.get(0),
+    )?;
 
     let current_version: i32 = if has_version_table {
         conn.query_row(
             "SELECT COALESCE(MAX(version), 0) FROM schema_version",
             [],
             |row| row.get(0),
-        )
-        .unwrap_or(0)
+        )?
     } else {
         0
     };

src/core/error.rs

@@ -21,6 +21,7 @@ pub enum ErrorCode {
     EmbeddingFailed,
     NotFound,
     Ambiguous,
+    SurgicalPreflightFailed,
 }
 
 impl std::fmt::Display for ErrorCode {
@@ -44,6 +45,7 @@ impl std::fmt::Display for ErrorCode {
             Self::EmbeddingFailed => "EMBEDDING_FAILED",
             Self::NotFound => "NOT_FOUND",
             Self::Ambiguous => "AMBIGUOUS",
+            Self::SurgicalPreflightFailed => "SURGICAL_PREFLIGHT_FAILED",
         };
         write!(f, "{code}")
     }
@@ -70,6 +72,9 @@ impl ErrorCode {
             Self::EmbeddingFailed => 16,
             Self::NotFound => 17,
             Self::Ambiguous => 18,
+            // Shares exit code 6 with GitLabNotFound — same semantic category (resource not found).
+            // Robot consumers distinguish via ErrorCode string, not exit code.
+            Self::SurgicalPreflightFailed => 6,
         }
     }
 }
@@ -111,7 +116,7 @@ pub enum LoreError {
         source: Option<rusqlite::Error>,
     },
 
-    #[error("GitLab token not set. Export {env_var} environment variable.")]
+    #[error("GitLab token not set. Run 'lore token set' or export {env_var}.")]
     TokenNotSet { env_var: String },
 
     #[error("Database error: {0}")]
@@ -153,6 +158,14 @@ pub enum LoreError {
 
     #[error("No embeddings found. Run: lore embed")]
     EmbeddingsNotBuilt,
+
+    #[error("Surgical preflight failed for {entity_type} !{iid} in {project}: {reason}")]
+    SurgicalPreflightFailed {
+        entity_type: String,
+        iid: u64,
+        project: String,
+        reason: String,
+    },
 }
 
 impl LoreError {
@@ -167,7 +180,13 @@ impl LoreError {
             Self::DatabaseLocked { .. } => ErrorCode::DatabaseLocked,
             Self::MigrationFailed { .. } => ErrorCode::MigrationFailed,
             Self::TokenNotSet { .. } => ErrorCode::TokenNotSet,
-            Self::Database(_) => ErrorCode::DatabaseError,
+            Self::Database(e) => {
+                if e.sqlite_error_code() == Some(rusqlite::ErrorCode::DatabaseBusy) {
+                    ErrorCode::DatabaseLocked
+                } else {
+                    ErrorCode::DatabaseError
+                }
+            }
             Self::Http(_) => ErrorCode::GitLabNetworkError,
             Self::Json(_) => ErrorCode::InternalError,
             Self::Io(_) => ErrorCode::IoError,
@@ -179,6 +198,7 @@ impl LoreError {
             Self::OllamaModelNotFound { .. } => ErrorCode::OllamaModelNotFound,
             Self::EmbeddingFailed { .. } => ErrorCode::EmbeddingFailed,
             Self::EmbeddingsNotBuilt => ErrorCode::EmbeddingFailed,
+            Self::SurgicalPreflightFailed { .. } => ErrorCode::SurgicalPreflightFailed,
         }
     }
 
@@ -204,14 +224,20 @@ impl LoreError {
                 "Wait for other sync to complete or use --force.\n\n  Example:\n    lore ingest --force\n    lore ingest issues --force",
             ),
             Self::MigrationFailed { .. } => Some(
-                "Check database file permissions or reset with 'lore reset'.\n\n  Example:\n    lore migrate\n    lore reset --yes",
+                "Check database file permissions and try again.\n\n  Example:\n    lore migrate\n    lore doctor",
             ),
             Self::TokenNotSet { .. } => Some(
-                "Export the token to your shell:\n\n  export GITLAB_TOKEN=glpat-xxxxxxxxxxxx\n\n  Your token needs the read_api scope.",
-            ),
-            Self::Database(_) => Some(
-                "Check database file permissions or reset with 'lore reset'.\n\n  Example:\n    lore doctor\n    lore reset --yes",
+                "Set your token:\n\n  lore token set\n\n  Or export to your shell:\n\n  export GITLAB_TOKEN=glpat-xxxxxxxxxxxx\n\n  Your token needs the read_api scope.",
             ),
+            Self::Database(e) => {
+                if e.sqlite_error_code() == Some(rusqlite::ErrorCode::DatabaseBusy) {
+                    Some(
+                        "Another process has the database locked. Wait a moment and retry.\n\n  Common causes:\n    - A cron sync is running (lore cron status)\n    - Another lore command is active",
+                    )
+                } else {
+                    Some("Check database file permissions.\n\n  Example:\n    lore doctor")
+                }
+            }
             Self::Http(_) => Some("Check network connection"),
             Self::NotFound(_) => {
                 Some("Verify the entity exists.\n\n  Example:\n    lore issues\n    lore mrs")
@@ -227,6 +253,9 @@ impl LoreError {
                 Some("Check Ollama logs or retry with 'lore embed --retry-failed'")
             }
             Self::EmbeddingsNotBuilt => Some("Generate embeddings first: lore embed"),
+            Self::SurgicalPreflightFailed { .. } => Some(
+                "Verify the IID exists in the project and you have access.\n\n  Example:\n    lore issues -p <project>\n    lore mrs -p <project>",
+            ),
             Self::Json(_) | Self::Io(_) | Self::Transform(_) | Self::Other(_) => None,
         }
     }
@@ -246,14 +275,22 @@ impl LoreError {
             Self::GitLabAuthFailed => {
                 vec!["export GITLAB_TOKEN=glpat-xxx", "lore auth"]
             }
-            Self::TokenNotSet { .. } => vec!["export GITLAB_TOKEN=glpat-xxx"],
+            Self::TokenNotSet { .. } => vec!["lore token set", "export GITLAB_TOKEN=glpat-xxx"],
             Self::OllamaUnavailable { .. } => vec!["ollama serve"],
             Self::OllamaModelNotFound { .. } => vec!["ollama pull nomic-embed-text"],
             Self::DatabaseLocked { .. } => vec!["lore ingest --force"],
+            Self::Database(e)
+                if e.sqlite_error_code() == Some(rusqlite::ErrorCode::DatabaseBusy) =>
+            {
+                vec!["lore cron status"]
+            }
             Self::EmbeddingsNotBuilt => vec!["lore embed"],
             Self::EmbeddingFailed { .. } => vec!["lore embed --retry-failed"],
             Self::MigrationFailed { .. } => vec!["lore migrate"],
             Self::GitLabNetworkError { .. } => vec!["lore doctor"],
+            Self::SurgicalPreflightFailed { .. } => {
+                vec!["lore issues -p <project>", "lore mrs -p <project>"]
+            }
             _ => vec![],
         }
     }
@@ -293,3 +330,40 @@ impl From<&LoreError> for RobotErrorOutput {
 }
 
 pub type Result<T> = std::result::Result<T, LoreError>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn surgical_preflight_failed_display() {
+        let err = LoreError::SurgicalPreflightFailed {
+            entity_type: "issue".to_string(),
+            iid: 42,
+            project: "group/repo".to_string(),
+            reason: "not found on GitLab".to_string(),
+        };
+        let msg = err.to_string();
+        assert!(msg.contains("issue"), "missing entity_type: {msg}");
+        assert!(msg.contains("42"), "missing iid: {msg}");
+        assert!(msg.contains("group/repo"), "missing project: {msg}");
+        assert!(msg.contains("not found on GitLab"), "missing reason: {msg}");
+    }
+
+    #[test]
+    fn surgical_preflight_failed_error_code() {
+        let code = ErrorCode::SurgicalPreflightFailed;
+        assert_eq!(code.exit_code(), 6);
+    }
+
+    #[test]
+    fn surgical_preflight_failed_code_mapping() {
+        let err = LoreError::SurgicalPreflightFailed {
+            entity_type: "merge_request".to_string(),
+            iid: 99,
+            project: "ns/proj".to_string(),
+            reason: "404".to_string(),
+        };
+        assert_eq!(err.code(), ErrorCode::SurgicalPreflightFailed);
+    }
+}

src/core/file_history.rs

@@ -44,15 +44,13 @@ pub fn resolve_rename_chain(
         let mut fwd_stmt = conn.prepare_cached(forward_sql)?;
         let forward: Vec<String> = fwd_stmt
             .query_map(rusqlite::params![project_id, &current], |row| row.get(0))?
-            .filter_map(std::result::Result::ok)
-            .collect();
+            .collect::<std::result::Result<Vec<_>, _>>()?;
 
         // Backward: current was the new name -> discover old names
         let mut bwd_stmt = conn.prepare_cached(backward_sql)?;
         let backward: Vec<String> = bwd_stmt
             .query_map(rusqlite::params![project_id, &current], |row| row.get(0))?
-            .filter_map(std::result::Result::ok)
-            .collect();
+            .collect::<std::result::Result<Vec<_>, _>>()?;
 
         for discovered in forward.into_iter().chain(backward) {
             if visited.insert(discovered.clone()) {

src/core/mod.rs

@@ -1,5 +1,8 @@
 pub mod backoff;
 pub mod config;
+#[cfg(unix)]
+pub mod cron;
+pub mod cursor;
 pub mod db;
 pub mod dependent_queue;
 pub mod error;

src/core/path_resolver.rs

@@ -294,8 +294,7 @@ fn try_resolve_rename_ambiguity(
 
     let old_paths: Vec<String> = stmt
         .query_map(param_refs.as_slice(), |row| row.get(0))?
-        .filter_map(std::result::Result::ok)
-        .collect();
+        .collect::<std::result::Result<Vec<_>, _>>()?;
 
     // The newest path is a candidate that is NOT an old_path in any intra-chain rename.
     let newest = candidates.iter().find(|c| !old_paths.contains(c));

src/core/paths.rs

@@ -40,6 +40,20 @@ pub fn get_log_dir(config_override: Option<&str>) -> PathBuf {
     get_data_dir().join("logs")
 }
 
+pub fn get_cursor_path(username: &str) -> PathBuf {
+    let safe_username: String = username
+        .chars()
+        .map(|ch| {
+            if ch.is_ascii_alphanumeric() || matches!(ch, '_' | '-' | '.') {
+                ch
+            } else {
+                '_'
+            }
+        })
+        .collect();
+    get_data_dir().join(format!("me_cursor_{safe_username}.json"))
+}
+
 pub fn get_backup_dir(config_override: Option<&str>) -> PathBuf {
     if let Some(path) = config_override {
         return PathBuf::from(path);
@@ -68,6 +82,36 @@ fn get_xdg_data_dir() -> PathBuf {
         })
 }
 
+/// Enforce restrictive permissions (0600) on the config file.
+/// Warns to stderr if permissions were too open, then tightens them.
+#[cfg(unix)]
+pub fn ensure_config_permissions(path: &std::path::Path) {
+    use std::os::unix::fs::MetadataExt;
+
+    let Ok(meta) = std::fs::metadata(path) else {
+        return;
+    };
+    let mode = meta.mode() & 0o777;
+    if mode != 0o600 {
+        eprintln!(
+            "Warning: config file permissions were {mode:04o}, tightening to 0600: {}",
+            path.display()
+        );
+        let _ = set_permissions_600(path);
+    }
+}
+
+#[cfg(unix)]
+fn set_permissions_600(path: &std::path::Path) -> std::io::Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+    let perms = std::fs::Permissions::from_mode(0o600);
+    std::fs::set_permissions(path, perms)
+}
+
+/// No-op on non-Unix platforms.
+#[cfg(not(unix))]
+pub fn ensure_config_permissions(_path: &std::path::Path) {}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/core/sync_run.rs

@@ -20,6 +20,75 @@ impl SyncRunRecorder {
         Ok(Self { row_id })
     }
 
+    /// Returns the database row ID of this sync run.
+    pub fn row_id(&self) -> i64 {
+        self.row_id
+    }
+
+    /// Sets surgical-mode metadata on the run (mode, phase, IID manifest).
+    pub fn set_surgical_metadata(
+        &self,
+        conn: &Connection,
+        mode: &str,
+        phase: &str,
+        surgical_iids_json: &str,
+    ) -> Result<()> {
+        conn.execute(
+            "UPDATE sync_runs
+             SET mode = ?1, phase = ?2, surgical_iids_json = ?3
+             WHERE id = ?4",
+            rusqlite::params![mode, phase, surgical_iids_json, self.row_id],
+        )?;
+        Ok(())
+    }
+
+    /// Updates the current phase and refreshes the heartbeat timestamp.
+    pub fn update_phase(&self, conn: &Connection, phase: &str) -> Result<()> {
+        let now = now_ms();
+        conn.execute(
+            "UPDATE sync_runs SET phase = ?1, heartbeat_at = ?2 WHERE id = ?3",
+            rusqlite::params![phase, now, self.row_id],
+        )?;
+        Ok(())
+    }
+
+    /// Increments a counter column by 1 based on entity type and stage.
+    /// Unknown (entity_type, stage) combinations are silently ignored.
+    pub fn record_entity_result(
+        &self,
+        conn: &Connection,
+        entity_type: &str,
+        stage: &str,
+    ) -> Result<()> {
+        let column = match (entity_type, stage) {
+            ("issue", "fetched") => "issues_fetched",
+            ("issue", "ingested") => "issues_ingested",
+            ("mr", "fetched") => "mrs_fetched",
+            ("mr", "ingested") => "mrs_ingested",
+            ("issue" | "mr", "skipped_stale") => "skipped_stale",
+            ("doc", "regenerated") => "docs_regenerated",
+            ("doc", "embedded") => "docs_embedded",
+            (_, "warning") => "warnings_count",
+            _ => return Ok(()),
+        };
+        // Column name is from a hardcoded match, not user input — safe to interpolate.
+        let sql = format!("UPDATE sync_runs SET {column} = {column} + 1 WHERE id = ?1");
+        conn.execute(&sql, rusqlite::params![self.row_id])?;
+        Ok(())
+    }
+
+    /// Marks the run as cancelled with a reason. Consumes self (terminal state).
+    pub fn cancel(self, conn: &Connection, reason: &str) -> Result<()> {
+        let now = now_ms();
+        conn.execute(
+            "UPDATE sync_runs
+             SET status = 'cancelled', error = ?1, cancelled_at = ?2, finished_at = ?3
+             WHERE id = ?4",
+            rusqlite::params![reason, now, now, self.row_id],
+        )?;
+        Ok(())
+    }
+
     pub fn succeed(
         self,
         conn: &Connection,

src/core/sync_run_tests.rs

@@ -146,3 +146,239 @@ fn test_sync_run_recorder_fail_with_partial_metrics() {
     assert_eq!(parsed.len(), 1);
     assert_eq!(parsed[0].name, "ingest_issues");
 }
+
+#[test]
+fn sync_run_surgical_columns_exist() {
+    let conn = setup_test_db();
+    conn.execute(
+        "INSERT INTO sync_runs (started_at, heartbeat_at, status, command, mode, phase, surgical_iids_json)
+         VALUES (1000, 1000, 'running', 'sync', 'surgical', 'preflight', '{\"issues\":[7],\"mrs\":[]}')",
+        [],
+    )
+    .unwrap();
+    let (mode, phase, iids_json): (String, String, String) = conn
+        .query_row(
+            "SELECT mode, phase, surgical_iids_json FROM sync_runs WHERE mode = 'surgical'",
+            [],
+            |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)),
+        )
+        .unwrap();
+    assert_eq!(mode, "surgical");
+    assert_eq!(phase, "preflight");
+    assert!(iids_json.contains("7"));
+}
+
+#[test]
+fn sync_run_counter_defaults_are_zero() {
+    let conn = setup_test_db();
+    conn.execute(
+        "INSERT INTO sync_runs (started_at, heartbeat_at, status, command)
+         VALUES (2000, 2000, 'running', 'sync')",
+        [],
+    )
+    .unwrap();
+    let row_id = conn.last_insert_rowid();
+    let (issues_fetched, mrs_fetched, docs_regenerated, warnings_count): (i64, i64, i64, i64) =
+        conn.query_row(
+            "SELECT issues_fetched, mrs_fetched, docs_regenerated, warnings_count FROM sync_runs WHERE id = ?1",
+            [row_id],
+            |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?, r.get(3)?)),
+        )
+        .unwrap();
+    assert_eq!(issues_fetched, 0);
+    assert_eq!(mrs_fetched, 0);
+    assert_eq!(docs_regenerated, 0);
+    assert_eq!(warnings_count, 0);
+}
+
+#[test]
+fn sync_run_nullable_columns_default_to_null() {
+    let conn = setup_test_db();
+    conn.execute(
+        "INSERT INTO sync_runs (started_at, heartbeat_at, status, command)
+         VALUES (3000, 3000, 'running', 'sync')",
+        [],
+    )
+    .unwrap();
+    let row_id = conn.last_insert_rowid();
+    let (mode, phase, cancelled_at): (Option<String>, Option<String>, Option<i64>) = conn
+        .query_row(
+            "SELECT mode, phase, cancelled_at FROM sync_runs WHERE id = ?1",
+            [row_id],
+            |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)),
+        )
+        .unwrap();
+    assert!(mode.is_none());
+    assert!(phase.is_none());
+    assert!(cancelled_at.is_none());
+}
+
+#[test]
+fn sync_run_counter_round_trip() {
+    let conn = setup_test_db();
+    conn.execute(
+        "INSERT INTO sync_runs (started_at, heartbeat_at, status, command, mode, issues_fetched, mrs_ingested, docs_embedded)
+         VALUES (4000, 4000, 'succeeded', 'sync', 'surgical', 3, 2, 5)",
+        [],
+    )
+    .unwrap();
+    let row_id = conn.last_insert_rowid();
+    let (issues_fetched, mrs_ingested, docs_embedded): (i64, i64, i64) = conn
+        .query_row(
+            "SELECT issues_fetched, mrs_ingested, docs_embedded FROM sync_runs WHERE id = ?1",
+            [row_id],
+            |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)),
+        )
+        .unwrap();
+    assert_eq!(issues_fetched, 3);
+    assert_eq!(mrs_ingested, 2);
+    assert_eq!(docs_embedded, 5);
+}
+
+#[test]
+fn surgical_lifecycle_start_metadata_succeed() {
+    let conn = setup_test_db();
+    let recorder = SyncRunRecorder::start(&conn, "sync", "surg001").unwrap();
+    let row_id = recorder.row_id();
+
+    recorder
+        .set_surgical_metadata(
+            &conn,
+            "surgical",
+            "preflight",
+            r#"{"issues":[7,8],"mrs":[101]}"#,
+        )
+        .unwrap();
+
+    recorder.update_phase(&conn, "ingest").unwrap();
+    recorder
+        .record_entity_result(&conn, "issue", "fetched")
+        .unwrap();
+    recorder
+        .record_entity_result(&conn, "issue", "fetched")
+        .unwrap();
+    recorder
+        .record_entity_result(&conn, "issue", "ingested")
+        .unwrap();
+    recorder
+        .record_entity_result(&conn, "mr", "fetched")
+        .unwrap();
+    recorder
+        .record_entity_result(&conn, "mr", "ingested")
+        .unwrap();
+
+    recorder.succeed(&conn, &[], 3, 0).unwrap();
+
+    #[allow(clippy::type_complexity)]
+    let (mode, phase, iids, issues_fetched, mrs_fetched, issues_ingested, mrs_ingested, status): (
+        String,
+        String,
+        String,
+        i64,
+        i64,
+        i64,
+        i64,
+        String,
+    ) = conn
+        .query_row(
+            "SELECT mode, phase, surgical_iids_json, issues_fetched, mrs_fetched, \
+             issues_ingested, mrs_ingested, status \
+             FROM sync_runs WHERE id = ?1",
+            [row_id],
+            |r| {
+                Ok((
+                    r.get(0)?,
+                    r.get(1)?,
+                    r.get(2)?,
+                    r.get(3)?,
+                    r.get(4)?,
+                    r.get(5)?,
+                    r.get(6)?,
+                    r.get(7)?,
+                ))
+            },
+        )
+        .unwrap();
+
+    assert_eq!(mode, "surgical");
+    assert_eq!(phase, "ingest");
+    assert!(iids.contains("101"));
+    assert_eq!(issues_fetched, 2);
+    assert_eq!(mrs_fetched, 1);
+    assert_eq!(issues_ingested, 1);
+    assert_eq!(mrs_ingested, 1);
+    assert_eq!(status, "succeeded");
+}
+
+#[test]
+fn surgical_lifecycle_cancel() {
+    let conn = setup_test_db();
+    let recorder = SyncRunRecorder::start(&conn, "sync", "cancel01").unwrap();
+    let row_id = recorder.row_id();
+
+    recorder
+        .set_surgical_metadata(&conn, "surgical", "preflight", "{}")
+        .unwrap();
+    recorder
+        .cancel(&conn, "User requested cancellation")
+        .unwrap();
+
+    let (status, error, cancelled_at, finished_at): (
+        String,
+        Option<String>,
+        Option<i64>,
+        Option<i64>,
+    ) = conn
+        .query_row(
+            "SELECT status, error, cancelled_at, finished_at FROM sync_runs WHERE id = ?1",
+            [row_id],
+            |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?, r.get(3)?)),
+        )
+        .unwrap();
+
+    assert_eq!(status, "cancelled");
+    assert_eq!(error.as_deref(), Some("User requested cancellation"));
+    assert!(cancelled_at.is_some());
+    assert!(finished_at.is_some());
+}
+
+#[test]
+fn record_entity_result_ignores_unknown() {
+    let conn = setup_test_db();
+    let recorder = SyncRunRecorder::start(&conn, "sync", "unk001").unwrap();
+    recorder
+        .record_entity_result(&conn, "widget", "exploded")
+        .unwrap();
+}
+
+#[test]
+fn record_entity_result_doc_counters() {
+    let conn = setup_test_db();
+    let recorder = SyncRunRecorder::start(&conn, "sync", "cnt001").unwrap();
+    let row_id = recorder.row_id();
+
+    recorder
+        .record_entity_result(&conn, "doc", "regenerated")
+        .unwrap();
+    recorder
+        .record_entity_result(&conn, "doc", "regenerated")
+        .unwrap();
+    recorder
+        .record_entity_result(&conn, "doc", "embedded")
+        .unwrap();
+    recorder
+        .record_entity_result(&conn, "issue", "skipped_stale")
+        .unwrap();
+
+    let (docs_regen, docs_embed, skipped): (i64, i64, i64) = conn
+        .query_row(
+            "SELECT docs_regenerated, docs_embedded, skipped_stale FROM sync_runs WHERE id = ?1",
+            [row_id],
+            |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)),
+        )
+        .unwrap();
+
+    assert_eq!(docs_regen, 2);
+    assert_eq!(docs_embed, 1);
+    assert_eq!(skipped, 1);
+}

src/core/timeline.rs

@@ -164,9 +164,10 @@ pub struct TimelineResult {
     /// The search mode actually used for seeding (e.g. "hybrid", "lexical", "lexical (hybrid fallback)").
     pub search_mode: String,
     pub events: Vec<TimelineEvent>,
-    /// Total events before the `--limit` was applied (for meta.total_events vs meta.showing).
+    /// Total events after filters (e.g., --since) but before --limit was applied.
+    /// Use this to show "showing X of Y filtered events".
     #[serde(skip)]
-    pub total_events_before_limit: usize,
+    pub total_filtered_events: usize,
     pub seed_entities: Vec<EntityRef>,
     pub expanded_entities: Vec<ExpandedEntityRef>,
     pub unresolved_references: Vec<UnresolvedRef>,

src/core/timeline_seed.rs

@@ -260,6 +260,9 @@ fn resolve_documents_to_entities(
 }
 
 /// Find evidence notes: FTS5-matched discussion notes that provide context.
+///
+/// Uses round-robin selection across discussions to ensure diverse evidence
+/// rather than all notes coming from a single high-traffic discussion.
 fn find_evidence_notes(
     conn: &Connection,
     fts_query: &str,
@@ -267,6 +270,10 @@ fn find_evidence_notes(
     since_ms: Option<i64>,
     max_evidence: usize,
 ) -> Result<Vec<TimelineEvent>> {
+    // Fetch extra rows to enable round-robin across discussions.
+    // We'll select from multiple discussions in rotation.
+    let fetch_limit = (max_evidence * 5).max(50);
+
     let sql = r"
         SELECT n.id AS note_id, n.body, n.created_at, n.author_username,
                disc.id AS discussion_id,
@@ -286,7 +293,7 @@ fn find_evidence_notes(
 
     let mut stmt = conn.prepare(sql)?;
     let rows = stmt.query_map(
-        rusqlite::params![fts_query, project_id, since_ms, max_evidence as i64],
+        rusqlite::params![fts_query, project_id, since_ms, fetch_limit as i64],
         |row| {
             Ok((
                 row.get::<_, i64>(0)?,            // note_id
@@ -331,25 +338,84 @@ fn find_evidence_notes(
             }
         };
 
-        events.push(TimelineEvent {
-            timestamp: created_at,
-            entity_type: parent_type,
-            entity_id: parent_entity_id,
-            entity_iid: iid,
-            project_path,
-            event_type: TimelineEventType::NoteEvidence {
-                note_id,
-                snippet,
-                discussion_id: Some(discussion_id),
+        events.push((
+            discussion_id,
+            TimelineEvent {
+                timestamp: created_at,
+                entity_type: parent_type,
+                entity_id: parent_entity_id,
+                entity_iid: iid,
+                project_path,
+                event_type: TimelineEventType::NoteEvidence {
+                    note_id,
+                    snippet,
+                    discussion_id: Some(discussion_id),
+                },
+                summary: format!("Note by {}", author.as_deref().unwrap_or("unknown")),
+                actor: author,
+                url: None,
+                is_seed: true,
             },
-            summary: format!("Note by {}", author.as_deref().unwrap_or("unknown")),
-            actor: author,
-            url: None,
-            is_seed: true,
-        });
+        ));
     }
 
-    Ok(events)
+    // Round-robin selection across discussions for diverse evidence
+    Ok(round_robin_select_by_discussion(events, max_evidence))
+}
+
+/// Round-robin select events across discussions to ensure diverse evidence.
+///
+/// Groups events by discussion_id, then iterates through discussions in order,
+/// taking one event from each until the limit is reached.
+fn round_robin_select_by_discussion(
+    events: Vec<(i64, TimelineEvent)>,
+    max_evidence: usize,
+) -> Vec<TimelineEvent> {
+    use std::collections::HashMap;
+
+    if events.is_empty() || max_evidence == 0 {
+        return Vec::new();
+    }
+
+    // Group events by discussion_id, preserving order within each group
+    let mut by_discussion: HashMap<i64, Vec<TimelineEvent>> = HashMap::new();
+    let mut discussion_order: Vec<i64> = Vec::new();
+
+    for (discussion_id, event) in events {
+        if !by_discussion.contains_key(&discussion_id) {
+            discussion_order.push(discussion_id);
+        }
+        by_discussion.entry(discussion_id).or_default().push(event);
+    }
+
+    // Round-robin selection
+    let mut result = Vec::with_capacity(max_evidence);
+    let mut indices: Vec<usize> = vec![0; discussion_order.len()];
+
+    'outer: loop {
+        let mut made_progress = false;
+
+        for (disc_idx, &discussion_id) in discussion_order.iter().enumerate() {
+            let notes = by_discussion.get(&discussion_id).unwrap();
+            let note_idx = indices[disc_idx];
+
+            if note_idx < notes.len() {
+                result.push(notes[note_idx].clone());
+                indices[disc_idx] += 1;
+                made_progress = true;
+
+                if result.len() >= max_evidence {
+                    break 'outer;
+                }
+            }
+        }
+
+        if !made_progress {
+            break;
+        }
+    }
+
+    result
 }
 
 #[cfg(test)]

src/core/trace.rs

@@ -1,4 +1,5 @@
 use serde::Serialize;
+use tracing::info;
 
 use super::error::Result;
 use super::file_history::resolve_rename_chain;
@@ -51,6 +52,9 @@ pub struct TraceResult {
     pub renames_followed: bool,
     pub trace_chains: Vec<TraceChain>,
     pub total_chains: usize,
+    /// Diagnostic hints explaining why results may be empty.
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub hints: Vec<String>,
 }
 
 /// Run the trace query: file -> MR -> issue chain.
@@ -75,6 +79,14 @@ pub fn run_trace(
         (vec![path.to_string()], false)
     };
 
+    info!(
+        paths = all_paths.len(),
+        renames_followed,
+        "trace: resolved {} path(s) for '{}'",
+        all_paths.len(),
+        path
+    );
+
     // Build placeholders for IN clause
     let placeholders: Vec<String> = (0..all_paths.len())
         .map(|i| format!("?{}", i + 2))
@@ -100,7 +112,7 @@ pub fn run_trace(
         all_paths.len() + 2
     );
 
-    let mut stmt = conn.prepare(&mr_sql)?;
+    let mut stmt = conn.prepare_cached(&mr_sql)?;
 
     let mut params: Vec<Box<dyn rusqlite::types::ToSql>> = Vec::new();
     params.push(Box::new(project_id.unwrap_or(0)));
@@ -137,8 +149,14 @@ pub fn run_trace(
                 web_url: row.get(8)?,
             })
         })?
-        .filter_map(std::result::Result::ok)
-        .collect();
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    info!(
+        mr_count = mr_rows.len(),
+        "trace: found {} MR(s) touching '{}'",
+        mr_rows.len(),
+        path
+    );
 
     // Step 2: For each MR, find linked issues + optional discussions
     let mut trace_chains = Vec::with_capacity(mr_rows.len());
@@ -152,6 +170,16 @@ pub fn run_trace(
             Vec::new()
         };
 
+        info!(
+            mr_iid = mr.iid,
+            issues = issues.len(),
+            discussions = discussions.len(),
+            "trace: MR !{}: {} issue(s), {} discussion(s)",
+            mr.iid,
+            issues.len(),
+            discussions.len()
+        );
+
         trace_chains.push(TraceChain {
             mr_iid: mr.iid,
             mr_title: mr.title.clone(),
@@ -168,12 +196,20 @@ pub fn run_trace(
 
     let total_chains = trace_chains.len();
 
+    // Build diagnostic hints when no results found
+    let hints = if total_chains == 0 {
+        build_trace_hints(conn, project_id, &all_paths)?
+    } else {
+        Vec::new()
+    };
+
     Ok(TraceResult {
         path: path.to_string(),
         resolved_paths: all_paths,
         renames_followed,
         trace_chains,
         total_chains,
+        hints,
     })
 }
 
@@ -191,7 +227,7 @@ fn fetch_linked_issues(conn: &rusqlite::Connection, mr_id: i64) -> Result<Vec<Tr
                  CASE er.reference_type WHEN 'closes' THEN 0 WHEN 'related' THEN 1 ELSE 2 END, \
                  i.iid";
 
-    let mut stmt = conn.prepare(sql)?;
+    let mut stmt = conn.prepare_cached(sql)?;
     let issues: Vec<TraceIssue> = stmt
         .query_map(rusqlite::params![mr_id], |row| {
             Ok(TraceIssue {
@@ -202,8 +238,7 @@ fn fetch_linked_issues(conn: &rusqlite::Connection, mr_id: i64) -> Result<Vec<Tr
                 web_url: row.get(4)?,
             })
         })?
-        .filter_map(std::result::Result::ok)
-        .collect();
+        .collect::<std::result::Result<Vec<_>, _>>()?;
 
     Ok(issues)
 }
@@ -225,11 +260,10 @@ fn fetch_trace_discussions(
          WHERE d.merge_request_id = ?1 \
            AND n.position_new_path IN ({in_clause}) \
            AND n.is_system = 0 \
-         ORDER BY n.created_at DESC \
-         LIMIT 20"
+         ORDER BY n.created_at DESC"
     );
 
-    let mut stmt = conn.prepare(&sql)?;
+    let mut stmt = conn.prepare_cached(&sql)?;
 
     let mut params: Vec<Box<dyn rusqlite::types::ToSql>> = Vec::new();
     params.push(Box::new(mr_id));
@@ -251,12 +285,57 @@ fn fetch_trace_discussions(
                 created_at_iso: ms_to_iso(created_at),
             })
         })?
-        .filter_map(std::result::Result::ok)
-        .collect();
+        .collect::<std::result::Result<Vec<_>, _>>()?;
 
     Ok(discussions)
 }
 
+/// Build diagnostic hints explaining why a trace query returned no results.
+fn build_trace_hints(
+    conn: &rusqlite::Connection,
+    project_id: Option<i64>,
+    paths: &[String],
+) -> Result<Vec<String>> {
+    let mut hints = Vec::new();
+
+    // Check if mr_file_changes has ANY rows for this project
+    let has_file_changes: bool = if let Some(pid) = project_id {
+        conn.query_row(
+            "SELECT EXISTS(SELECT 1 FROM mr_file_changes WHERE project_id = ?1 LIMIT 1)",
+            rusqlite::params![pid],
+            |row| row.get(0),
+        )?
+    } else {
+        conn.query_row(
+            "SELECT EXISTS(SELECT 1 FROM mr_file_changes LIMIT 1)",
+            [],
+            |row| row.get(0),
+        )?
+    };
+
+    if !has_file_changes {
+        hints.push(
+            "No MR file changes have been synced yet. Run 'lore sync' to fetch file change data."
+                .to_string(),
+        );
+        return Ok(hints);
+    }
+
+    // File changes exist but none match these paths
+    let path_list = paths
+        .iter()
+        .map(|p| format!("'{p}'"))
+        .collect::<Vec<_>>()
+        .join(", ");
+    hints.push(format!(
+        "Searched paths [{}] were not found in MR file changes. \
+         The file may predate the sync window or use a different path.",
+        path_list
+    ));
+
+    Ok(hints)
+}
+
 #[cfg(test)]
 #[path = "trace_tests.rs"]
 mod tests;

src/documents/extractor.rs

@@ -6,10 +6,12 @@ use std::collections::{BTreeSet, HashMap};
 use std::fmt::Write as _;
 
 use super::truncation::{
-    MAX_DISCUSSION_BYTES, NoteContent, truncate_discussion, truncate_hard_cap,
+    MAX_DISCUSSION_BYTES, MAX_DOCUMENT_BYTES_HARD, NoteContent, pre_truncate_description,
+    truncate_discussion, truncate_hard_cap,
 };
 use crate::core::error::Result;
 use crate::core::time::ms_to_iso;
+use tracing::warn;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
@@ -158,7 +160,16 @@ pub fn extract_issue_document(conn: &Connection, issue_id: i64) -> Result<Option
 
     if let Some(ref desc) = description {
         content.push_str("\n--- Description ---\n\n");
-        content.push_str(desc);
+        // Pre-truncate to avoid unbounded memory allocation for huge descriptions
+        let pre_trunc = pre_truncate_description(desc, MAX_DOCUMENT_BYTES_HARD);
+        if pre_trunc.was_truncated {
+            warn!(
+                iid,
+                original_bytes = pre_trunc.original_bytes,
+                "Issue description truncated (oversized)"
+            );
+        }
+        content.push_str(&pre_trunc.content);
     }
 
     let labels_hash = compute_list_hash(&labels);
@@ -268,7 +279,16 @@ pub fn extract_mr_document(conn: &Connection, mr_id: i64) -> Result<Option<Docum
 
     if let Some(ref desc) = description {
         content.push_str("\n--- Description ---\n\n");
-        content.push_str(desc);
+        // Pre-truncate to avoid unbounded memory allocation for huge descriptions
+        let pre_trunc = pre_truncate_description(desc, MAX_DOCUMENT_BYTES_HARD);
+        if pre_trunc.was_truncated {
+            warn!(
+                iid,
+                original_bytes = pre_trunc.original_bytes,
+                "MR description truncated (oversized)"
+            );
+        }
+        content.push_str(&pre_trunc.content);
     }
 
     let labels_hash = compute_list_hash(&labels);

src/documents/mod.rs

@@ -7,7 +7,10 @@ pub use extractor::{
     extract_discussion_document, extract_issue_document, extract_mr_document,
     extract_note_document, extract_note_document_cached,
 };
-pub use regenerator::{RegenerateResult, regenerate_dirty_documents};
+pub use regenerator::{
+    RegenerateForSourcesResult, RegenerateResult, regenerate_dirty_documents,
+    regenerate_dirty_documents_for_sources,
+};
 pub use truncation::{
     MAX_DISCUSSION_BYTES, MAX_DOCUMENT_BYTES_HARD, NoteContent, TruncationReason, TruncationResult,
     truncate_discussion, truncate_hard_cap, truncate_utf8,

src/documents/regenerator.rs

@@ -84,6 +84,60 @@ pub fn regenerate_dirty_documents(
     Ok(result)
 }
 
+#[derive(Debug, Default)]
+pub struct RegenerateForSourcesResult {
+    pub regenerated: usize,
+    pub unchanged: usize,
+    pub errored: usize,
+    pub document_ids: Vec<i64>,
+}
+
+pub fn regenerate_dirty_documents_for_sources(
+    conn: &Connection,
+    source_keys: &[(SourceType, i64)],
+) -> Result<RegenerateForSourcesResult> {
+    let mut result = RegenerateForSourcesResult::default();
+    let mut cache = ParentMetadataCache::new();
+
+    for &(source_type, source_id) in source_keys {
+        match regenerate_one(conn, source_type, source_id, &mut cache) {
+            Ok(changed) => {
+                if changed {
+                    result.regenerated += 1;
+                } else {
+                    result.unchanged += 1;
+                }
+                clear_dirty(conn, source_type, source_id)?;
+
+                // Try to collect the document_id if a document exists
+                if let Ok(doc_id) = get_document_id(conn, source_type, source_id) {
+                    result.document_ids.push(doc_id);
+                }
+            }
+            Err(e) => {
+                warn!(
+                    source_type = %source_type,
+                    source_id,
+                    error = %e,
+                    "Failed to regenerate document for source"
+                );
+                record_dirty_error(conn, source_type, source_id, &e.to_string())?;
+                result.errored += 1;
+            }
+        }
+    }
+
+    debug!(
+        regenerated = result.regenerated,
+        unchanged = result.unchanged,
+        errored = result.errored,
+        document_ids = result.document_ids.len(),
+        "Scoped document regeneration complete"
+    );
+
+    Ok(result)
+}
+
 fn regenerate_one(
     conn: &Connection,
     source_type: SourceType,

src/documents/regenerator_tests.rs

@@ -518,3 +518,88 @@ fn test_note_regeneration_cache_invalidates_across_parents() {
     assert!(beta_content.contains("parent_iid: 99"));
     assert!(beta_content.contains("parent_title: Issue Beta"));
 }
+
+#[test]
+fn test_scoped_regen_only_processes_specified_sources() {
+    let conn = setup_db();
+    // Insert two issues
+    conn.execute(
+        "INSERT INTO issues (id, gitlab_id, project_id, iid, title, state, created_at, updated_at, last_seen_at) VALUES (1, 10, 1, 42, 'First Issue', 'opened', 1000, 2000, 3000)",
+        [],
+    ).unwrap();
+    conn.execute(
+        "INSERT INTO issues (id, gitlab_id, project_id, iid, title, state, created_at, updated_at, last_seen_at) VALUES (2, 20, 1, 43, 'Second Issue', 'opened', 1000, 2000, 3000)",
+        [],
+    ).unwrap();
+
+    // Mark both dirty
+    mark_dirty(&conn, SourceType::Issue, 1).unwrap();
+    mark_dirty(&conn, SourceType::Issue, 2).unwrap();
+
+    // Regenerate only issue 1
+    let result = regenerate_dirty_documents_for_sources(&conn, &[(SourceType::Issue, 1)]).unwrap();
+
+    assert_eq!(result.regenerated, 1);
+    assert_eq!(result.errored, 0);
+
+    // Issue 1 should be regenerated and cleared from dirty
+    let doc_count: i64 = conn
+        .query_row(
+            "SELECT COUNT(*) FROM documents WHERE source_type = 'issue' AND source_id = 1",
+            [],
+            |r| r.get(0),
+        )
+        .unwrap();
+    assert_eq!(doc_count, 1);
+
+    // Issue 2 should still be dirty
+    let dirty_count: i64 = conn
+        .query_row(
+            "SELECT COUNT(*) FROM dirty_sources WHERE source_type = 'issue' AND source_id = 2",
+            [],
+            |r| r.get(0),
+        )
+        .unwrap();
+    assert_eq!(dirty_count, 1);
+}
+
+#[test]
+fn test_scoped_regen_returns_document_ids() {
+    let conn = setup_db();
+    conn.execute(
+        "INSERT INTO issues (id, gitlab_id, project_id, iid, title, state, created_at, updated_at, last_seen_at) VALUES (1, 10, 1, 42, 'Test Issue', 'opened', 1000, 2000, 3000)",
+        [],
+    ).unwrap();
+    mark_dirty(&conn, SourceType::Issue, 1).unwrap();
+
+    let result = regenerate_dirty_documents_for_sources(&conn, &[(SourceType::Issue, 1)]).unwrap();
+
+    assert_eq!(result.document_ids.len(), 1);
+
+    // Verify returned ID matches the actual document
+    let actual_id: i64 = conn
+        .query_row(
+            "SELECT id FROM documents WHERE source_type = 'issue' AND source_id = 1",
+            [],
+            |r| r.get(0),
+        )
+        .unwrap();
+    assert_eq!(result.document_ids[0], actual_id);
+}
+
+#[test]
+fn test_scoped_regen_handles_missing_source() {
+    let conn = setup_db();
+    // Don't insert any issues — source_id 999 doesn't exist
+    // But mark it dirty so the function tries to process it
+    mark_dirty(&conn, SourceType::Issue, 999).unwrap();
+
+    let result =
+        regenerate_dirty_documents_for_sources(&conn, &[(SourceType::Issue, 999)]).unwrap();
+
+    // Source doesn't exist, so regenerate_one returns Ok(true) deleting the doc.
+    // No document_id to collect since there's nothing in the documents table.
+    assert_eq!(result.regenerated, 1);
+    assert_eq!(result.errored, 0);
+    assert!(result.document_ids.is_empty());
+}

src/documents/truncation.rs

@@ -48,6 +48,56 @@ pub fn truncate_utf8(s: &str, max_bytes: usize) -> &str {
     &s[..end]
 }
 
+/// Result of pre-truncating a description to avoid unbounded memory allocation.
+pub struct DescriptionPreTruncateResult {
+    pub content: String,
+    pub was_truncated: bool,
+    pub original_bytes: usize,
+}
+
+/// Pre-truncate a description to avoid allocating huge amounts of memory.
+///
+/// This is called BEFORE appending to the document content, so we don't
+/// allocate memory for pathologically large descriptions (e.g., 500MB base64 blob).
+///
+/// Returns the (potentially truncated) description and whether truncation occurred.
+pub fn pre_truncate_description(desc: &str, max_bytes: usize) -> DescriptionPreTruncateResult {
+    let original_bytes = desc.len();
+
+    if original_bytes <= max_bytes {
+        return DescriptionPreTruncateResult {
+            content: desc.to_string(),
+            was_truncated: false,
+            original_bytes,
+        };
+    }
+
+    // Truncate at UTF-8 boundary and add indicator
+    let truncated = truncate_utf8(desc, max_bytes.saturating_sub(50)); // Reserve space for marker
+    let mut content = truncated.to_string();
+    content.push_str("\n\n[... description truncated from ");
+    content.push_str(&format_bytes(original_bytes));
+    content.push_str(" to ");
+    content.push_str(&format_bytes(max_bytes));
+    content.push_str(" ...]");
+
+    DescriptionPreTruncateResult {
+        content,
+        was_truncated: true,
+        original_bytes,
+    }
+}
+
+fn format_bytes(bytes: usize) -> String {
+    if bytes >= 1_000_000 {
+        format!("{:.1}MB", bytes as f64 / 1_000_000.0)
+    } else if bytes >= 1_000 {
+        format!("{:.1}KB", bytes as f64 / 1_000.0)
+    } else {
+        format!("{}B", bytes)
+    }
+}
+
 pub fn truncate_discussion(notes: &[NoteContent], max_bytes: usize) -> TruncationResult {
     if notes.is_empty() {
         return TruncationResult {

src/embedding/mod.rs

@@ -7,5 +7,5 @@ pub mod similarity;
 
 pub use change_detector::{PendingDocument, count_pending_documents, find_pending_documents};
 pub use chunking::{CHUNK_MAX_BYTES, CHUNK_OVERLAP_CHARS, split_into_chunks};
-pub use pipeline::{EmbedResult, embed_documents};
+pub use pipeline::{EmbedForIdsResult, EmbedResult, embed_documents, embed_documents_by_ids};
 pub use similarity::cosine_similarity;

src/embedding/pipeline.rs

@@ -578,3 +578,207 @@ fn sha256_hash(input: &str) -> String {
     hasher.update(input.as_bytes());
     format!("{:x}", hasher.finalize())
 }
+
+#[derive(Debug, Default)]
+pub struct EmbedForIdsResult {
+    pub chunks_embedded: usize,
+    pub docs_embedded: usize,
+    pub failed: usize,
+    pub skipped: usize,
+}
+
+/// Embed only the documents with the given IDs, skipping any that are
+/// already embedded with matching config (model, dims, chunk size, hash).
+pub async fn embed_documents_by_ids(
+    conn: &Connection,
+    client: &OllamaClient,
+    model_name: &str,
+    concurrency: usize,
+    document_ids: &[i64],
+    signal: &ShutdownSignal,
+) -> Result<EmbedForIdsResult> {
+    let mut result = EmbedForIdsResult::default();
+
+    if document_ids.is_empty() {
+        return Ok(result);
+    }
+
+    if signal.is_cancelled() {
+        return Ok(result);
+    }
+
+    // Load documents for the specified IDs, filtering out already-embedded
+    let pending = find_documents_by_ids(conn, document_ids, model_name)?;
+
+    if pending.is_empty() {
+        result.skipped = document_ids.len();
+        return Ok(result);
+    }
+
+    let skipped_count = document_ids.len() - pending.len();
+    result.skipped = skipped_count;
+
+    info!(
+        requested = document_ids.len(),
+        pending = pending.len(),
+        skipped = skipped_count,
+        "Scoped embedding: processing documents by ID"
+    );
+
+    // Use the same SAVEPOINT + embed_page pattern as the main pipeline
+    let mut last_id: i64 = 0;
+    let mut processed: usize = 0;
+    let total = pending.len();
+    let mut page_stats = EmbedResult::default();
+
+    conn.execute_batch("SAVEPOINT embed_by_ids")?;
+    let page_result = embed_page(
+        conn,
+        client,
+        model_name,
+        concurrency,
+        &pending,
+        &mut page_stats,
+        &mut last_id,
+        &mut processed,
+        total,
+        &None,
+        signal,
+    )
+    .await;
+
+    match page_result {
+        Ok(()) if signal.is_cancelled() => {
+            let _ = conn.execute_batch("ROLLBACK TO embed_by_ids; RELEASE embed_by_ids");
+            info!("Rolled back scoped embed page due to cancellation");
+        }
+        Ok(()) => {
+            conn.execute_batch("RELEASE embed_by_ids")?;
+
+            // Count actual results from DB
+            let (chunks, docs) = count_embedded_results(conn, &pending)?;
+            result.chunks_embedded = chunks;
+            result.docs_embedded = docs;
+            result.failed = page_stats.failed;
+        }
+        Err(e) => {
+            let _ = conn.execute_batch("ROLLBACK TO embed_by_ids; RELEASE embed_by_ids");
+            return Err(e);
+        }
+    }
+
+    info!(
+        chunks_embedded = result.chunks_embedded,
+        docs_embedded = result.docs_embedded,
+        failed = result.failed,
+        skipped = result.skipped,
+        "Scoped embedding complete"
+    );
+
+    Ok(result)
+}
+
+/// Load documents by specific IDs, filtering out those already embedded
+/// with matching config (same logic as `find_pending_documents` but scoped).
+fn find_documents_by_ids(
+    conn: &Connection,
+    document_ids: &[i64],
+    model_name: &str,
+) -> Result<Vec<crate::embedding::change_detector::PendingDocument>> {
+    use crate::embedding::chunking::{CHUNK_MAX_BYTES, EXPECTED_DIMS};
+
+    if document_ids.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    // Build IN clause with placeholders
+    let placeholders: Vec<String> = (0..document_ids.len())
+        .map(|i| format!("?{}", i + 1))
+        .collect();
+    let in_clause = placeholders.join(", ");
+
+    let sql = format!(
+        r#"
+        SELECT d.id, d.content_text, d.content_hash
+        FROM documents d
+        LEFT JOIN embedding_metadata em
+          ON em.document_id = d.id AND em.chunk_index = 0
+        WHERE d.id IN ({in_clause})
+          AND (
+            em.document_id IS NULL
+            OR em.document_hash != d.content_hash
+            OR em.chunk_max_bytes IS NULL
+            OR em.chunk_max_bytes != ?{chunk_bytes_idx}
+            OR em.model != ?{model_idx}
+            OR em.dims != ?{dims_idx}
+          )
+        ORDER BY d.id
+        "#,
+        in_clause = in_clause,
+        chunk_bytes_idx = document_ids.len() + 1,
+        model_idx = document_ids.len() + 2,
+        dims_idx = document_ids.len() + 3,
+    );
+
+    let mut stmt = conn.prepare(&sql)?;
+
+    // Build params: document_ids... then chunk_max_bytes, model, dims
+    let mut params: Vec<Box<dyn rusqlite::types::ToSql>> = Vec::new();
+    for id in document_ids {
+        params.push(Box::new(*id));
+    }
+    params.push(Box::new(CHUNK_MAX_BYTES as i64));
+    params.push(Box::new(model_name.to_string()));
+    params.push(Box::new(EXPECTED_DIMS as i64));
+
+    let param_refs: Vec<&dyn rusqlite::types::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+
+    let rows = stmt
+        .query_map(param_refs.as_slice(), |row| {
+            Ok(crate::embedding::change_detector::PendingDocument {
+                document_id: row.get(0)?,
+                content_text: row.get(1)?,
+                content_hash: row.get(2)?,
+            })
+        })?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    Ok(rows)
+}
+
+/// Count how many chunks and complete docs were embedded for the given pending docs.
+fn count_embedded_results(
+    conn: &Connection,
+    pending: &[crate::embedding::change_detector::PendingDocument],
+) -> Result<(usize, usize)> {
+    let mut total_chunks: usize = 0;
+    let mut total_docs: usize = 0;
+
+    for doc in pending {
+        let chunk_count: i64 = conn.query_row(
+            "SELECT COUNT(*) FROM embedding_metadata WHERE document_id = ?1 AND last_error IS NULL",
+            [doc.document_id],
+            |row| row.get(0),
+        )?;
+        if chunk_count > 0 {
+            total_chunks += chunk_count as usize;
+            // Check if all expected chunks are present (chunk_count metadata on chunk_index=0)
+            let expected: Option<i64> = conn.query_row(
+                "SELECT chunk_count FROM embedding_metadata WHERE document_id = ?1 AND chunk_index = 0",
+                [doc.document_id],
+                |row| row.get(0),
+            )?;
+            if let Some(expected_count) = expected
+                && chunk_count >= expected_count
+            {
+                total_docs += 1;
+            }
+        }
+    }
+
+    Ok((total_chunks, total_docs))
+}
+
+#[cfg(test)]
+#[path = "pipeline_tests.rs"]
+mod tests;

src/embedding/pipeline_tests.rs

@@ -0,0 +1,184 @@
+use std::path::Path;
+
+use rusqlite::Connection;
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use crate::core::db::{create_connection, run_migrations};
+use crate::core::shutdown::ShutdownSignal;
+use crate::embedding::chunking::EXPECTED_DIMS;
+use crate::embedding::ollama::{OllamaClient, OllamaConfig};
+use crate::embedding::pipeline::embed_documents_by_ids;
+
+const MODEL: &str = "nomic-embed-text";
+
+fn setup_db() -> Connection {
+    let conn = create_connection(Path::new(":memory:")).unwrap();
+    run_migrations(&conn).unwrap();
+    conn
+}
+
+fn insert_test_project(conn: &Connection) -> i64 {
+    conn.execute(
+        "INSERT INTO projects (gitlab_project_id, path_with_namespace, web_url)
+         VALUES (1, 'group/test', 'https://gitlab.example.com/group/test')",
+        [],
+    )
+    .unwrap();
+    conn.last_insert_rowid()
+}
+
+fn insert_test_document(
+    conn: &Connection,
+    project_id: i64,
+    source_id: i64,
+    content: &str,
+    hash: &str,
+) -> i64 {
+    conn.execute(
+        "INSERT INTO documents (source_type, source_id, project_id, content_text, content_hash)
+         VALUES ('issue', ?1, ?2, ?3, ?4)",
+        rusqlite::params![source_id, project_id, content, hash],
+    )
+    .unwrap();
+    conn.last_insert_rowid()
+}
+
+fn make_fake_embedding() -> Vec<f32> {
+    vec![0.1_f32; EXPECTED_DIMS]
+}
+
+fn make_ollama_response(count: usize) -> serde_json::Value {
+    let embedding = make_fake_embedding();
+    let embeddings: Vec<_> = (0..count).map(|_| embedding.clone()).collect();
+    serde_json::json!({
+        "model": MODEL,
+        "embeddings": embeddings
+    })
+}
+
+fn count_embeddings_for_doc(conn: &Connection, doc_id: i64) -> i64 {
+    conn.query_row(
+        "SELECT COUNT(*) FROM embedding_metadata WHERE document_id = ?1",
+        [doc_id],
+        |row| row.get(0),
+    )
+    .unwrap()
+}
+
+fn make_client(base_url: &str) -> OllamaClient {
+    OllamaClient::new(OllamaConfig {
+        base_url: base_url.to_string(),
+        model: MODEL.to_string(),
+        timeout_secs: 10,
+    })
+}
+
+#[tokio::test]
+async fn test_embed_by_ids_only_embeds_specified_docs() {
+    let mock_server = MockServer::start().await;
+
+    Mock::given(method("POST"))
+        .and(path("/api/embed"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(make_ollama_response(1)))
+        .mount(&mock_server)
+        .await;
+
+    let conn = setup_db();
+    let proj_id = insert_test_project(&conn);
+    let doc1 = insert_test_document(&conn, proj_id, 1, "Hello world content for doc 1", "hash_a");
+    let doc2 = insert_test_document(&conn, proj_id, 2, "Hello world content for doc 2", "hash_b");
+
+    let signal = ShutdownSignal::new();
+    let client = make_client(&mock_server.uri());
+
+    // Only embed doc1
+    let result = embed_documents_by_ids(&conn, &client, MODEL, 1, &[doc1], &signal)
+        .await
+        .unwrap();
+
+    assert_eq!(result.docs_embedded, 1, "Should embed exactly 1 doc");
+    assert!(result.chunks_embedded > 0, "Should have embedded chunks");
+
+    // doc1 should have embeddings
+    assert!(
+        count_embeddings_for_doc(&conn, doc1) > 0,
+        "doc1 should have embeddings"
+    );
+
+    // doc2 should have NO embeddings
+    assert_eq!(
+        count_embeddings_for_doc(&conn, doc2),
+        0,
+        "doc2 should have no embeddings"
+    );
+}
+
+#[tokio::test]
+async fn test_embed_by_ids_skips_already_embedded() {
+    let mock_server = MockServer::start().await;
+
+    Mock::given(method("POST"))
+        .and(path("/api/embed"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(make_ollama_response(1)))
+        .expect(1) // Should only be called once
+        .mount(&mock_server)
+        .await;
+
+    let conn = setup_db();
+    let proj_id = insert_test_project(&conn);
+    let doc1 = insert_test_document(&conn, proj_id, 1, "Hello world content for doc 1", "hash_a");
+
+    let signal = ShutdownSignal::new();
+    let client = make_client(&mock_server.uri());
+
+    // First embed
+    let result1 = embed_documents_by_ids(&conn, &client, MODEL, 1, &[doc1], &signal)
+        .await
+        .unwrap();
+    assert_eq!(result1.docs_embedded, 1);
+
+    // Second embed with same doc — should skip
+    let result2 = embed_documents_by_ids(&conn, &client, MODEL, 1, &[doc1], &signal)
+        .await
+        .unwrap();
+    assert_eq!(result2.docs_embedded, 0, "Should embed 0 on second call");
+    assert_eq!(result2.skipped, 1, "Should report 1 skipped");
+    assert_eq!(result2.chunks_embedded, 0, "No new chunks");
+}
+
+#[tokio::test]
+async fn test_embed_by_ids_empty_input() {
+    let conn = setup_db();
+    let signal = ShutdownSignal::new();
+    // Client URL doesn't matter — should never be called
+    let client = make_client("http://localhost:99999");
+
+    let result = embed_documents_by_ids(&conn, &client, MODEL, 1, &[], &signal)
+        .await
+        .unwrap();
+
+    assert_eq!(result.docs_embedded, 0);
+    assert_eq!(result.chunks_embedded, 0);
+    assert_eq!(result.failed, 0);
+    assert_eq!(result.skipped, 0);
+}
+
+#[tokio::test]
+async fn test_embed_by_ids_respects_cancellation() {
+    let conn = setup_db();
+    let proj_id = insert_test_project(&conn);
+    let doc1 = insert_test_document(&conn, proj_id, 1, "Hello world content for doc 1", "hash_a");
+
+    let signal = ShutdownSignal::new();
+    signal.cancel(); // Pre-cancel
+
+    let client = make_client("http://localhost:99999");
+
+    let result = embed_documents_by_ids(&conn, &client, MODEL, 1, &[doc1], &signal)
+        .await
+        .unwrap();
+
+    assert_eq!(result.docs_embedded, 0, "Should embed 0 when cancelled");
+    assert_eq!(result.chunks_embedded, 0, "No chunks when cancelled");
+}

src/gitlab/client.rs

@@ -112,6 +112,18 @@ impl GitLabClient {
         self.request("/api/v4/version").await
     }
 
+    pub async fn get_issue_by_iid(&self, project_id: i64, iid: i64) -> Result<GitLabIssue> {
+        self.request(&format!("/api/v4/projects/{project_id}/issues/{iid}"))
+            .await
+    }
+
+    pub async fn get_mr_by_iid(&self, project_id: i64, iid: i64) -> Result<GitLabMergeRequest> {
+        self.request(&format!(
+            "/api/v4/projects/{project_id}/merge_requests/{iid}"
+        ))
+        .await
+    }
+
     const MAX_RETRIES: u32 = 3;
 
     async fn request<T: serde::de::DeserializeOwned>(&self, path: &str) -> Result<T> {
@@ -564,6 +576,23 @@ impl GitLabClient {
 
         Ok(discussions)
     }
+
+    pub async fn fetch_all_issue_discussions(
+        &self,
+        gitlab_project_id: i64,
+        issue_iid: i64,
+    ) -> Result<Vec<GitLabDiscussion>> {
+        use futures::StreamExt;
+
+        let mut discussions = Vec::new();
+        let mut stream = self.paginate_issue_discussions(gitlab_project_id, issue_iid);
+
+        while let Some(result) = stream.next().await {
+            discussions.push(result?);
+        }
+
+        Ok(discussions)
+    }
 }
 
 impl GitLabClient {
@@ -763,6 +792,10 @@ fn ms_to_iso8601(ms: i64) -> Option<String> {
         .map(|dt| dt.format("%Y-%m-%dT%H:%M:%S%.3fZ").to_string())
 }
 
+#[cfg(test)]
+#[path = "client_tests.rs"]
+mod client_tests;
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/gitlab/client_tests.rs

@@ -0,0 +1,113 @@
+use super::*;
+use crate::core::error::LoreError;
+use wiremock::matchers::{header, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+#[tokio::test]
+async fn get_issue_by_iid_success() {
+    let server = MockServer::start().await;
+    let issue_json = serde_json::json!({
+        "id": 1001,
+        "iid": 42,
+        "project_id": 5,
+        "title": "Fix login bug",
+        "state": "opened",
+        "created_at": "2026-01-15T10:00:00Z",
+        "updated_at": "2026-02-01T14:30:00Z",
+        "author": { "id": 1, "username": "dev1", "name": "Developer One" },
+        "web_url": "https://gitlab.example.com/group/repo/-/issues/42",
+        "labels": [],
+        "milestone": null,
+        "assignees": [],
+        "closed_at": null,
+        "description": "Login fails on mobile"
+    });
+
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/5/issues/42"))
+        .and(header("PRIVATE-TOKEN", "test-token"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(&issue_json))
+        .mount(&server)
+        .await;
+
+    let client = GitLabClient::new(&server.uri(), "test-token", Some(100.0));
+    let issue = client.get_issue_by_iid(5, 42).await.unwrap();
+    assert_eq!(issue.iid, 42);
+    assert_eq!(issue.title, "Fix login bug");
+}
+
+#[tokio::test]
+async fn get_issue_by_iid_not_found() {
+    let server = MockServer::start().await;
+
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/5/issues/999"))
+        .respond_with(
+            ResponseTemplate::new(404)
+                .set_body_json(serde_json::json!({"message": "404 Not Found"})),
+        )
+        .mount(&server)
+        .await;
+
+    let client = GitLabClient::new(&server.uri(), "test-token", Some(100.0));
+    let err = client.get_issue_by_iid(5, 999).await.unwrap_err();
+    assert!(matches!(err, LoreError::GitLabNotFound { .. }));
+}
+
+#[tokio::test]
+async fn get_mr_by_iid_success() {
+    let server = MockServer::start().await;
+    let mr_json = serde_json::json!({
+        "id": 2001,
+        "iid": 101,
+        "project_id": 5,
+        "title": "Add caching layer",
+        "state": "merged",
+        "created_at": "2026-01-20T09:00:00Z",
+        "updated_at": "2026-02-10T16:00:00Z",
+        "author": { "id": 2, "username": "dev2", "name": "Developer Two" },
+        "web_url": "https://gitlab.example.com/group/repo/-/merge_requests/101",
+        "source_branch": "feature/caching",
+        "target_branch": "main",
+        "draft": false,
+        "labels": [],
+        "milestone": null,
+        "assignees": [],
+        "reviewers": [],
+        "merged_by": null,
+        "merged_at": null,
+        "closed_at": null,
+        "description": "Adds Redis caching"
+    });
+
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/5/merge_requests/101"))
+        .and(header("PRIVATE-TOKEN", "test-token"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(&mr_json))
+        .mount(&server)
+        .await;
+
+    let client = GitLabClient::new(&server.uri(), "test-token", Some(100.0));
+    let mr = client.get_mr_by_iid(5, 101).await.unwrap();
+    assert_eq!(mr.iid, 101);
+    assert_eq!(mr.title, "Add caching layer");
+    assert_eq!(mr.source_branch, "feature/caching");
+}
+
+#[tokio::test]
+async fn get_mr_by_iid_not_found() {
+    let server = MockServer::start().await;
+
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/5/merge_requests/999"))
+        .respond_with(
+            ResponseTemplate::new(404)
+                .set_body_json(serde_json::json!({"message": "404 Not Found"})),
+        )
+        .mount(&server)
+        .await;
+
+    let client = GitLabClient::new(&server.uri(), "test-token", Some(100.0));
+    let err = client.get_mr_by_iid(5, 999).await.unwrap_err();
+    assert!(matches!(err, LoreError::GitLabNotFound { .. }));
+}

src/ingestion/discussions.rs

@@ -1,4 +1,3 @@
-use futures::StreamExt;
 use rusqlite::{Connection, params};
 use tracing::{debug, warn};
 
@@ -9,8 +8,9 @@ use crate::core::time::now_ms;
 use crate::documents::SourceType;
 use crate::gitlab::GitLabClient;
 use crate::gitlab::transformers::{
-    NormalizedNote, NoteableRef, transform_discussion, transform_notes,
+    NormalizedDiscussion, NormalizedNote, NoteableRef, transform_discussion, transform_notes,
 };
+use crate::gitlab::types::GitLabDiscussion;
 use crate::ingestion::dirty_tracker;
 
 use super::issues::IssueForDiscussionSync;
@@ -29,109 +29,113 @@ pub struct IngestDiscussionsResult {
     pub stale_discussions_removed: usize,
 }
 
-pub async fn ingest_issue_discussions(
-    conn: &Connection,
-    client: &GitLabClient,
-    config: &Config,
-    gitlab_project_id: i64,
-    local_project_id: i64,
-    issues: &[IssueForDiscussionSync],
-) -> Result<IngestDiscussionsResult> {
-    let mut total_result = IngestDiscussionsResult::default();
+// ═══════════════════════════════════════════════════════════════════════
+//  Prefetch pattern — concurrent HTTP fetch, sequential DB write
+// ═══════════════════════════════════════════════════════════════════════
 
-    for issue in issues {
-        let result = ingest_discussions_for_issue(
-            conn,
-            client,
-            config,
-            gitlab_project_id,
-            local_project_id,
-            issue,
-        )
-        .await?;
-
-        total_result.discussions_fetched += result.discussions_fetched;
-        total_result.discussions_upserted += result.discussions_upserted;
-        total_result.notes_upserted += result.notes_upserted;
-        total_result.stale_discussions_removed += result.stale_discussions_removed;
-    }
-
-    debug!(
-        issues_processed = issues.len(),
-        discussions_fetched = total_result.discussions_fetched,
-        discussions_upserted = total_result.discussions_upserted,
-        notes_upserted = total_result.notes_upserted,
-        stale_removed = total_result.stale_discussions_removed,
-        "Discussion ingestion complete"
-    );
-
-    Ok(total_result)
+#[derive(Debug)]
+pub struct PrefetchedIssueDiscussions {
+    pub issue: IssueForDiscussionSync,
+    pub discussions: Vec<PrefetchedDiscussion>,
+    pub fetch_error: Option<String>,
 }
 
-async fn ingest_discussions_for_issue(
-    conn: &Connection,
+#[derive(Debug)]
+pub struct PrefetchedDiscussion {
+    pub raw: GitLabDiscussion,
+    pub normalized: NormalizedDiscussion,
+    pub notes: Vec<NormalizedNote>,
+}
+
+/// Prefetch all discussions for an issue (HTTP only, no DB writes).
+/// This function is designed to be called concurrently via `join_all`.
+pub async fn prefetch_issue_discussions(
     client: &GitLabClient,
-    config: &Config,
     gitlab_project_id: i64,
     local_project_id: i64,
-    issue: &IssueForDiscussionSync,
-) -> Result<IngestDiscussionsResult> {
-    let mut result = IngestDiscussionsResult::default();
+    issue: IssueForDiscussionSync,
+) -> PrefetchedIssueDiscussions {
+    debug!(issue_iid = issue.iid, "Prefetching discussions for issue");
 
-    debug!(
-        issue_iid = issue.iid,
-        local_issue_id = issue.local_issue_id,
-        "Fetching discussions for issue"
-    );
+    let raw_discussions = match client
+        .fetch_all_issue_discussions(gitlab_project_id, issue.iid)
+        .await
+    {
+        Ok(d) => d,
+        Err(e) => {
+            return PrefetchedIssueDiscussions {
+                issue,
+                discussions: Vec::new(),
+                fetch_error: Some(e.to_string()),
+            };
+        }
+    };
 
-    let mut discussions_stream = client.paginate_issue_discussions(gitlab_project_id, issue.iid);
-
-    let mut seen_discussion_ids: Vec<String> = Vec::new();
-    let mut pagination_error: Option<crate::core::error::LoreError> = None;
-
-    let run_seen_at = now_ms();
-
-    while let Some(disc_result) = discussions_stream.next().await {
-        let gitlab_discussion = match disc_result {
-            Ok(d) => d,
-            Err(e) => {
-                warn!(
-                    issue_iid = issue.iid,
-                    error = %e,
-                    "Error during discussion pagination, skipping stale removal"
-                );
-                pagination_error = Some(e);
-                break;
-            }
-        };
-        result.discussions_fetched += 1;
-
-        let payload_bytes = serde_json::to_vec(&gitlab_discussion)?;
+    let mut discussions = Vec::with_capacity(raw_discussions.len());
 
+    for raw in raw_discussions {
         let normalized = transform_discussion(
-            &gitlab_discussion,
+            &raw,
             local_project_id,
             NoteableRef::Issue(issue.local_issue_id),
         );
+        let notes = transform_notes(&raw, local_project_id);
+
+        discussions.push(PrefetchedDiscussion {
+            raw,
+            normalized,
+            notes,
+        });
+    }
+
+    PrefetchedIssueDiscussions {
+        issue,
+        discussions,
+        fetch_error: None,
+    }
+}
+
+/// Write prefetched discussions to the database (sequential DB writes).
+pub fn write_prefetched_issue_discussions(
+    conn: &Connection,
+    config: &Config,
+    local_project_id: i64,
+    prefetched: PrefetchedIssueDiscussions,
+) -> Result<IngestDiscussionsResult> {
+    let mut result = IngestDiscussionsResult::default();
+    let issue = &prefetched.issue;
+
+    if let Some(error) = &prefetched.fetch_error {
+        warn!(issue_iid = issue.iid, error = %error, "Prefetch failed for issue");
+        return Ok(result);
+    }
+
+    let run_seen_at = now_ms();
+    let mut seen_discussion_ids: Vec<String> = Vec::with_capacity(prefetched.discussions.len());
+
+    for disc in &prefetched.discussions {
+        result.discussions_fetched += 1;
+        let notes_count = disc.notes.len();
 
         let tx = conn.unchecked_transaction()?;
 
+        let payload_bytes = serde_json::to_vec(&disc.raw)?;
         let payload_id = store_payload(
             &tx,
             StorePayloadOptions {
                 project_id: Some(local_project_id),
                 resource_type: "discussion",
-                gitlab_id: &gitlab_discussion.id,
+                gitlab_id: &disc.raw.id,
                 json_bytes: &payload_bytes,
                 compress: config.storage.compress_raw_payloads,
             },
         )?;
 
-        upsert_discussion(&tx, &normalized, payload_id)?;
+        upsert_discussion(&tx, &disc.normalized, payload_id)?;
 
         let local_discussion_id: i64 = tx.query_row(
             "SELECT id FROM discussions WHERE project_id = ? AND gitlab_discussion_id = ?",
-            (local_project_id, &normalized.gitlab_discussion_id),
+            (local_project_id, &disc.normalized.gitlab_discussion_id),
             |row| row.get(0),
         )?;
 
@@ -147,12 +151,8 @@ async fn ingest_discussions_for_issue(
             params![now_ms(), local_discussion_id],
         )?;
 
-        let notes = transform_notes(&gitlab_discussion, local_project_id);
-        let notes_count = notes.len();
-
-        for note in notes {
-            let outcome =
-                upsert_note_for_issue(&tx, local_discussion_id, &note, run_seen_at, None)?;
+        for note in &disc.notes {
+            let outcome = upsert_note_for_issue(&tx, local_discussion_id, note, run_seen_at, None)?;
             if !note.is_system && outcome.changed_semantics {
                 dirty_tracker::mark_dirty_tx(&tx, SourceType::Note, outcome.local_note_id)?;
             }
@@ -164,26 +164,22 @@ async fn ingest_discussions_for_issue(
 
         result.discussions_upserted += 1;
         result.notes_upserted += notes_count;
-        seen_discussion_ids.push(normalized.gitlab_discussion_id.clone());
+        seen_discussion_ids.push(disc.normalized.gitlab_discussion_id.clone());
     }
 
-    if pagination_error.is_none() {
-        let removed = remove_stale_discussions(conn, issue.local_issue_id, &seen_discussion_ids)?;
-        result.stale_discussions_removed = removed;
+    // Only do stale removal if fetch succeeded
+    let removed = remove_stale_discussions(conn, issue.local_issue_id, &seen_discussion_ids)?;
+    result.stale_discussions_removed = removed;
 
-        update_issue_sync_timestamp(conn, issue.local_issue_id, issue.updated_at)?;
-    } else if let Some(err) = pagination_error {
-        warn!(
-            issue_iid = issue.iid,
-            discussions_seen = seen_discussion_ids.len(),
-            "Skipping stale removal due to pagination error"
-        );
-        return Err(err);
-    }
+    update_issue_sync_timestamp(conn, issue.local_issue_id, issue.updated_at)?;
 
     Ok(result)
 }
 
+// ═══════════════════════════════════════════════════════════════════════
+//  Database helpers
+// ═══════════════════════════════════════════════════════════════════════
+
 fn upsert_discussion(
     conn: &Connection,
     discussion: &crate::gitlab::transformers::NormalizedDiscussion,

src/ingestion/issues.rs

@@ -140,7 +140,7 @@ fn passes_cursor_filter_with_ts(gitlab_id: i64, issue_ts: i64, cursor: &SyncCurs
     true
 }
 
-fn process_single_issue(
+pub(crate) fn process_single_issue(
     conn: &Connection,
     config: &Config,
     project_id: i64,

src/ingestion/merge_requests.rs

@@ -135,13 +135,13 @@ pub async fn ingest_merge_requests(
     Ok(result)
 }
 
-struct ProcessMrResult {
-    labels_created: usize,
-    assignees_linked: usize,
-    reviewers_linked: usize,
+pub(crate) struct ProcessMrResult {
+    pub(crate) labels_created: usize,
+    pub(crate) assignees_linked: usize,
+    pub(crate) reviewers_linked: usize,
 }
 
-fn process_single_mr(
+pub(crate) fn process_single_mr(
     conn: &Connection,
     config: &Config,
     project_id: i64,

src/ingestion/mod.rs

@@ -6,8 +6,11 @@ pub mod merge_requests;
 pub mod mr_diffs;
 pub mod mr_discussions;
 pub mod orchestrator;
+pub(crate) mod surgical;
 
-pub use discussions::{IngestDiscussionsResult, ingest_issue_discussions};
+pub use discussions::{
+    IngestDiscussionsResult, prefetch_issue_discussions, write_prefetched_issue_discussions,
+};
 pub use issues::{IngestIssuesResult, IssueForDiscussionSync, ingest_issues};
 pub use merge_requests::{
     IngestMergeRequestsResult, MrForDiscussionSync, get_mrs_needing_discussion_sync,

src/ingestion/orchestrator.rs

@@ -13,7 +13,7 @@ use crate::core::references::{
 use crate::core::shutdown::ShutdownSignal;
 use crate::gitlab::GitLabClient;
 
-use super::discussions::ingest_issue_discussions;
+use super::discussions::{prefetch_issue_discussions, write_prefetched_issue_discussions};
 use super::issues::{IssueForDiscussionSync, ingest_issues};
 use super::merge_requests::{
     MrForDiscussionSync, get_mrs_needing_discussion_sync, ingest_merge_requests,
@@ -130,6 +130,12 @@ pub async fn ingest_project_issues_with_progress(
     progress: Option<ProgressCallback>,
     signal: &ShutdownSignal,
 ) -> Result<IngestProjectResult> {
+    // Reclaim stale locks once at entry, not per-drain-function
+    let reclaimed = reclaim_stale_locks(conn, config.sync.stale_lock_minutes)?;
+    if reclaimed > 0 {
+        debug!(reclaimed, "Reclaimed stale locks at issue sync start");
+    }
+
     let mut result = IngestProjectResult::default();
     let emit = |event: ProgressEvent| {
         if let Some(ref cb) = progress {
@@ -176,7 +182,7 @@ pub async fn ingest_project_issues_with_progress(
             None => {
                 warn!("Cannot enrich statuses: project path not found for project_id={project_id}");
                 result.status_enrichment_error = Some("project_path_missing".into());
-                result.status_enrichment_mode = "fetched".into();
+                result.status_enrichment_mode = "error".into();
                 emit(ProgressEvent::StatusEnrichmentComplete {
                     enriched: 0,
                     cleared: 0,
@@ -260,7 +266,7 @@ pub async fn ingest_project_issues_with_progress(
                     Err(e) => {
                         warn!("Status enrichment fetch failed: {e}");
                         result.status_enrichment_error = Some(e.to_string());
-                        result.status_enrichment_mode = "fetched".into();
+                        result.status_enrichment_mode = "fetch_error".into();
                         emit(ProgressEvent::StatusEnrichmentComplete {
                             enriched: 0,
                             cleared: 0,
@@ -460,31 +466,35 @@ async fn sync_discussions_sequential(
     progress: &Option<ProgressCallback>,
     signal: &ShutdownSignal,
 ) -> Result<Vec<super::discussions::IngestDiscussionsResult>> {
-    let batch_size = config.sync.dependent_concurrency as usize;
+    // Guard against batch_size == 0 which would panic in .chunks()
+    let batch_size = (config.sync.dependent_concurrency as usize).max(1);
     let total = issues.len();
 
     let mut results = Vec::with_capacity(issues.len());
+    let mut processed = 0;
 
     for chunk in issues.chunks(batch_size) {
         if signal.is_cancelled() {
             debug!("Shutdown requested during discussion sync, returning partial results");
             break;
         }
-        for issue in chunk {
-            let disc_result = ingest_issue_discussions(
-                conn,
-                client,
-                config,
-                gitlab_project_id,
-                local_project_id,
-                std::slice::from_ref(issue),
-            )
-            .await?;
+
+        // Concurrent HTTP prefetch for all issues in this batch
+        let prefetch_futures = chunk.iter().map(|issue| {
+            prefetch_issue_discussions(client, gitlab_project_id, local_project_id, issue.clone())
+        });
+        let prefetched_batch = join_all(prefetch_futures).await;
+
+        // Sequential DB writes
+        for prefetched in prefetched_batch {
+            let disc_result =
+                write_prefetched_issue_discussions(conn, config, local_project_id, prefetched)?;
             results.push(disc_result);
+            processed += 1;
 
             if let Some(cb) = progress {
                 cb(ProgressEvent::DiscussionSynced {
-                    current: results.len(),
+                    current: processed,
                     total,
                 });
             }
@@ -531,6 +541,12 @@ pub async fn ingest_project_merge_requests_with_progress(
     progress: Option<ProgressCallback>,
     signal: &ShutdownSignal,
 ) -> Result<IngestMrProjectResult> {
+    // Reclaim stale locks once at entry, not per-drain-function
+    let reclaimed = reclaim_stale_locks(conn, config.sync.stale_lock_minutes)?;
+    if reclaimed > 0 {
+        debug!(reclaimed, "Reclaimed stale locks at MR sync start");
+    }
+
     let mut result = IngestMrProjectResult::default();
     let emit = |event: ProgressEvent| {
         if let Some(ref cb) = progress {
@@ -766,7 +782,8 @@ async fn sync_mr_discussions_sequential(
     progress: &Option<ProgressCallback>,
     signal: &ShutdownSignal,
 ) -> Result<Vec<super::mr_discussions::IngestMrDiscussionsResult>> {
-    let batch_size = config.sync.dependent_concurrency as usize;
+    // Guard against batch_size == 0 which would panic in .chunks()
+    let batch_size = (config.sync.dependent_concurrency as usize).max(1);
     let total = mrs.len();
 
     let mut results = Vec::with_capacity(mrs.len());
@@ -941,10 +958,7 @@ async fn drain_resource_events(
     let mut result = DrainResult::default();
     let batch_size = config.sync.dependent_concurrency as usize;
 
-    let reclaimed = reclaim_stale_locks(conn, config.sync.stale_lock_minutes)?;
-    if reclaimed > 0 {
-        debug!(reclaimed, "Reclaimed stale resource event locks");
-    }
+    // Note: stale locks are reclaimed once at sync entry point, not here
 
     let claimable_counts = count_claimable_jobs(conn, project_id)?;
     let total_pending = claimable_counts
@@ -1097,7 +1111,7 @@ async fn drain_resource_events(
 }
 
 /// Store resource events using the provided connection (caller manages the transaction).
-fn store_resource_events(
+pub(crate) fn store_resource_events(
     conn: &Connection,
     project_id: i64,
     entity_type: &str,
@@ -1263,10 +1277,7 @@ async fn drain_mr_closes_issues(
     let mut result = DrainResult::default();
     let batch_size = config.sync.dependent_concurrency as usize;
 
-    let reclaimed = reclaim_stale_locks(conn, config.sync.stale_lock_minutes)?;
-    if reclaimed > 0 {
-        debug!(reclaimed, "Reclaimed stale mr_closes_issues locks");
-    }
+    // Note: stale locks are reclaimed once at sync entry point, not here
 
     let claimable_counts = count_claimable_jobs(conn, project_id)?;
     let total_pending = claimable_counts
@@ -1406,7 +1417,7 @@ async fn drain_mr_closes_issues(
     Ok(result)
 }
 
-fn store_closes_issues_refs(
+pub(crate) fn store_closes_issues_refs(
     conn: &Connection,
     project_id: i64,
     mr_local_id: i64,
@@ -1523,10 +1534,7 @@ async fn drain_mr_diffs(
     let mut result = DrainResult::default();
     let batch_size = config.sync.dependent_concurrency as usize;
 
-    let reclaimed = reclaim_stale_locks(conn, config.sync.stale_lock_minutes)?;
-    if reclaimed > 0 {
-        debug!(reclaimed, "Reclaimed stale mr_diffs locks");
-    }
+    // Note: stale locks are reclaimed once at sync entry point, not here
 
     let claimable_counts = count_claimable_jobs(conn, project_id)?;
     let total_pending = claimable_counts.get("mr_diffs").copied().unwrap_or(0);

src/ingestion/surgical.rs

@@ -0,0 +1,464 @@
+use futures::stream::StreamExt;
+use rusqlite::Connection;
+use rusqlite::OptionalExtension;
+use tracing::{debug, warn};
+
+use crate::Config;
+use crate::core::error::{LoreError, Result};
+use crate::documents::SourceType;
+use crate::gitlab::GitLabClient;
+use crate::gitlab::types::{GitLabIssue, GitLabMergeRequest};
+use crate::ingestion::dirty_tracker;
+use crate::ingestion::discussions::{
+    prefetch_issue_discussions, write_prefetched_issue_discussions,
+};
+use crate::ingestion::issues::{IssueForDiscussionSync, process_single_issue};
+use crate::ingestion::merge_requests::{MrForDiscussionSync, process_single_mr};
+use crate::ingestion::mr_diffs::upsert_mr_file_changes;
+use crate::ingestion::mr_discussions::ingest_mr_discussions;
+use crate::ingestion::orchestrator::{store_closes_issues_refs, store_resource_events};
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+#[derive(Debug)]
+pub(crate) struct IngestIssueResult {
+    pub skipped_stale: bool,
+    pub dirty_source_keys: Vec<(SourceType, i64)>,
+}
+
+#[derive(Debug)]
+pub(crate) struct IngestMrResult {
+    pub skipped_stale: bool,
+    pub dirty_source_keys: Vec<(SourceType, i64)>,
+}
+
+#[derive(Debug)]
+pub(crate) struct PreflightResult {
+    pub issues: Vec<GitLabIssue>,
+    pub merge_requests: Vec<GitLabMergeRequest>,
+    pub failures: Vec<PreflightFailure>,
+}
+
+#[derive(Debug)]
+pub(crate) struct PreflightFailure {
+    pub entity_type: String,
+    pub iid: i64,
+    pub error: LoreError,
+}
+
+// ---------------------------------------------------------------------------
+// TOCTOU guard
+// ---------------------------------------------------------------------------
+
+/// Returns `true` if the payload is stale (same age or older than what the DB
+/// already has). Returns `false` when the entity is new (no DB row) or when
+/// the payload is strictly newer.
+pub(crate) fn is_stale(payload_updated_at: &str, db_updated_at_ms: Option<i64>) -> Result<bool> {
+    let Some(db_ms) = db_updated_at_ms else {
+        return Ok(false);
+    };
+
+    let payload_ms = chrono::DateTime::parse_from_rfc3339(payload_updated_at)
+        .map(|dt| dt.timestamp_millis())
+        .map_err(|e| {
+            LoreError::Other(format!(
+                "Failed to parse timestamp '{}': {}",
+                payload_updated_at, e
+            ))
+        })?;
+
+    Ok(payload_ms <= db_ms)
+}
+
+// ---------------------------------------------------------------------------
+// Ingestion wrappers
+// ---------------------------------------------------------------------------
+
+/// Ingest a single issue by IID with TOCTOU guard and dirty marking.
+pub(crate) fn ingest_issue_by_iid(
+    conn: &Connection,
+    config: &Config,
+    project_id: i64,
+    issue: &GitLabIssue,
+) -> Result<IngestIssueResult> {
+    let db_updated_at = get_db_updated_at(conn, "issues", issue.iid, project_id)?;
+
+    if is_stale(&issue.updated_at, db_updated_at)? {
+        debug!(iid = issue.iid, "Skipping stale issue (TOCTOU guard)");
+        return Ok(IngestIssueResult {
+            skipped_stale: true,
+            dirty_source_keys: vec![],
+        });
+    }
+
+    process_single_issue(conn, config, project_id, issue)?;
+
+    let local_id: i64 = conn.query_row(
+        "SELECT id FROM issues WHERE project_id = ? AND iid = ?",
+        (project_id, issue.iid),
+        |row| row.get(0),
+    )?;
+
+    dirty_tracker::mark_dirty(conn, SourceType::Issue, local_id)?;
+
+    Ok(IngestIssueResult {
+        skipped_stale: false,
+        dirty_source_keys: vec![(SourceType::Issue, local_id)],
+    })
+}
+
+/// Ingest a single merge request by IID with TOCTOU guard and dirty marking.
+pub(crate) fn ingest_mr_by_iid(
+    conn: &Connection,
+    config: &Config,
+    project_id: i64,
+    mr: &GitLabMergeRequest,
+) -> Result<IngestMrResult> {
+    let db_updated_at = get_db_updated_at(conn, "merge_requests", mr.iid, project_id)?;
+
+    if is_stale(&mr.updated_at, db_updated_at)? {
+        debug!(iid = mr.iid, "Skipping stale MR (TOCTOU guard)");
+        return Ok(IngestMrResult {
+            skipped_stale: true,
+            dirty_source_keys: vec![],
+        });
+    }
+
+    process_single_mr(conn, config, project_id, mr)?;
+
+    let local_id: i64 = conn.query_row(
+        "SELECT id FROM merge_requests WHERE project_id = ? AND iid = ?",
+        (project_id, mr.iid),
+        |row| row.get(0),
+    )?;
+
+    dirty_tracker::mark_dirty(conn, SourceType::MergeRequest, local_id)?;
+
+    Ok(IngestMrResult {
+        skipped_stale: false,
+        dirty_source_keys: vec![(SourceType::MergeRequest, local_id)],
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Preflight fetch
+// ---------------------------------------------------------------------------
+
+/// Fetch specific issues and MRs by IID from GitLab. Collects successes and
+/// failures without aborting on individual 404s.
+///
+/// Requests are dispatched concurrently (up to 10 in-flight at once) to avoid
+/// sequential round-trip latency when syncing many IIDs.
+pub(crate) async fn preflight_fetch(
+    client: &GitLabClient,
+    gitlab_project_id: i64,
+    targets: &[(String, i64)],
+) -> PreflightResult {
+    /// Max concurrent HTTP requests during preflight.
+    const PREFLIGHT_CONCURRENCY: usize = 10;
+
+    #[allow(clippy::large_enum_variant)]
+    enum FetchOutcome {
+        Issue(std::result::Result<GitLabIssue, (String, i64, LoreError)>),
+        MergeRequest(std::result::Result<GitLabMergeRequest, (String, i64, LoreError)>),
+        UnknownType(String, i64),
+    }
+
+    let mut result = PreflightResult {
+        issues: Vec::new(),
+        merge_requests: Vec::new(),
+        failures: Vec::new(),
+    };
+
+    let mut stream = futures::stream::iter(targets.iter().map(|(entity_type, iid)| {
+        let entity_type = entity_type.clone();
+        let iid = *iid;
+        async move {
+            match entity_type.as_str() {
+                "issue" => FetchOutcome::Issue(
+                    client
+                        .get_issue_by_iid(gitlab_project_id, iid)
+                        .await
+                        .map_err(|e| (entity_type, iid, e)),
+                ),
+                "merge_request" => FetchOutcome::MergeRequest(
+                    client
+                        .get_mr_by_iid(gitlab_project_id, iid)
+                        .await
+                        .map_err(|e| (entity_type, iid, e)),
+                ),
+                _ => FetchOutcome::UnknownType(entity_type, iid),
+            }
+        }
+    }))
+    .buffer_unordered(PREFLIGHT_CONCURRENCY);
+
+    while let Some(outcome) = stream.next().await {
+        match outcome {
+            FetchOutcome::Issue(Ok(issue)) => result.issues.push(issue),
+            FetchOutcome::Issue(Err((et, iid, e))) => {
+                result.failures.push(PreflightFailure {
+                    entity_type: et,
+                    iid,
+                    error: e,
+                });
+            }
+            FetchOutcome::MergeRequest(Ok(mr)) => result.merge_requests.push(mr),
+            FetchOutcome::MergeRequest(Err((et, iid, e))) => {
+                result.failures.push(PreflightFailure {
+                    entity_type: et,
+                    iid,
+                    error: e,
+                });
+            }
+            FetchOutcome::UnknownType(et, iid) => {
+                result.failures.push(PreflightFailure {
+                    entity_type: et.clone(),
+                    iid,
+                    error: LoreError::Other(format!("Unknown entity type: {et}")),
+                });
+            }
+        }
+    }
+
+    result
+}
+
+// ---------------------------------------------------------------------------
+// Dependent fetch helpers (surgical mode)
+// ---------------------------------------------------------------------------
+
+/// Counts returned from fetching dependents for a single entity.
+#[derive(Debug, Default)]
+pub(crate) struct DependentFetchResult {
+    pub resource_events_fetched: usize,
+    pub discussions_fetched: usize,
+    pub closes_issues_stored: usize,
+    pub file_changes_stored: usize,
+}
+
+/// Fetch and store all dependents for a single issue:
+/// resource events (state, label, milestone) and discussions.
+pub(crate) async fn fetch_dependents_for_issue(
+    client: &GitLabClient,
+    conn: &Connection,
+    project_id: i64,
+    gitlab_project_id: i64,
+    iid: i64,
+    local_id: i64,
+    config: &Config,
+) -> Result<DependentFetchResult> {
+    let mut result = DependentFetchResult::default();
+
+    // --- Resource events ---
+    match client
+        .fetch_all_resource_events(gitlab_project_id, "issue", iid)
+        .await
+    {
+        Ok((state_events, label_events, milestone_events)) => {
+            let count = state_events.len() + label_events.len() + milestone_events.len();
+            let tx = conn.unchecked_transaction()?;
+            store_resource_events(
+                &tx,
+                project_id,
+                "issue",
+                local_id,
+                &state_events,
+                &label_events,
+                &milestone_events,
+            )?;
+            tx.execute(
+                "UPDATE issues SET resource_events_synced_for_updated_at = updated_at WHERE id = ?",
+                [local_id],
+            )?;
+            tx.commit()?;
+            result.resource_events_fetched = count;
+        }
+        Err(e) => {
+            warn!(
+                iid,
+                error = %e,
+                "Failed to fetch resource events for issue, continuing"
+            );
+        }
+    }
+
+    // --- Discussions ---
+    let sync_item = IssueForDiscussionSync {
+        local_issue_id: local_id,
+        iid,
+        updated_at: 0, // not used for filtering in surgical mode
+    };
+    let prefetched =
+        prefetch_issue_discussions(client, gitlab_project_id, project_id, sync_item).await;
+    match write_prefetched_issue_discussions(conn, config, project_id, prefetched) {
+        Ok(disc_result) => {
+            result.discussions_fetched = disc_result.discussions_fetched;
+        }
+        Err(e) => {
+            warn!(
+                iid,
+                error = %e,
+                "Failed to ingest discussions for issue, continuing"
+            );
+        }
+    }
+
+    Ok(result)
+}
+
+/// Fetch and store all dependents for a single merge request:
+/// resource events, discussions, closes-issues references, and file changes (diffs).
+pub(crate) async fn fetch_dependents_for_mr(
+    client: &GitLabClient,
+    conn: &Connection,
+    project_id: i64,
+    gitlab_project_id: i64,
+    iid: i64,
+    local_id: i64,
+    config: &Config,
+) -> Result<DependentFetchResult> {
+    let mut result = DependentFetchResult::default();
+
+    // --- Resource events ---
+    match client
+        .fetch_all_resource_events(gitlab_project_id, "merge_request", iid)
+        .await
+    {
+        Ok((state_events, label_events, milestone_events)) => {
+            let count = state_events.len() + label_events.len() + milestone_events.len();
+            let tx = conn.unchecked_transaction()?;
+            store_resource_events(
+                &tx,
+                project_id,
+                "merge_request",
+                local_id,
+                &state_events,
+                &label_events,
+                &milestone_events,
+            )?;
+            tx.execute(
+                "UPDATE merge_requests SET resource_events_synced_for_updated_at = updated_at WHERE id = ?",
+                [local_id],
+            )?;
+            tx.commit()?;
+            result.resource_events_fetched = count;
+        }
+        Err(e) => {
+            warn!(
+                iid,
+                error = %e,
+                "Failed to fetch resource events for MR, continuing"
+            );
+        }
+    }
+
+    // --- Discussions ---
+    let sync_item = MrForDiscussionSync {
+        local_mr_id: local_id,
+        iid,
+        updated_at: 0,
+    };
+    match ingest_mr_discussions(
+        conn,
+        client,
+        config,
+        gitlab_project_id,
+        project_id,
+        &[sync_item],
+    )
+    .await
+    {
+        Ok(disc_result) => {
+            result.discussions_fetched = disc_result.discussions_fetched;
+        }
+        Err(e) => {
+            warn!(
+                iid,
+                error = %e,
+                "Failed to ingest discussions for MR, continuing"
+            );
+        }
+    }
+
+    // --- Closes issues ---
+    match client.fetch_mr_closes_issues(gitlab_project_id, iid).await {
+        Ok(closes_issues) => {
+            let count = closes_issues.len();
+            let tx = conn.unchecked_transaction()?;
+            store_closes_issues_refs(&tx, project_id, local_id, &closes_issues)?;
+            tx.execute(
+                "UPDATE merge_requests SET closes_issues_synced_for_updated_at = updated_at WHERE id = ?",
+                [local_id],
+            )?;
+            tx.commit()?;
+            result.closes_issues_stored = count;
+        }
+        Err(e) => {
+            warn!(
+                iid,
+                error = %e,
+                "Failed to fetch closes_issues for MR, continuing"
+            );
+        }
+    }
+
+    // --- File changes (diffs) ---
+    match client.fetch_mr_diffs(gitlab_project_id, iid).await {
+        Ok(diffs) => {
+            let tx = conn.unchecked_transaction()?;
+            let stored = upsert_mr_file_changes(&tx, local_id, project_id, &diffs)?;
+            tx.execute(
+                "UPDATE merge_requests SET diffs_synced_for_updated_at = updated_at WHERE id = ?",
+                [local_id],
+            )?;
+            tx.commit()?;
+            result.file_changes_stored = stored;
+        }
+        Err(e) => {
+            warn!(
+                iid,
+                error = %e,
+                "Failed to fetch diffs for MR, continuing"
+            );
+        }
+    }
+
+    Ok(result)
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+fn get_db_updated_at(
+    conn: &Connection,
+    table: &str,
+    iid: i64,
+    project_id: i64,
+) -> Result<Option<i64>> {
+    // Using a match on known table names avoids SQL injection from the table parameter.
+    let sql = match table {
+        "issues" => "SELECT updated_at FROM issues WHERE project_id = ?1 AND iid = ?2",
+        "merge_requests" => {
+            "SELECT updated_at FROM merge_requests WHERE project_id = ?1 AND iid = ?2"
+        }
+        _ => {
+            return Err(LoreError::Other(format!(
+                "Unknown table for updated_at lookup: {table}"
+            )));
+        }
+    };
+
+    let result: Option<i64> = conn
+        .query_row(sql, (project_id, iid), |row| row.get(0))
+        .optional()?;
+
+    Ok(result)
+}
+
+#[cfg(test)]
+#[path = "surgical_tests.rs"]
+mod tests;

src/ingestion/surgical_tests.rs

@@ -0,0 +1,640 @@
+use std::path::Path;
+
+use super::*;
+use crate::core::config::{
+    Config, EmbeddingConfig, GitLabConfig, LoggingConfig, ProjectConfig, ScoringConfig,
+    StorageConfig, SyncConfig,
+};
+use crate::core::db::{create_connection, run_migrations};
+use crate::gitlab::types::{GitLabAuthor, GitLabMergeRequest};
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+fn setup_db() -> rusqlite::Connection {
+    let conn = create_connection(Path::new(":memory:")).expect("in-memory DB");
+    run_migrations(&conn).expect("migrations");
+    conn.execute(
+        "INSERT INTO projects (gitlab_project_id, path_with_namespace, web_url)
+         VALUES (100, 'group/repo', 'https://example.com/group/repo')",
+        [],
+    )
+    .expect("insert project");
+    conn
+}
+
+fn test_config() -> Config {
+    Config {
+        gitlab: GitLabConfig {
+            base_url: "https://gitlab.example.com".to_string(),
+            token_env_var: "GITLAB_TOKEN".to_string(),
+            token: None,
+            username: None,
+        },
+        projects: vec![ProjectConfig {
+            path: "group/repo".to_string(),
+        }],
+        default_project: None,
+        sync: SyncConfig::default(),
+        storage: StorageConfig::default(),
+        embedding: EmbeddingConfig::default(),
+        logging: LoggingConfig::default(),
+        scoring: ScoringConfig::default(),
+    }
+}
+
+fn make_test_issue(iid: i64, updated_at: &str) -> GitLabIssue {
+    GitLabIssue {
+        id: iid * 1000, // unique gitlab_id
+        iid,
+        project_id: 100,
+        title: format!("Test issue {iid}"),
+        description: Some("Description".to_string()),
+        state: "opened".to_string(),
+        created_at: "2026-01-01T00:00:00.000+00:00".to_string(),
+        updated_at: updated_at.to_string(),
+        closed_at: None,
+        author: GitLabAuthor {
+            id: 1,
+            username: "testuser".to_string(),
+            name: "Test User".to_string(),
+        },
+        assignees: vec![],
+        labels: vec![],
+        milestone: None,
+        due_date: None,
+        web_url: format!("https://example.com/group/repo/-/issues/{iid}"),
+    }
+}
+
+fn make_test_mr(iid: i64, updated_at: &str) -> GitLabMergeRequest {
+    GitLabMergeRequest {
+        id: iid * 1000,
+        iid,
+        project_id: 100,
+        title: format!("Test MR {iid}"),
+        description: Some("MR description".to_string()),
+        state: "opened".to_string(),
+        draft: false,
+        work_in_progress: false,
+        source_branch: "feature".to_string(),
+        target_branch: "main".to_string(),
+        sha: Some("abc123".to_string()),
+        references: None,
+        detailed_merge_status: None,
+        merge_status_legacy: None,
+        created_at: "2026-01-01T00:00:00.000+00:00".to_string(),
+        updated_at: updated_at.to_string(),
+        merged_at: None,
+        closed_at: None,
+        author: GitLabAuthor {
+            id: 1,
+            username: "testuser".to_string(),
+            name: "Test User".to_string(),
+        },
+        merge_user: None,
+        merged_by: None,
+        labels: vec![],
+        assignees: vec![],
+        reviewers: vec![],
+        web_url: format!("https://example.com/group/repo/-/merge_requests/{iid}"),
+        merge_commit_sha: None,
+        squash_commit_sha: None,
+    }
+}
+
+fn get_db_updated_at_helper(conn: &rusqlite::Connection, table: &str, iid: i64) -> Option<i64> {
+    let sql = match table {
+        "issues" => "SELECT updated_at FROM issues WHERE project_id = 1 AND iid = ?1",
+        "merge_requests" => {
+            "SELECT updated_at FROM merge_requests WHERE project_id = 1 AND iid = ?1"
+        }
+        _ => return None,
+    };
+    conn.query_row(sql, [iid], |row| row.get(0)).ok()
+}
+
+fn get_dirty_keys(conn: &rusqlite::Connection) -> Vec<(String, i64)> {
+    let mut stmt = conn
+        .prepare("SELECT source_type, source_id FROM dirty_sources ORDER BY source_type, source_id")
+        .expect("prepare dirty_sources query");
+    stmt.query_map([], |row| {
+        let st: String = row.get(0)?;
+        let id: i64 = row.get(1)?;
+        Ok((st, id))
+    })
+    .expect("query dirty_sources")
+    .collect::<std::result::Result<Vec<_>, _>>()
+    .expect("collect dirty_sources")
+}
+
+// ---------------------------------------------------------------------------
+// is_stale unit tests
+// ---------------------------------------------------------------------------
+
+#[test]
+fn test_is_stale_parses_iso8601() {
+    // 2026-02-17T12:00:00.000+00:00 -> 1771243200000 ms
+    let result = is_stale("2026-02-17T12:00:00.000+00:00", Some(1_771_329_600_000));
+    assert!(result.is_ok());
+    // Same timestamp => stale
+    assert!(result.unwrap());
+}
+
+#[test]
+fn test_is_stale_handles_none_db_value() {
+    let result = is_stale("2026-02-17T12:00:00.000+00:00", None);
+    assert!(result.is_ok());
+    assert!(!result.unwrap(), "no DB row means not stale");
+}
+
+#[test]
+fn test_is_stale_with_z_suffix() {
+    let result = is_stale("2026-02-17T12:00:00Z", Some(1_771_329_600_000));
+    assert!(result.is_ok());
+    assert!(result.unwrap(), "Z suffix should parse same as +00:00");
+}
+
+// ---------------------------------------------------------------------------
+// Issue ingestion tests
+// ---------------------------------------------------------------------------
+
+#[test]
+fn test_ingest_issue_by_iid_upserts_and_marks_dirty() {
+    let conn = setup_db();
+    let config = test_config();
+    let issue = make_test_issue(42, "2026-02-17T12:00:00.000+00:00");
+
+    let result = ingest_issue_by_iid(&conn, &config, 1, &issue).unwrap();
+
+    assert!(!result.skipped_stale);
+    assert!(!result.dirty_source_keys.is_empty());
+
+    // Verify DB row exists
+    let db_ts = get_db_updated_at_helper(&conn, "issues", 42);
+    assert!(db_ts.is_some(), "issue should exist in DB");
+
+    // Verify dirty marking
+    let dirty = get_dirty_keys(&conn);
+    assert!(
+        dirty.iter().any(|(t, _)| t == "issue"),
+        "dirty_sources should contain an issue entry"
+    );
+}
+
+#[test]
+fn test_toctou_skips_stale_issue() {
+    let conn = setup_db();
+    let config = test_config();
+    let issue = make_test_issue(42, "2026-02-17T12:00:00.000+00:00");
+
+    // First ingest succeeds
+    let r1 = ingest_issue_by_iid(&conn, &config, 1, &issue).unwrap();
+    assert!(!r1.skipped_stale);
+
+    // Clear dirty to check second ingest doesn't re-mark
+    conn.execute("DELETE FROM dirty_sources", []).unwrap();
+
+    // Second ingest with same timestamp should be skipped
+    let r2 = ingest_issue_by_iid(&conn, &config, 1, &issue).unwrap();
+    assert!(r2.skipped_stale);
+    assert!(r2.dirty_source_keys.is_empty());
+
+    // No new dirty mark
+    let dirty = get_dirty_keys(&conn);
+    assert!(dirty.is_empty(), "stale skip should not create dirty marks");
+}
+
+#[test]
+fn test_toctou_allows_newer_issue() {
+    let conn = setup_db();
+    let config = test_config();
+
+    // Ingest at T1
+    let issue_t1 = make_test_issue(42, "2026-02-17T12:00:00.000+00:00");
+    ingest_issue_by_iid(&conn, &config, 1, &issue_t1).unwrap();
+
+    conn.execute("DELETE FROM dirty_sources", []).unwrap();
+
+    // Ingest at T2 (newer) — should succeed
+    let issue_t2 = make_test_issue(42, "2026-02-17T13:00:00.000+00:00");
+    let result = ingest_issue_by_iid(&conn, &config, 1, &issue_t2).unwrap();
+
+    assert!(!result.skipped_stale);
+}
+
+#[test]
+fn test_ingest_issue_returns_dirty_source_keys() {
+    let conn = setup_db();
+    let config = test_config();
+    let issue = make_test_issue(42, "2026-02-17T12:00:00.000+00:00");
+
+    let result = ingest_issue_by_iid(&conn, &config, 1, &issue).unwrap();
+
+    assert_eq!(result.dirty_source_keys.len(), 1);
+    let (source_type, local_id) = &result.dirty_source_keys[0];
+    assert_eq!(source_type.as_str(), "issue");
+    assert!(*local_id > 0, "local_id should be positive");
+}
+
+#[test]
+fn test_ingest_issue_updates_existing() {
+    let conn = setup_db();
+    let config = test_config();
+
+    let issue_v1 = make_test_issue(42, "2026-02-17T12:00:00.000+00:00");
+    ingest_issue_by_iid(&conn, &config, 1, &issue_v1).unwrap();
+
+    let ts1 = get_db_updated_at_helper(&conn, "issues", 42).unwrap();
+
+    // Newer version
+    let issue_v2 = make_test_issue(42, "2026-02-17T14:00:00.000+00:00");
+    let result = ingest_issue_by_iid(&conn, &config, 1, &issue_v2).unwrap();
+
+    assert!(!result.skipped_stale);
+    let ts2 = get_db_updated_at_helper(&conn, "issues", 42).unwrap();
+    assert!(ts2 > ts1, "DB timestamp should increase after update");
+}
+
+// ---------------------------------------------------------------------------
+// MR ingestion tests
+// ---------------------------------------------------------------------------
+
+#[test]
+fn test_ingest_mr_by_iid_upserts_and_marks_dirty() {
+    let conn = setup_db();
+    let config = test_config();
+    let mr = make_test_mr(101, "2026-02-17T12:00:00.000+00:00");
+
+    let result = ingest_mr_by_iid(&conn, &config, 1, &mr).unwrap();
+
+    assert!(!result.skipped_stale);
+    assert!(!result.dirty_source_keys.is_empty());
+
+    let db_ts = get_db_updated_at_helper(&conn, "merge_requests", 101);
+    assert!(db_ts.is_some(), "MR should exist in DB");
+
+    let dirty = get_dirty_keys(&conn);
+    assert!(
+        dirty.iter().any(|(t, _)| t == "merge_request"),
+        "dirty_sources should contain a merge_request entry"
+    );
+}
+
+#[test]
+fn test_toctou_skips_stale_mr() {
+    let conn = setup_db();
+    let config = test_config();
+    let mr = make_test_mr(101, "2026-02-17T12:00:00.000+00:00");
+
+    let r1 = ingest_mr_by_iid(&conn, &config, 1, &mr).unwrap();
+    assert!(!r1.skipped_stale);
+
+    conn.execute("DELETE FROM dirty_sources", []).unwrap();
+
+    let r2 = ingest_mr_by_iid(&conn, &config, 1, &mr).unwrap();
+    assert!(r2.skipped_stale);
+    assert!(r2.dirty_source_keys.is_empty());
+}
+
+#[test]
+fn test_toctou_allows_newer_mr() {
+    let conn = setup_db();
+    let config = test_config();
+
+    let mr_t1 = make_test_mr(101, "2026-02-17T12:00:00.000+00:00");
+    ingest_mr_by_iid(&conn, &config, 1, &mr_t1).unwrap();
+
+    conn.execute("DELETE FROM dirty_sources", []).unwrap();
+
+    let mr_t2 = make_test_mr(101, "2026-02-17T13:00:00.000+00:00");
+    let result = ingest_mr_by_iid(&conn, &config, 1, &mr_t2).unwrap();
+
+    assert!(!result.skipped_stale);
+}
+
+#[test]
+fn test_ingest_mr_returns_dirty_source_keys() {
+    let conn = setup_db();
+    let config = test_config();
+    let mr = make_test_mr(101, "2026-02-17T12:00:00.000+00:00");
+
+    let result = ingest_mr_by_iid(&conn, &config, 1, &mr).unwrap();
+
+    assert_eq!(result.dirty_source_keys.len(), 1);
+    let (source_type, local_id) = &result.dirty_source_keys[0];
+    assert_eq!(source_type.as_str(), "merge_request");
+    assert!(*local_id > 0);
+}
+
+#[test]
+fn test_ingest_mr_updates_existing() {
+    let conn = setup_db();
+    let config = test_config();
+
+    let mr_v1 = make_test_mr(101, "2026-02-17T12:00:00.000+00:00");
+    ingest_mr_by_iid(&conn, &config, 1, &mr_v1).unwrap();
+
+    let ts1 = get_db_updated_at_helper(&conn, "merge_requests", 101).unwrap();
+
+    let mr_v2 = make_test_mr(101, "2026-02-17T14:00:00.000+00:00");
+    let result = ingest_mr_by_iid(&conn, &config, 1, &mr_v2).unwrap();
+
+    assert!(!result.skipped_stale);
+    let ts2 = get_db_updated_at_helper(&conn, "merge_requests", 101).unwrap();
+    assert!(ts2 > ts1, "DB timestamp should increase after update");
+}
+
+// ---------------------------------------------------------------------------
+// Preflight fetch test (wiremock)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn test_preflight_fetch_returns_issues_and_mrs() {
+    use wiremock::matchers::{method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    let mock_server = MockServer::start().await;
+
+    // Issue fixture
+    let issue_json = serde_json::json!({
+        "id": 42000,
+        "iid": 42,
+        "project_id": 100,
+        "title": "Test issue 42",
+        "description": "desc",
+        "state": "opened",
+        "created_at": "2026-01-01T00:00:00.000+00:00",
+        "updated_at": "2026-02-17T12:00:00.000+00:00",
+        "author": {"id": 1, "username": "testuser", "name": "Test User"},
+        "assignees": [],
+        "labels": [],
+        "web_url": "https://example.com/group/repo/-/issues/42"
+    });
+
+    // MR fixture
+    let mr_json = serde_json::json!({
+        "id": 101000,
+        "iid": 101,
+        "project_id": 100,
+        "title": "Test MR 101",
+        "description": "mr desc",
+        "state": "opened",
+        "draft": false,
+        "work_in_progress": false,
+        "source_branch": "feature",
+        "target_branch": "main",
+        "sha": "abc123",
+        "created_at": "2026-01-01T00:00:00.000+00:00",
+        "updated_at": "2026-02-17T12:00:00.000+00:00",
+        "author": {"id": 1, "username": "testuser", "name": "Test User"},
+        "labels": [],
+        "assignees": [],
+        "reviewers": [],
+        "web_url": "https://example.com/group/repo/-/merge_requests/101"
+    });
+
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/100/issues/42"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(&issue_json))
+        .mount(&mock_server)
+        .await;
+
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/100/merge_requests/101"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(&mr_json))
+        .mount(&mock_server)
+        .await;
+
+    let client = GitLabClient::new(&mock_server.uri(), "test-token", None);
+    let targets = vec![
+        ("issue".to_string(), 42i64),
+        ("merge_request".to_string(), 101i64),
+    ];
+
+    let result = preflight_fetch(&client, 100, &targets).await;
+
+    assert_eq!(result.issues.len(), 1);
+    assert_eq!(result.issues[0].iid, 42);
+    assert_eq!(result.merge_requests.len(), 1);
+    assert_eq!(result.merge_requests[0].iid, 101);
+    assert!(result.failures.is_empty());
+}
+
+// ---------------------------------------------------------------------------
+// Dependent helper tests (bd-kanh)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn test_fetch_dependents_for_issue_empty_events() {
+    use wiremock::matchers::{method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    let mock_server = MockServer::start().await;
+    let conn = setup_db();
+    let config = test_config();
+
+    // Insert an issue so we have a local_id
+    let issue = make_test_issue(42, "2026-02-17T12:00:00.000+00:00");
+    ingest_issue_by_iid(&conn, &config, 1, &issue).unwrap();
+    let local_id: i64 = conn
+        .query_row(
+            "SELECT id FROM issues WHERE project_id = 1 AND iid = 42",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+
+    // Mock empty resource event endpoints
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/100/issues/42/resource_state_events"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/100/issues/42/resource_label_events"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+    Mock::given(method("GET"))
+        .and(path(
+            "/api/v4/projects/100/issues/42/resource_milestone_events",
+        ))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+
+    // Mock empty discussions endpoint
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/100/issues/42/discussions"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+
+    let client = GitLabClient::new(&mock_server.uri(), "test-token", None);
+
+    let result = fetch_dependents_for_issue(&client, &conn, 1, 100, 42, local_id, &config)
+        .await
+        .unwrap();
+
+    assert_eq!(result.resource_events_fetched, 0);
+    assert_eq!(result.discussions_fetched, 0);
+}
+
+#[tokio::test]
+async fn test_fetch_dependents_for_mr_empty_events() {
+    use wiremock::matchers::{method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    let mock_server = MockServer::start().await;
+    let conn = setup_db();
+    let config = test_config();
+
+    // Insert an MR so we have a local_id
+    let mr = make_test_mr(101, "2026-02-17T12:00:00.000+00:00");
+    ingest_mr_by_iid(&conn, &config, 1, &mr).unwrap();
+    let local_id: i64 = conn
+        .query_row(
+            "SELECT id FROM merge_requests WHERE project_id = 1 AND iid = 101",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+
+    // Mock empty resource event endpoints for MR
+    Mock::given(method("GET"))
+        .and(path(
+            "/api/v4/projects/100/merge_requests/101/resource_state_events",
+        ))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+    Mock::given(method("GET"))
+        .and(path(
+            "/api/v4/projects/100/merge_requests/101/resource_label_events",
+        ))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+    Mock::given(method("GET"))
+        .and(path(
+            "/api/v4/projects/100/merge_requests/101/resource_milestone_events",
+        ))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+
+    // Mock empty discussions endpoint for MR
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/100/merge_requests/101/discussions"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+
+    // Mock empty closes_issues endpoint
+    Mock::given(method("GET"))
+        .and(path(
+            "/api/v4/projects/100/merge_requests/101/closes_issues",
+        ))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+
+    // Mock empty diffs endpoint
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/100/merge_requests/101/diffs"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+
+    let client = GitLabClient::new(&mock_server.uri(), "test-token", None);
+
+    let result = fetch_dependents_for_mr(&client, &conn, 1, 100, 101, local_id, &config)
+        .await
+        .unwrap();
+
+    assert_eq!(result.resource_events_fetched, 0);
+    assert_eq!(result.discussions_fetched, 0);
+    assert_eq!(result.closes_issues_stored, 0);
+    assert_eq!(result.file_changes_stored, 0);
+}
+
+#[tokio::test]
+async fn test_fetch_dependents_for_mr_with_closes_issues() {
+    use wiremock::matchers::{method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    let mock_server = MockServer::start().await;
+    let conn = setup_db();
+    let config = test_config();
+
+    // Insert issue and MR so references can resolve
+    let issue = make_test_issue(42, "2026-02-17T12:00:00.000+00:00");
+    ingest_issue_by_iid(&conn, &config, 1, &issue).unwrap();
+
+    let mr = make_test_mr(101, "2026-02-17T12:00:00.000+00:00");
+    ingest_mr_by_iid(&conn, &config, 1, &mr).unwrap();
+    let mr_local_id: i64 = conn
+        .query_row(
+            "SELECT id FROM merge_requests WHERE project_id = 1 AND iid = 101",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+
+    // Mock empty resource events
+    for endpoint in [
+        "resource_state_events",
+        "resource_label_events",
+        "resource_milestone_events",
+    ] {
+        Mock::given(method("GET"))
+            .and(path(format!(
+                "/api/v4/projects/100/merge_requests/101/{endpoint}"
+            )))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+            .mount(&mock_server)
+            .await;
+    }
+
+    // Mock empty discussions
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/100/merge_requests/101/discussions"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+
+    // Mock closes_issues with one reference
+    Mock::given(method("GET"))
+        .and(path(
+            "/api/v4/projects/100/merge_requests/101/closes_issues",
+        ))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([
+            {
+                "id": 42000,
+                "iid": 42,
+                "project_id": 100,
+                "title": "Test issue 42",
+                "state": "opened",
+                "web_url": "https://example.com/group/repo/-/issues/42"
+            }
+        ])))
+        .mount(&mock_server)
+        .await;
+
+    // Mock empty diffs
+    Mock::given(method("GET"))
+        .and(path("/api/v4/projects/100/merge_requests/101/diffs"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([])))
+        .mount(&mock_server)
+        .await;
+
+    let client = GitLabClient::new(&mock_server.uri(), "test-token", None);
+
+    let result = fetch_dependents_for_mr(&client, &conn, 1, 100, 101, mr_local_id, &config)
+        .await
+        .unwrap();
+
+    assert_eq!(result.closes_issues_stored, 1);
+}

src/main.rs

@@ -11,26 +11,30 @@ use lore::cli::autocorrect::{self, CorrectionResult};
 use lore::cli::commands::{
     IngestDisplay, InitInputs, InitOptions, InitResult, ListFilters, MrListFilters,
     NoteListFilters, SearchCliFilters, SyncOptions, TimelineParams, open_issue_in_browser,
-    open_mr_in_browser, parse_trace_path, print_count, print_count_json, print_doctor_results,
-    print_drift_human, print_drift_json, print_dry_run_preview, print_dry_run_preview_json,
-    print_embed, print_embed_json, print_event_count, print_event_count_json, print_file_history,
-    print_file_history_json, print_generate_docs, print_generate_docs_json, print_ingest_summary,
-    print_ingest_summary_json, print_list_issues, print_list_issues_json, print_list_mrs,
-    print_list_mrs_json, print_list_notes, print_list_notes_csv, print_list_notes_json,
-    print_list_notes_jsonl, print_search_results, print_search_results_json, print_show_issue,
-    print_show_issue_json, print_show_mr, print_show_mr_json, print_stats, print_stats_json,
-    print_sync, print_sync_json, print_sync_status, print_sync_status_json, print_timeline,
-    print_timeline_json_with_meta, print_trace, print_trace_json, print_who_human, print_who_json,
-    query_notes, run_auth_test, run_count, run_count_events, run_doctor, run_drift, run_embed,
-    run_file_history, run_generate_docs, run_ingest, run_ingest_dry_run, run_init, run_list_issues,
-    run_list_mrs, run_search, run_show_issue, run_show_mr, run_stats, run_sync, run_sync_status,
-    run_timeline, run_who,
+    open_mr_in_browser, parse_trace_path, print_count, print_count_json, print_cron_install,
+    print_cron_install_json, print_cron_status, print_cron_status_json, print_cron_uninstall,
+    print_cron_uninstall_json, print_doctor_results, print_drift_human, print_drift_json,
+    print_dry_run_preview, print_dry_run_preview_json, print_embed, print_embed_json,
+    print_event_count, print_event_count_json, print_file_history, print_file_history_json,
+    print_generate_docs, print_generate_docs_json, print_ingest_summary, print_ingest_summary_json,
+    print_list_issues, print_list_issues_json, print_list_mrs, print_list_mrs_json,
+    print_list_notes, print_list_notes_json, print_related_human, print_related_json,
+    print_search_results, print_search_results_json, print_show_issue, print_show_issue_json,
+    print_show_mr, print_show_mr_json, print_stats, print_stats_json, print_sync, print_sync_json,
+    print_sync_status, print_sync_status_json, print_timeline, print_timeline_json_with_meta,
+    print_trace, print_trace_json, print_who_human, print_who_json, query_notes, run_auth_test,
+    run_count, run_count_events, run_cron_install, run_cron_status, run_cron_uninstall, run_doctor,
+    run_drift, run_embed, run_file_history, run_generate_docs, run_ingest, run_ingest_dry_run,
+    run_init, run_list_issues, run_list_mrs, run_me, run_related, run_search, run_show_issue,
+    run_show_mr, run_stats, run_sync, run_sync_status, run_timeline, run_token_set, run_token_show,
+    run_who,
 };
 use lore::cli::render::{ColorMode, GlyphMode, Icons, LoreRenderer, Theme};
 use lore::cli::robot::{RobotMeta, strip_schemas};
 use lore::cli::{
-    Cli, Commands, CountArgs, EmbedArgs, FileHistoryArgs, GenerateDocsArgs, IngestArgs, IssuesArgs,
-    MrsArgs, NotesArgs, SearchArgs, StatsArgs, SyncArgs, TimelineArgs, TraceArgs, WhoArgs,
+    Cli, Commands, CountArgs, CronAction, CronArgs, EmbedArgs, FileHistoryArgs, GenerateDocsArgs,
+    IngestArgs, IssuesArgs, MeArgs, MrsArgs, NotesArgs, SearchArgs, StatsArgs, SyncArgs,
+    TimelineArgs, TokenAction, TokenArgs, TraceArgs, WhoArgs,
 };
 use lore::core::db::{
     LATEST_SCHEMA_VERSION, create_connection, get_schema_version, run_migrations,
@@ -199,10 +203,13 @@ async fn main() {
             handle_timeline(cli.config.as_deref(), args, robot_mode).await
         }
         Some(Commands::Who(args)) => handle_who(cli.config.as_deref(), args, robot_mode),
+        Some(Commands::Me(args)) => handle_me(cli.config.as_deref(), args, robot_mode),
         Some(Commands::FileHistory(args)) => {
             handle_file_history(cli.config.as_deref(), args, robot_mode)
         }
         Some(Commands::Trace(args)) => handle_trace(cli.config.as_deref(), args, robot_mode),
+        Some(Commands::Cron(args)) => handle_cron(cli.config.as_deref(), args, robot_mode),
+        Some(Commands::Token(args)) => handle_token(cli.config.as_deref(), args, robot_mode).await,
         Some(Commands::Drift {
             entity_type,
             iid,
@@ -219,6 +226,22 @@ async fn main() {
             )
             .await
         }
+        Some(Commands::Related {
+            query_or_type,
+            iid,
+            limit,
+            project,
+        }) => {
+            handle_related(
+                cli.config.as_deref(),
+                &query_or_type,
+                iid,
+                limit,
+                project.as_deref(),
+                robot_mode,
+            )
+            .await
+        }
         Some(Commands::Stats(args)) => handle_stats(cli.config.as_deref(), args, robot_mode).await,
         Some(Commands::Embed(args)) => handle_embed(cli.config.as_deref(), args, robot_mode).await,
         Some(Commands::Sync(args)) => {
@@ -922,21 +945,14 @@ fn handle_notes(
 
     let result = query_notes(&conn, &filters, &config)?;
 
-    let format = if robot_mode && args.format == "table" {
-        "json"
-    } else {
-        &args.format
-    };
-
-    match format {
-        "json" => print_list_notes_json(
+    if robot_mode {
+        print_list_notes_json(
             &result,
             start.elapsed().as_millis() as u64,
             args.fields.as_deref(),
-        ),
-        "jsonl" => print_list_notes_jsonl(&result),
-        "csv" => print_list_notes_csv(&result),
-        _ => print_list_notes(&result),
+        );
+    } else {
+        print_list_notes(&result);
     }
 
     Ok(())
@@ -1642,6 +1658,7 @@ struct VersionOutput {
 
 #[derive(Serialize)]
 struct VersionData {
+    name: &'static str,
     version: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     git_hash: Option<String>,
@@ -1655,6 +1672,7 @@ fn handle_version(robot_mode: bool) -> Result<(), Box<dyn std::error::Error>> {
         let output = VersionOutput {
             ok: true,
             data: VersionData {
+                name: "lore",
                 version,
                 git_hash: if git_hash.is_empty() {
                     None
@@ -1995,7 +2013,7 @@ async fn handle_timeline(
     if robot_mode {
         print_timeline_json_with_meta(
             &result,
-            result.total_events_before_limit,
+            result.total_filtered_events,
             params.depth,
             !params.no_mentions,
             args.fields.as_deref(),
@@ -2155,6 +2173,14 @@ async fn handle_sync_cmd(
 ) -> Result<(), Box<dyn std::error::Error>> {
     let dry_run = args.dry_run && !args.no_dry_run;
 
+    // Dedup and sort IIDs
+    let mut issue_iids = args.issue;
+    let mut mr_iids = args.mr;
+    issue_iids.sort_unstable();
+    issue_iids.dedup();
+    mr_iids.sort_unstable();
+    mr_iids.dedup();
+
     let mut config = Config::load(config_override)?;
     if args.no_events {
         config.sync.fetch_resource_events = false;
@@ -2173,15 +2199,107 @@ async fn handle_sync_cmd(
         no_events: args.no_events,
         robot_mode,
         dry_run,
+        issue_iids,
+        mr_iids,
+        project: args.project,
+        preflight_only: args.preflight_only,
     };
 
-    // For dry run, skip recording and just show the preview
-    if dry_run {
+    // Validation: preflight_only requires surgical mode
+    if options.preflight_only && !options.is_surgical() {
+        return Err("--preflight-only requires --issue or --mr".into());
+    }
+
+    // Validation: full + surgical are incompatible
+    if options.full && options.is_surgical() {
+        return Err("--full and --issue/--mr are incompatible".into());
+    }
+
+    // Validation: surgical mode requires a project (via -p or config defaultProject)
+    if options.is_surgical()
+        && config
+            .effective_project(options.project.as_deref())
+            .is_none()
+    {
+        return Err("--issue/--mr requires -p/--project (or set defaultProject in config)".into());
+    }
+
+    // Validation: hard cap on total surgical targets
+    let total_targets = options.issue_iids.len() + options.mr_iids.len();
+    if total_targets > SyncOptions::MAX_SURGICAL_TARGETS {
+        return Err(format!(
+            "Too many surgical targets ({total_targets}); maximum is {}",
+            SyncOptions::MAX_SURGICAL_TARGETS
+        )
+        .into());
+    }
+
+    // Surgical + dry-run → treat as preflight-only
+    let mut options = options;
+    if dry_run && options.is_surgical() {
+        options.preflight_only = true;
+    }
+
+    // Resolve effective project for surgical mode: when -p is not passed but
+    // defaultProject is set in config, populate options.project so the surgical
+    // orchestrator receives the resolved project path.
+    if options.is_surgical() && options.project.is_none() {
+        options.project = config.default_project.clone();
+    }
+
+    // For non-surgical dry run, skip recording and just show the preview
+    if dry_run && !options.is_surgical() {
         let signal = ShutdownSignal::new();
         run_sync(&config, options, None, &signal).await?;
         return Ok(());
     }
 
+    // Acquire file lock if --lock was passed (used by cron to skip overlapping runs)
+    let _sync_lock = if args.lock {
+        match lore::core::cron::acquire_sync_lock() {
+            Ok(Some(guard)) => Some(guard),
+            Ok(None) => {
+                // Another sync is running — silently exit (expected for cron)
+                tracing::debug!("--lock: another sync is running, skipping");
+                return Ok(());
+            }
+            Err(e) => {
+                tracing::warn!(error = %e, "--lock: failed to acquire file lock, skipping sync");
+                return Ok(());
+            }
+        }
+    } else {
+        None
+    };
+
+    // Surgical mode: run_sync_surgical manages its own recorder, signal, and recording.
+    // Skip the normal recorder setup and let the dispatch handle everything.
+    if options.is_surgical() {
+        let signal = ShutdownSignal::new();
+        let signal_for_handler = signal.clone();
+        tokio::spawn(async move {
+            let _ = tokio::signal::ctrl_c().await;
+            eprintln!("\nInterrupted, finishing current batch... (Ctrl+C again to force quit)");
+            signal_for_handler.cancel();
+            let _ = tokio::signal::ctrl_c().await;
+            std::process::exit(130);
+        });
+
+        let start = std::time::Instant::now();
+        match run_sync(&config, options, None, &signal).await {
+            Ok(result) => {
+                let elapsed = start.elapsed();
+                if robot_mode {
+                    print_sync_json(&result, elapsed.as_millis() as u64, Some(metrics));
+                } else {
+                    print_sync(&result, elapsed, Some(metrics), args.timings);
+                }
+                return Ok(());
+            }
+            Err(e) => return Err(e.into()),
+        }
+    }
+
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let recorder_conn = create_connection(&db_path)?;
     let run_id = uuid::Uuid::new_v4().simple().to_string();
@@ -2254,6 +2372,138 @@ async fn handle_sync_cmd(
     }
 }
 
+fn handle_cron(
+    config_override: Option<&str>,
+    args: CronArgs,
+    robot_mode: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let start = std::time::Instant::now();
+
+    match args.action {
+        CronAction::Install { interval } => {
+            let result = run_cron_install(interval)?;
+            let elapsed_ms = start.elapsed().as_millis() as u64;
+            if robot_mode {
+                print_cron_install_json(&result, elapsed_ms);
+            } else {
+                print_cron_install(&result);
+            }
+            // Warn if no stored token — cron runs in a minimal shell with no env vars
+            if let Ok(config) = Config::load(config_override)
+                && config
+                    .gitlab
+                    .token
+                    .as_ref()
+                    .is_none_or(|t| t.trim().is_empty())
+            {
+                if robot_mode {
+                    eprintln!(
+                        "{{\"warning\":\"No stored token found. Cron sync requires a stored token. Run: lore token set\"}}"
+                    );
+                } else {
+                    eprintln!();
+                    eprintln!(
+                        "  {} No stored token found. Cron sync requires a stored token.",
+                        lore::cli::render::Theme::warning()
+                            .render(lore::cli::render::Icons::warning()),
+                    );
+                    eprintln!("  Run: lore token set");
+                    eprintln!();
+                }
+            }
+        }
+        CronAction::Uninstall => {
+            let result = run_cron_uninstall()?;
+            let elapsed_ms = start.elapsed().as_millis() as u64;
+            if robot_mode {
+                print_cron_uninstall_json(&result, elapsed_ms);
+            } else {
+                print_cron_uninstall(&result);
+            }
+        }
+        CronAction::Status => {
+            let config = Config::load(config_override)?;
+            let info = run_cron_status(&config)?;
+            let elapsed_ms = start.elapsed().as_millis() as u64;
+            if robot_mode {
+                print_cron_status_json(&info, elapsed_ms);
+            } else {
+                print_cron_status(&info);
+            }
+        }
+    }
+
+    Ok(())
+}
+
+async fn handle_token(
+    config_override: Option<&str>,
+    args: TokenArgs,
+    robot_mode: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let start = std::time::Instant::now();
+
+    match args.action {
+        TokenAction::Set { token } => {
+            let result = run_token_set(config_override, token).await?;
+            let elapsed_ms = start.elapsed().as_millis() as u64;
+            if robot_mode {
+                let output = serde_json::json!({
+                    "ok": true,
+                    "data": {
+                        "action": "set",
+                        "username": result.username,
+                        "config_path": result.config_path,
+                    },
+                    "meta": { "elapsed_ms": elapsed_ms },
+                });
+                println!("{}", serde_json::to_string(&output)?);
+            } else {
+                println!(
+                    "  {} Token stored and validated (authenticated as @{})",
+                    lore::cli::render::Theme::success().render(lore::cli::render::Icons::success()),
+                    result.username
+                );
+                println!(
+                    "  {} {}",
+                    lore::cli::render::Theme::dim().render("config:"),
+                    result.config_path
+                );
+                println!();
+            }
+        }
+        TokenAction::Show { unmask } => {
+            let result = run_token_show(config_override, unmask)?;
+            let elapsed_ms = start.elapsed().as_millis() as u64;
+            if robot_mode {
+                let output = serde_json::json!({
+                    "ok": true,
+                    "data": {
+                        "token": result.token,
+                        "source": result.source,
+                    },
+                    "meta": { "elapsed_ms": elapsed_ms },
+                });
+                println!("{}", serde_json::to_string(&output)?);
+            } else {
+                println!(
+                    "  {} {}",
+                    lore::cli::render::Theme::dim().render("token:"),
+                    result.token
+                );
+                println!(
+                    "  {} {}",
+                    lore::cli::render::Theme::dim().render("source:"),
+                    result.source
+                );
+                println!();
+            }
+        }
+    }
+
+    Ok(())
+}
+
 #[derive(Serialize)]
 struct HealthOutput {
     ok: bool,
@@ -2455,13 +2705,31 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
             }
         },
         "sync": {
-            "description": "Full sync pipeline: ingest -> generate-docs -> embed",
-            "flags": ["--full", "--no-full", "--force", "--no-force", "--no-embed", "--no-docs", "--no-events", "--no-file-changes", "--no-status", "--dry-run", "--no-dry-run"],
+            "description": "Full sync pipeline: ingest -> generate-docs -> embed. Supports surgical per-IID mode.",
+            "flags": ["--full", "--no-full", "--force", "--no-force", "--no-embed", "--no-docs", "--no-events", "--no-file-changes", "--no-status", "--dry-run", "--no-dry-run", "-t/--timings", "--lock", "--issue <IID>", "--mr <IID>", "-p/--project <path>", "--preflight-only"],
             "example": "lore --robot sync",
+            "surgical_mode": {
+                "description": "Sync specific issues or MRs by IID. Runs a scoped pipeline: preflight -> TOCTOU check -> ingest -> dependents -> docs -> embed.",
+                "flags": ["--issue <IID> (repeatable)", "--mr <IID> (repeatable)", "-p/--project <path> (required)", "--preflight-only"],
+                "examples": [
+                    "lore --robot sync --issue 7 -p group/project",
+                    "lore --robot sync --issue 7 --issue 42 --mr 10 -p group/project",
+                    "lore --robot sync --issue 7 -p group/project --preflight-only"
+                ],
+                "constraints": ["--issue/--mr requires -p/--project (or defaultProject in config)", "--full and --issue/--mr are incompatible", "--preflight-only requires --issue or --mr", "Max 100 total targets"],
+                "entity_result_outcomes": ["synced", "skipped_stale", "not_found", "preflight_failed", "error"]
+            },
             "response_schema": {
-                "ok": "bool",
-                "data": {"issues_updated": "int", "mrs_updated": "int", "documents_regenerated": "int", "documents_embedded": "int", "resource_events_synced": "int", "resource_events_failed": "int"},
-                "meta": {"elapsed_ms": "int", "stages?": "[{name:string, elapsed_ms:int, items_processed:int}]"}
+                "normal": {
+                    "ok": "bool",
+                    "data": {"issues_updated": "int", "mrs_updated": "int", "documents_regenerated": "int", "documents_embedded": "int", "resource_events_synced": "int", "resource_events_failed": "int"},
+                    "meta": {"elapsed_ms": "int", "stages?": "[{name:string, elapsed_ms:int, items_processed:int}]"}
+                },
+                "surgical": {
+                    "ok": "bool",
+                    "data": {"surgical_mode": "true", "surgical_iids": "{issues:[int], merge_requests:[int]}", "entity_results": "[{entity_type:string, iid:int, outcome:string, error?:string, toctou_reason?:string}]", "preflight_only?": "bool", "issues_updated": "int", "mrs_updated": "int", "documents_regenerated": "int", "documents_embedded": "int", "discussions_fetched": "int"},
+                    "meta": {"elapsed_ms": "int"}
+                }
             }
         },
         "issues": {
@@ -2610,7 +2878,7 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
         },
         "who": {
             "description": "People intelligence: experts, workload, active discussions, overlap, review patterns",
-            "flags": ["<target>", "--path <path>", "--active", "--overlap <path>", "--reviews", "--since <duration>", "-p/--project", "-n/--limit", "--fields <list>", "--detail", "--no-detail", "--as-of <date>", "--explain-score", "--include-bots", "--all-history"],
+            "flags": ["<target>", "--path <path>", "--active", "--overlap <path>", "--reviews", "--since <duration>", "-p/--project", "-n/--limit", "--fields <list>", "--detail", "--no-detail", "--as-of <date>", "--explain-score", "--include-bots", "--include-closed", "--all-history"],
             "modes": {
                 "expert": "lore who <file-path> -- Who knows about this area? (also: --path for root files)",
                 "workload": "lore who <username> -- What is someone working on?",
@@ -2668,7 +2936,7 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
         },
         "notes": {
             "description": "List notes from discussions with rich filtering",
-            "flags": ["--limit/-n <N>", "--author/-a <username>", "--note-type <type>", "--contains <text>", "--for-issue <iid>", "--for-mr <iid>", "-p/--project <path>", "--since <period>", "--until <period>", "--path <filepath>", "--resolution <any|unresolved|resolved>", "--sort <created|updated>", "--asc", "--include-system", "--note-id <id>", "--gitlab-note-id <id>", "--discussion-id <id>", "--format <table|json|jsonl|csv>", "--fields <list|minimal>", "--open"],
+            "flags": ["--limit/-n <N>", "--author/-a <username>", "--note-type <type>", "--contains <text>", "--for-issue <iid>", "--for-mr <iid>", "-p/--project <path>", "--since <period>", "--until <period>", "--path <filepath>", "--resolution <any|unresolved|resolved>", "--sort <created|updated>", "--asc", "--include-system", "--note-id <id>", "--gitlab-note-id <id>", "--discussion-id <id>", "--fields <list|minimal>", "--open"],
             "robot_flags": ["--format json", "--fields minimal"],
             "example": "lore --robot notes --author jdefting --since 1y --format json --fields minimal",
             "response_schema": {
@@ -2677,6 +2945,65 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
                 "meta": {"elapsed_ms": "int"}
             }
         },
+        "cron": {
+            "description": "Manage cron-based automatic syncing (Unix only)",
+            "subcommands": {
+                "install": {"flags": ["--interval <minutes>"], "default_interval": 8},
+                "uninstall": {"flags": []},
+                "status": {"flags": []}
+            },
+            "example": "lore --robot cron status",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"action": "string (install|uninstall|status)", "installed?": "bool", "interval_minutes?": "int", "entry?": "string", "log_path?": "string", "replaced?": "bool", "was_installed?": "bool", "last_run_iso?": "string"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "token": {
+            "description": "Manage stored GitLab token",
+            "subcommands": {
+                "set": {"flags": ["--token <value>"], "note": "Reads from stdin if --token omitted in non-interactive mode"},
+                "show": {"flags": ["--unmask"]}
+            },
+            "example": "lore --robot token show",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"action": "string (set|show)", "token_masked?": "string", "token?": "string", "valid?": "bool", "username?": "string"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
+        "me": {
+            "description": "Personal work dashboard: open issues, authored/reviewing MRs, activity feed, and cursor-based since-last-check inbox with computed attention states",
+            "flags": ["--issues", "--mrs", "--activity", "--since <period>", "-p/--project <path>", "--all", "--user <username>", "--fields <list|minimal>", "--reset-cursor"],
+            "example": "lore --robot me",
+            "response_schema": {
+                "ok": "bool",
+                "data": {
+                    "username": "string",
+                    "since_iso": "string?",
+                    "summary": {"project_count": "int", "open_issue_count": "int", "authored_mr_count": "int", "reviewing_mr_count": "int", "needs_attention_count": "int"},
+                    "since_last_check": "{cursor_iso:string, total_event_count:int, groups:[{entity_type:string, entity_iid:int, entity_title:string, project:string, events:[{timestamp_iso:string, event_type:string, actor:string?, summary:string, body_preview:string?}]}]}?",
+                    "open_issues": "[{project:string, iid:int, title:string, state:string, attention_state:string, status_name:string?, labels:[string], updated_at_iso:string, web_url:string?}]",
+                    "open_mrs_authored": "[{project:string, iid:int, title:string, state:string, attention_state:string, draft:bool, detailed_merge_status:string?, author_username:string?, labels:[string], updated_at_iso:string, web_url:string?}]",
+                    "reviewing_mrs": "[same as open_mrs_authored]",
+                    "activity": "[{timestamp_iso:string, event_type:string, entity_type:string, entity_iid:int, project:string, actor:string?, is_own:bool, summary:string, body_preview:string?}]"
+                },
+                "meta": {"elapsed_ms": "int"}
+            },
+            "fields_presets": {
+                "me_items_minimal": ["iid", "title", "attention_state", "updated_at_iso"],
+                "me_activity_minimal": ["timestamp_iso", "event_type", "entity_iid", "actor"]
+            },
+            "notes": {
+                "attention_states": "needs_attention | not_started | awaiting_response | stale | not_ready",
+                "event_types": "note | status_change | label_change | assign | unassign | review_request | milestone_change",
+                "section_flags": "If none of --issues/--mrs/--activity specified, all sections returned",
+                "since_default": "1d for activity feed",
+                "issue_filter": "Only In Progress / In Review status issues shown",
+                "since_last_check": "Cursor-based inbox showing events since last run. Null on first run (no cursor yet). Groups events by entity (issue/MR). Sources: others' comments on your items, @mentions, assignment/review-request notes. Cursor auto-advances after each run. Use --reset-cursor to clear.",
+                "cursor_persistence": "Stored per user in ~/.local/share/lore/me_cursor_<username>.json. --project filters display only for since-last-check; cursor still advances for all projects for that user."
+            }
+        },
         "robot-docs": {
             "description": "This command (agent self-discovery manifest)",
             "flags": ["--brief"],
@@ -2698,10 +3025,15 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
             "search: FTS5 + vector hybrid search across all entities",
             "who: Expert/workload/reviews analysis per file path or person",
             "timeline: Chronological event reconstruction across entities",
+            "trace: Code provenance chains (file -> MR -> issue -> discussion)",
+            "file-history: MR history per file with rename resolution",
             "notes: Rich note listing with author, type, resolution, path, and discussion filters",
             "stats: Database statistics with document/note/discussion counts",
             "count: Entity counts with state breakdowns",
-            "embed: Generate vector embeddings for semantic search via Ollama"
+            "embed: Generate vector embeddings for semantic search via Ollama",
+            "cron: Automated sync scheduling (Unix)",
+            "token: Secure token management with masked display",
+            "me: Personal work dashboard with attention states, activity feed, cursor-based since-last-check inbox, and needs-attention triage"
         ],
         "read_write_split": "lore = ALL reads (issues, MRs, search, who, timeline, intelligence). glab = ALL writes (create, update, approve, merge, CI/CD)."
     });
@@ -2763,6 +3095,19 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
             "lore --robot who --active --since 7d",
             "lore --robot who --overlap src/path/",
             "lore --robot who --path README.md"
+        ],
+        "surgical_sync": [
+            "lore --robot sync --issue 7 -p group/project",
+            "lore --robot sync --issue 7 --mr 10 -p group/project",
+            "lore --robot sync --issue 7 -p group/project --preflight-only"
+        ],
+        "personal_dashboard": [
+            "lore --robot me",
+            "lore --robot me --issues",
+            "lore --robot me --activity --since 7d",
+            "lore --robot me --project group/repo",
+            "lore --robot me --fields minimal",
+            "lore --robot me --reset-cursor"
         ]
     });
 
@@ -2896,6 +3241,16 @@ fn handle_who(
     Ok(())
 }
 
+fn handle_me(
+    config_override: Option<&str>,
+    args: MeArgs,
+    robot_mode: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let config = Config::load(config_override)?;
+    run_me(&config, &args, robot_mode)?;
+    Ok(())
+}
+
 async fn handle_drift(
     config_override: Option<&str>,
     entity_type: &str,
@@ -2918,6 +3273,28 @@ async fn handle_drift(
     Ok(())
 }
 
+async fn handle_related(
+    config_override: Option<&str>,
+    query_or_type: &str,
+    iid: Option<i64>,
+    limit: usize,
+    project: Option<&str>,
+    robot_mode: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let start = std::time::Instant::now();
+    let config = Config::load(config_override)?;
+    let effective_project = config.effective_project(project);
+    let response = run_related(&config, query_or_type, iid, limit, effective_project).await?;
+    let elapsed_ms = start.elapsed().as_millis() as u64;
+
+    if robot_mode {
+        print_related_json(&response, elapsed_ms);
+    } else {
+        print_related_human(&response);
+    }
+    Ok(())
+}
+
 #[allow(clippy::too_many_arguments)]
 async fn handle_list_compat(
     config_override: Option<&str>,