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

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

Includes 3 unit tests.

.beads/last-touched

@@ -1 +1 @@
-bd-23xb
+bd-1lj5

Cargo.lock

@@ -1324,7 +1324,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lore"
-version = "0.9.2"
+version = "0.9.4"
 dependencies = [
  "asupersync",
  "async-stream",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lore"
-version = "0.9.2"
+version = "0.9.4"
 edition = "2024"
 description = "Gitlore - Local GitLab data management with semantic search"
 authors = ["Taylor Eernisse"]

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

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

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

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

agents/founding-engineer/AGENTS.md

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

agents/founding-engineer/DOMAIN.md

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

agents/founding-engineer/HEARTBEAT.md

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

agents/founding-engineer/SOUL.md

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

agents/founding-engineer/TOOLS.md

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

agents/plan-reviewer/AGENTS.md

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

agents/plan-reviewer/HEARTBEAT.md

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

agents/plan-reviewer/SOUL.md

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

command-restructure/CLI_AUDIT.md

@@ -37,11 +37,10 @@
 | 29 | *help* | — | — | — | (clap built-in) |
 | | **Hidden/deprecated:** | | | | |
 | 30 | `list` | — | `<ENTITY>` | 14 | deprecated, use issues/mrs |
-| 31 | `show` | — | `<ENTITY> <IID>` | 1 | deprecated, use issues/mrs |
-| 32 | `auth-test` | — | — | 0 | deprecated, use auth |
-| 33 | `sync-status` | — | — | 0 | deprecated, use status |
-| 34 | `backup` | — | — | 0 | Stub (not implemented) |
-| 35 | `reset` | — | — | 1 | Stub (not implemented) |
+| 31 | `auth-test` | — | — | 0 | deprecated, use auth |
+| 32 | `sync-status` | — | — | 0 | deprecated, use status |
+| 33 | `backup` | — | — | 0 | Stub (not implemented) |
+| 34 | `reset` | — | — | 1 | Stub (not implemented) |
 
 ---
 

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

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

docs/plan-expose-discussion-ids.md

@@ -43,7 +43,7 @@ construct API calls without a separate project-ID lookup, even after path change
 **Back-compat rule**: Note payloads in the `notes` list command continue exposing `gitlab_id`
 for existing consumers, but **MUST also** expose `gitlab_note_id` with the same value. This
 ensures agents can use a single field name (`gitlab_note_id`) across all commands — `notes`,
-`show`, and `discussions --include-notes` — without special-casing by command.
+`issues <IID>`/`mrs <IID>`, and `discussions --include-notes` — without special-casing by command.
 
 This contract exists so agents can deterministically construct `glab api` write calls without
 cross-referencing multiple commands. Each workstream below must satisfy these fields in its

plans/work-item-status-graphql.md

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

specs/SPEC_discussion_analysis.md

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

specs/SPEC_explain.md

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

src/app/errors.rs

@@ -7,6 +7,10 @@ struct FallbackErrorOutput {
 struct FallbackError {
     code: String,
     message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    suggestion: Option<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    actions: Vec<String>,
 }
 
 fn handle_error(e: Box<dyn std::error::Error>, robot_mode: bool) -> ! {
@@ -20,6 +24,8 @@ fn handle_error(e: Box<dyn std::error::Error>, robot_mode: bool) -> ! {
                         error: FallbackError {
                             code: "INTERNAL_ERROR".to_string(),
                             message: gi_error.to_string(),
+                            suggestion: None,
+                            actions: Vec::new(),
                         },
                     };
                     serde_json::to_string(&fallback)
@@ -59,6 +65,8 @@ fn handle_error(e: Box<dyn std::error::Error>, robot_mode: bool) -> ! {
             error: FallbackError {
                 code: "INTERNAL_ERROR".to_string(),
                 message: e.to_string(),
+                suggestion: None,
+                actions: Vec::new(),
             },
         };
         eprintln!(

src/app/handlers.rs

@@ -361,7 +361,7 @@ fn print_combined_ingest_json(
                 notes_upserted: mrs.notes_upserted,
             },
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
 
     println!(
@@ -735,7 +735,7 @@ async fn handle_init(
         }
 
         let project_paths: Vec<String> = projects_flag
-            .unwrap()
+            .expect("validated: checked for None at lines 714-721")
             .split(',')
             .map(|p| p.trim().to_string())
             .filter(|p| !p.is_empty())
@@ -743,8 +743,10 @@ async fn handle_init(
 
         let result = run_init(
             InitInputs {
-                gitlab_url: gitlab_url_flag.unwrap(),
-                token_env_var: token_env_var_flag.unwrap(),
+                gitlab_url: gitlab_url_flag
+                    .expect("validated: checked for None at lines 714-721"),
+                token_env_var: token_env_var_flag
+                    .expect("validated: checked for None at lines 714-721"),
                 project_paths,
                 default_project: default_project_flag.clone(),
             },
@@ -973,9 +975,7 @@ async fn handle_auth_test(
                         name: result.name.clone(),
                         gitlab_url: result.base_url.clone(),
                     },
-                    meta: RobotMeta {
-                        elapsed_ms: start.elapsed().as_millis() as u64,
-                    },
+                    meta: RobotMeta::new(start.elapsed().as_millis() as u64),
                 };
                 println!("{}", serde_json::to_string(&output)?);
             } else {
@@ -1036,9 +1036,7 @@ async fn handle_doctor(
                 success: result.success,
                 checks: result.checks,
             },
-            meta: RobotMeta {
-                elapsed_ms: start.elapsed().as_millis() as u64,
-            },
+            meta: RobotMeta::new(start.elapsed().as_millis() as u64),
         };
         println!("{}", serde_json::to_string(&output)?);
     } else {
@@ -1083,9 +1081,7 @@ fn handle_version(robot_mode: bool) -> Result<(), Box<dyn std::error::Error>> {
                     Some(git_hash)
                 },
             },
-            meta: RobotMeta {
-                elapsed_ms: start.elapsed().as_millis() as u64,
-            },
+            meta: RobotMeta::new(start.elapsed().as_millis() as u64),
         };
         println!("{}", serde_json::to_string(&output)?);
     } else if git_hash.is_empty() {
@@ -1243,9 +1239,7 @@ async fn handle_migrate(
                 after_version,
                 migrated: after_version > before_version,
             },
-            meta: RobotMeta {
-                elapsed_ms: start.elapsed().as_millis() as u64,
-            },
+            meta: RobotMeta::new(start.elapsed().as_millis() as u64),
         };
         println!("{}", serde_json::to_string(&output)?);
     } else if after_version > before_version {
@@ -1326,7 +1320,7 @@ fn handle_file_history(
 
     if robot_mode {
         let elapsed_ms = start.elapsed().as_millis() as u64;
-        print_file_history_json(&result, elapsed_ms);
+        print_file_history_json(&result, elapsed_ms)?;
     } else {
         print_file_history(&result);
     }
@@ -1382,7 +1376,7 @@ fn handle_trace(
 
     if robot_mode {
         let elapsed_ms = start.elapsed().as_millis() as u64;
-        print_trace_json(&result, elapsed_ms, line_requested);
+        print_trace_json(&result, elapsed_ms, line_requested)?;
     } else {
         print_trace(&result);
     }
@@ -1475,7 +1469,7 @@ async fn handle_search(
     if robot_mode {
         print_search_results_json(&response, elapsed_ms, args.fields.as_deref());
     } else {
-        print_search_results(&response);
+        print_search_results(&response, explain);
     }
     Ok(())
 }
@@ -1960,9 +1954,7 @@ async fn handle_health(
                 schema_version,
                 actions,
             },
-            meta: RobotMeta {
-                elapsed_ms: start.elapsed().as_millis() as u64,
-            },
+            meta: RobotMeta::new(start.elapsed().as_millis() as u64),
         };
         println!("{}", serde_json::to_string(&output)?);
     } else {

src/app/robot_docs.rs

@@ -115,7 +115,7 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
             }
         },
         "issues": {
-            "description": "List or show issues",
+            "description": "List issues, or view detail with <IID>",
             "flags": ["<IID>", "-n/--limit", "--fields <list>", "-s/--state", "--status <name>", "-p/--project", "-a/--author", "-A/--assignee", "-l/--label", "-m/--milestone", "--since", "--due-before", "--has-due", "--no-has-due", "--sort", "--asc", "--no-asc", "-o/--open", "--no-open"],
             "example": "lore --robot issues --state opened --limit 10",
             "notes": {
@@ -128,7 +128,7 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
                     "data": {"issues": "[{iid:int, title:string, state:string, author_username:string, labels:[string], assignees:[string], discussion_count:int, unresolved_count:int, created_at_iso:string, updated_at_iso:string, web_url:string?, project_path:string, status_name:string?}]", "total_count": "int", "showing": "int"},
                     "meta": {"elapsed_ms": "int", "available_statuses": "[string] — all distinct status names in the database, for use with --status filter"}
                 },
-                "show": {
+                "detail": {
                     "ok": "bool",
                     "data": "IssueDetail (full entity with description, discussions, notes, events)",
                     "meta": {"elapsed_ms": "int"}
@@ -138,7 +138,7 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
             "fields_presets": {"minimal": ["iid", "title", "state", "updated_at_iso"]}
         },
         "mrs": {
-            "description": "List or show merge requests",
+            "description": "List merge requests, or view detail with <IID>",
             "flags": ["<IID>", "-n/--limit", "--fields <list>", "-s/--state", "-p/--project", "-a/--author", "-A/--assignee", "-r/--reviewer", "-l/--label", "--since", "-d/--draft", "-D/--no-draft", "--target", "--source", "--sort", "--asc", "--no-asc", "-o/--open", "--no-open"],
             "example": "lore --robot mrs --state opened",
             "response_schema": {
@@ -147,7 +147,7 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
                     "data": {"mrs": "[{iid:int, title:string, state:string, author_username:string, labels:[string], draft:bool, target_branch:string, source_branch:string, discussion_count:int, unresolved_count:int, created_at_iso:string, updated_at_iso:string, web_url:string?, project_path:string, reviewers:[string]}]", "total_count": "int", "showing": "int"},
                     "meta": {"elapsed_ms": "int"}
                 },
-                "show": {
+                "detail": {
                     "ok": "bool",
                     "data": "MrDetail (full entity with description, discussions, notes, events)",
                     "meta": {"elapsed_ms": "int"}
@@ -316,6 +316,17 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
                 "meta": {"elapsed_ms": "int"}
             }
         },
+        "explain": {
+            "description": "Auto-generate a structured narrative of an issue or MR",
+            "flags": ["<entity_type: issues|mrs>", "<IID>", "-p/--project <path>", "--sections <comma-list>", "--no-timeline", "--max-decisions <N>", "--since <period>"],
+            "valid_sections": ["entity", "description", "key_decisions", "activity", "open_threads", "related", "timeline"],
+            "example": "lore --robot explain issues 42 --sections key_decisions,activity --since 30d",
+            "response_schema": {
+                "ok": "bool",
+                "data": {"entity": "{type:string, iid:int, title:string, state:string, author:string, assignees:[string], labels:[string], created_at:string, updated_at:string, url:string?, status_name:string?}", "description_excerpt": "string?", "key_decisions": "[{timestamp:string, actor:string, action:string, context_note:string}]?", "activity": "{state_changes:int, label_changes:int, notes:int, first_event:string?, last_event:string?}?", "open_threads": "[{discussion_id:string, started_by:string, started_at:string, note_count:int, last_note_at:string}]?", "related": "{closing_mrs:[{iid:int, title:string, state:string, web_url:string?}], related_issues:[{entity_type:string, iid:int, title:string?, reference_type:string}]}?", "timeline_excerpt": "[{timestamp:string, event_type:string, actor:string?, summary:string}]?"},
+                "meta": {"elapsed_ms": "int"}
+            }
+        },
         "notes": {
             "description": "List notes from discussions with rich filtering",
             "flags": ["--limit/-n <N>", "--author/-a <username>", "--note-type <type>", "--contains <text>", "--for-issue <iid>", "--for-mr <iid>", "-p/--project <path>", "--since <period>", "--until <period>", "--path <filepath>", "--resolution <any|unresolved|resolved>", "--sort <created|updated>", "--asc", "--include-system", "--note-id <id>", "--gitlab-note-id <id>", "--discussion-id <id>", "--fields <list|minimal>", "--open"],
@@ -371,7 +382,7 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
                     "mentioned_in": "[{entity_type:string, project:string, iid:int, title:string, state:string, attention_state:string, attention_reason:string, updated_at_iso:string, web_url:string?}]",
                     "activity": "[{timestamp_iso:string, event_type:string, entity_type:string, entity_iid:int, project:string, actor:string?, is_own:bool, summary:string, body_preview:string?}]"
                 },
-                "meta": {"elapsed_ms": "int"}
+                "meta": {"elapsed_ms": "int", "gitlab_base_url": "string (GitLab instance URL for constructing entity links: {base_url}/{project}/-/issues/{iid})"}
             },
             "fields_presets": {
                 "me_items_minimal": ["iid", "title", "attention_state", "attention_reason", "updated_at_iso"],
@@ -385,7 +396,8 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
                 "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."
+                "cursor_persistence": "Stored per user in ~/.local/share/lore/me_cursor_<username>.json. --project filters display only for since-last-check; cursor still advances for all projects for that user.",
+                "url_construction": "Use meta.gitlab_base_url + project + entity_type + iid to build links: {gitlab_base_url}/{project}/-/{issues|merge_requests}/{iid}"
             }
         },
         "robot-docs": {
@@ -449,7 +461,8 @@ fn handle_robot_docs(robot_mode: bool, brief: bool) -> Result<(), Box<dyn std::e
         "17": "Not found",
         "18": "Ambiguous match",
         "19": "Health check failed",
-        "20": "Config not found"
+        "20": "Config not found",
+        "21": "Embeddings not built"
     });
 
     let workflows = serde_json::json!({
@@ -780,42 +793,3 @@ async fn handle_list_compat(
     }
 }
 
-async fn handle_show_compat(
-    config_override: Option<&str>,
-    entity: &str,
-    iid: i64,
-    project_filter: Option<&str>,
-    robot_mode: bool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let start = std::time::Instant::now();
-    let config = Config::load(config_override)?;
-    let project_filter = config.effective_project(project_filter);
-
-    match entity {
-        "issue" => {
-            let result = run_show_issue(&config, iid, project_filter)?;
-            if robot_mode {
-                print_show_issue_json(&result, start.elapsed().as_millis() as u64);
-            } else {
-                print_show_issue(&result);
-            }
-            Ok(())
-        }
-        "mr" => {
-            let result = run_show_mr(&config, iid, project_filter)?;
-            if robot_mode {
-                print_show_mr_json(&result, start.elapsed().as_millis() as u64);
-            } else {
-                print_show_mr(&result);
-            }
-            Ok(())
-        }
-        _ => {
-            eprintln!(
-                "{}",
-                Theme::error().render(&format!("Unknown entity: {entity}"))
-            );
-            std::process::exit(1);
-        }
-    }
-}

src/cli/autocorrect.rs

@@ -209,6 +209,16 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
         ],
     ),
     ("drift", &["--threshold", "--project"]),
+    (
+        "explain",
+        &[
+            "--project",
+            "--sections",
+            "--no-timeline",
+            "--max-decisions",
+            "--since",
+        ],
+    ),
     (
         "notes",
         &[
@@ -290,7 +300,6 @@ const COMMAND_FLAGS: &[(&str, &[&str])] = &[
             "--source-branch",
         ],
     ),
-    ("show", &["--project"]),
     ("reset", &["--yes"]),
     (
         "me",
@@ -389,6 +398,7 @@ const CANONICAL_SUBCOMMANDS: &[&str] = &[
     "file-history",
     "trace",
     "drift",
+    "explain",
     "related",
     "cron",
     "token",
@@ -396,7 +406,6 @@ const CANONICAL_SUBCOMMANDS: &[&str] = &[
     "backup",
     "reset",
     "list",
-    "show",
     "auth-test",
     "sync-status",
 ];

src/cli/commands/count.rs

@@ -254,7 +254,7 @@ pub fn print_event_count_json(counts: &EventCounts, elapsed_ms: u64) {
             },
             total: counts.total(),
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
 
     match serde_json::to_string(&output) {
@@ -325,7 +325,7 @@ pub fn print_count_json(result: &CountResult, elapsed_ms: u64) {
             system_excluded: result.system_count,
             breakdown,
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
 
     match serde_json::to_string(&output) {

src/cli/commands/cron.rs

@@ -80,7 +80,7 @@ pub fn print_cron_install_json(result: &CronInstallResult, elapsed_ms: u64) {
             log_path: result.log_path.display().to_string(),
             replaced: result.replaced,
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
     if let Ok(json) = serde_json::to_string(&output) {
         println!("{json}");
@@ -128,7 +128,7 @@ pub fn print_cron_uninstall_json(result: &CronUninstallResult, elapsed_ms: u64)
             action: "uninstall",
             was_installed: result.was_installed,
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
     if let Ok(json) = serde_json::to_string(&output) {
         println!("{json}");
@@ -284,7 +284,7 @@ pub fn print_cron_status_json(info: &CronStatusInfo, elapsed_ms: u64) {
             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 },
+        meta: RobotMeta::new(elapsed_ms),
     };
     if let Ok(json) = serde_json::to_string(&output) {
         println!("{json}");

src/cli/commands/drift.rs

@@ -468,7 +468,7 @@ pub fn print_drift_human(response: &DriftResponse) {
 }
 
 pub fn print_drift_json(response: &DriftResponse, elapsed_ms: u64) {
-    let meta = RobotMeta { elapsed_ms };
+    let meta = RobotMeta::new(elapsed_ms);
     let output = serde_json::json!({
         "ok": true,
         "data": response,

src/cli/commands/embed.rs

@@ -135,7 +135,7 @@ pub fn print_embed_json(result: &EmbedCommandResult, elapsed_ms: u64) {
     let output = EmbedJsonOutput {
         ok: true,
         data: result,
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
     match serde_json::to_string(&output) {
         Ok(json) => println!("{json}"),

src/cli/commands/file_history.rs

@@ -5,7 +5,7 @@ use tracing::info;
 use crate::Config;
 use crate::cli::render::{self, Icons, Theme};
 use crate::core::db::create_connection;
-use crate::core::error::Result;
+use crate::core::error::{LoreError, Result};
 use crate::core::file_history::resolve_rename_chain;
 use crate::core::paths::get_db_path;
 use crate::core::project::resolve_project;
@@ -391,7 +391,7 @@ pub fn print_file_history(result: &FileHistoryResult) {
 
 // ── Robot (JSON) output ─────────────────────────────────────────────────────
 
-pub fn print_file_history_json(result: &FileHistoryResult, elapsed_ms: u64) {
+pub fn print_file_history_json(result: &FileHistoryResult, elapsed_ms: u64) -> Result<()> {
     let output = serde_json::json!({
         "ok": true,
         "data": {
@@ -409,5 +409,10 @@ pub fn print_file_history_json(result: &FileHistoryResult, elapsed_ms: u64) {
         }
     });
 
-    println!("{}", serde_json::to_string(&output).unwrap_or_default());
+    println!(
+        "{}",
+        serde_json::to_string(&output)
+            .map_err(|e| LoreError::Other(format!("JSON serialization failed: {e}")))?
+    );
+    Ok(())
 }

src/cli/commands/generate_docs.rs

@@ -257,7 +257,7 @@ pub fn print_generate_docs_json(result: &GenerateDocsResult, elapsed_ms: u64) {
             unchanged: result.unchanged,
             errored: result.errored,
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
     match serde_json::to_string(&output) {
         Ok(json) => println!("{json}"),

src/cli/commands/ingest/render.rs

@@ -191,7 +191,7 @@ pub fn print_ingest_summary_json(result: &IngestResult, elapsed_ms: u64) {
             status_enrichment,
             status_enrichment_errors: result.status_enrichment_errors,
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
 
     match serde_json::to_string(&output) {

src/cli/commands/list/mrs.rs

@@ -370,7 +370,7 @@ pub fn print_list_mrs(result: &MrListResult) {
 
 pub fn print_list_mrs_json(result: &MrListResult, elapsed_ms: u64, fields: Option<&[String]>) {
     let json_result = MrListResultJson::from(result);
-    let meta = RobotMeta { elapsed_ms };
+    let meta = RobotMeta::new(elapsed_ms);
     let output = serde_json::json!({
         "ok": true,
         "data": json_result,

src/cli/commands/list/notes.rs

@@ -193,7 +193,7 @@ pub fn print_list_notes(result: &NoteListResult) {
 
 pub fn print_list_notes_json(result: &NoteListResult, elapsed_ms: u64, fields: Option<&[String]>) {
     let json_result = NoteListResultJson::from(result);
-    let meta = RobotMeta { elapsed_ms };
+    let meta = RobotMeta::new(elapsed_ms);
     let output = serde_json::json!({
         "ok": true,
         "data": json_result,

src/cli/commands/me/me_tests.rs

@@ -946,7 +946,7 @@ fn mentioned_in_finds_mention_on_unassigned_issue() {
     );
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].entity_type, "issue");
     assert_eq!(results[0].iid, 42);
@@ -964,7 +964,7 @@ fn mentioned_in_excludes_assigned_issue() {
     insert_note_at(&conn, 200, disc_id, 1, "bob", false, "hey @alice", t);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert!(results.is_empty(), "should exclude assigned issues");
 }
 
@@ -979,7 +979,7 @@ fn mentioned_in_excludes_authored_issue() {
     insert_note_at(&conn, 200, disc_id, 1, "bob", false, "hey @alice", t);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert!(results.is_empty(), "should exclude authored issues");
 }
 
@@ -995,7 +995,7 @@ fn mentioned_in_finds_mention_on_non_authored_mr() {
     insert_note_at(&conn, 200, disc_id, 1, "bob", false, "cc @alice", t);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].entity_type, "mr");
     assert_eq!(results[0].iid, 99);
@@ -1012,7 +1012,7 @@ fn mentioned_in_excludes_authored_mr() {
     insert_note_at(&conn, 200, disc_id, 1, "bob", false, "@alice thoughts?", t);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert!(results.is_empty(), "should exclude authored MRs");
 }
 
@@ -1028,7 +1028,7 @@ fn mentioned_in_excludes_reviewer_mr() {
     insert_note_at(&conn, 200, disc_id, 1, "charlie", false, "@alice fyi", t);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert!(
         results.is_empty(),
         "should exclude MRs where user is reviewer"
@@ -1052,7 +1052,7 @@ fn mentioned_in_includes_recently_closed_issue() {
     insert_note_at(&conn, 200, disc_id, 1, "bob", false, "hey @alice", t);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert_eq!(results.len(), 1, "recently closed issue should be included");
     assert_eq!(results[0].state, "closed");
 }
@@ -1074,7 +1074,7 @@ fn mentioned_in_excludes_old_closed_issue() {
     insert_note_at(&conn, 200, disc_id, 1, "bob", false, "hey @alice", t);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert!(results.is_empty(), "old closed issue should be excluded");
 }
 
@@ -1099,7 +1099,7 @@ fn mentioned_in_attention_needs_attention_when_unreplied() {
     // alice has NOT replied
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].attention_state, AttentionState::NeedsAttention);
 }
@@ -1126,7 +1126,7 @@ fn mentioned_in_attention_awaiting_when_replied() {
     insert_note_at(&conn, 201, disc_id, 1, "alice", false, "looks good", t2);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].attention_state, AttentionState::AwaitingResponse);
 }
@@ -1147,7 +1147,7 @@ fn mentioned_in_project_filter() {
     insert_note_at(&conn, 201, disc_b, 2, "bob", false, "@alice", t);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[1], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[1], recency_cutoff, 0).unwrap();
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].project_path, "group/repo-a");
 }
@@ -1166,7 +1166,7 @@ fn mentioned_in_deduplicates_multiple_mentions_same_entity() {
     insert_note_at(&conn, 201, disc_id, 1, "charlie", false, "@alice +1", t2);
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert_eq!(results.len(), 1, "should deduplicate to one entity");
 }
 
@@ -1190,10 +1190,47 @@ fn mentioned_in_rejects_false_positive_email() {
     );
 
     let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
-    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff).unwrap();
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, 0).unwrap();
     assert!(results.is_empty(), "email-like text should not match");
 }
 
+#[test]
+fn mentioned_in_excludes_old_mention_on_open_issue() {
+    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));
+    // Mention from 45 days ago — outside 30-day mention window
+    let t = now_ms() - 45 * 24 * 3600 * 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "bob", false, "hey @alice", t);
+
+    let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
+    let mention_cutoff = now_ms() - 30 * 24 * 3600 * 1000;
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, mention_cutoff).unwrap();
+    assert!(
+        results.is_empty(),
+        "mentions older than 30 days should be excluded"
+    );
+}
+
+#[test]
+fn mentioned_in_includes_recent_mention_on_open_issue() {
+    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));
+    // Mention from 5 days ago — within 30-day window
+    let t = now_ms() - 5 * 24 * 3600 * 1000;
+    insert_note_at(&conn, 200, disc_id, 1, "bob", false, "hey @alice", t);
+
+    let recency_cutoff = now_ms() - 7 * 24 * 3600 * 1000;
+    let mention_cutoff = now_ms() - 30 * 24 * 3600 * 1000;
+    let results = query_mentioned_in(&conn, "alice", &[], recency_cutoff, mention_cutoff).unwrap();
+    assert_eq!(results.len(), 1, "recent mentions should be included");
+}
+
 // ─── Helper Tests ──────────────────────────────────────────────────────────
 
 #[test]

src/cli/commands/me/mod.rs

@@ -27,6 +27,8 @@ const DEFAULT_ACTIVITY_SINCE_DAYS: i64 = 1;
 const MS_PER_DAY: i64 = 24 * 60 * 60 * 1000;
 /// Recency window for closed/merged items in the "Mentioned In" section: 7 days.
 const RECENCY_WINDOW_MS: i64 = 7 * MS_PER_DAY;
+/// Only show mentions from notes created within this window (30 days).
+const MENTION_WINDOW_MS: i64 = 30 * MS_PER_DAY;
 
 /// Resolve the effective username from CLI flag or config.
 ///
@@ -151,7 +153,14 @@ pub fn run_me(config: &Config, args: &MeArgs, robot_mode: bool) -> Result<()> {
 
     let mentioned_in = if want_mentions {
         let recency_cutoff = crate::core::time::now_ms() - RECENCY_WINDOW_MS;
-        query_mentioned_in(&conn, username, &project_ids, recency_cutoff)?
+        let mention_cutoff = crate::core::time::now_ms() - MENTION_WINDOW_MS;
+        query_mentioned_in(
+            &conn,
+            username,
+            &project_ids,
+            recency_cutoff,
+            mention_cutoff,
+        )?
     } else {
         Vec::new()
     };
@@ -247,7 +256,7 @@ pub fn run_me(config: &Config, args: &MeArgs, robot_mode: bool) -> Result<()> {
 
     if robot_mode {
         let fields = args.fields.as_deref();
-        render_robot::print_me_json(&dashboard, elapsed_ms, fields)?;
+        render_robot::print_me_json(&dashboard, elapsed_ms, fields, &config.gitlab.base_url)?;
     } else if show_all {
         render_human::print_me_dashboard(&dashboard, single_project);
     } else {

src/cli/commands/me/queries.rs

@@ -849,6 +849,7 @@ fn build_mentioned_in_sql(project_clause: &str) -> String {
         LEFT JOIN note_ts_issue nt ON nt.issue_id = ci.id
         WHERE n.is_system = 0
           AND n.author_username != ?1
+          AND n.created_at > ?3
           AND LOWER(n.body) LIKE '%@' || LOWER(?1) || '%'
         UNION ALL
         -- MR mentions (scoped to candidate entities only)
@@ -862,6 +863,7 @@ fn build_mentioned_in_sql(project_clause: &str) -> String {
         LEFT JOIN note_ts_mr nt ON nt.merge_request_id = cm.id
         WHERE n.is_system = 0
           AND n.author_username != ?1
+          AND n.created_at > ?3
           AND LOWER(n.body) LIKE '%@' || LOWER(?1) || '%'
         ORDER BY 6 DESC
         LIMIT 500",
@@ -871,7 +873,8 @@ fn build_mentioned_in_sql(project_clause: &str) -> String {
 /// Query issues and MRs where the user is @mentioned but not assigned/authored/reviewing.
 ///
 /// Includes open items unconditionally, plus recently-closed/merged items
-/// (where `updated_at > recency_cutoff_ms`).
+/// (where `updated_at > recency_cutoff_ms`). Only considers mentions in notes
+/// created after `mention_cutoff_ms` (typically 30 days ago).
 ///
 /// Returns deduplicated results sorted by attention priority then recency.
 pub fn query_mentioned_in(
@@ -879,14 +882,16 @@ pub fn query_mentioned_in(
     username: &str,
     project_ids: &[i64],
     recency_cutoff_ms: i64,
+    mention_cutoff_ms: i64,
 ) -> Result<Vec<MeMention>> {
-    let project_clause = build_project_clause_at("p.id", project_ids, 3);
+    let project_clause = build_project_clause_at("p.id", project_ids, 4);
     // Materialized CTEs avoid pathological query plans for project-scoped mentions.
     let sql = build_mentioned_in_sql(&project_clause);
 
     let mut params: Vec<Box<dyn rusqlite::types::ToSql>> = Vec::new();
     params.push(Box::new(username.to_string()));
     params.push(Box::new(recency_cutoff_ms));
+    params.push(Box::new(mention_cutoff_ms));
     for &pid in project_ids {
         params.push(Box::new(pid));
     }

src/cli/commands/me/render_robot.rs

@@ -15,11 +15,12 @@ pub fn print_me_json(
     dashboard: &MeDashboard,
     elapsed_ms: u64,
     fields: Option<&[String]>,
+    gitlab_base_url: &str,
 ) -> crate::core::error::Result<()> {
     let envelope = MeJsonEnvelope {
         ok: true,
         data: MeDataJson::from_dashboard(dashboard),
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::with_base_url(elapsed_ms, gitlab_base_url),
     };
 
     let mut value = serde_json::to_value(&envelope)
@@ -478,4 +479,107 @@ mod tests {
         assert_eq!(value["data"]["cursor_reset"], serde_json::json!(true));
         assert_eq!(value["meta"]["elapsed_ms"], serde_json::json!(17));
     }
+
+    /// Integration test: full envelope serialization includes gitlab_base_url in meta.
+    /// Guards against drift where the wiring from run_me -> print_me_json -> JSON
+    /// could silently lose the base URL field.
+    #[test]
+    fn me_envelope_includes_gitlab_base_url_in_meta() {
+        let dashboard = MeDashboard {
+            username: "testuser".to_string(),
+            since_ms: Some(1_700_000_000_000),
+            summary: MeSummary {
+                project_count: 1,
+                open_issue_count: 0,
+                authored_mr_count: 0,
+                reviewing_mr_count: 0,
+                mentioned_in_count: 0,
+                needs_attention_count: 0,
+            },
+            open_issues: vec![],
+            open_mrs_authored: vec![],
+            reviewing_mrs: vec![],
+            mentioned_in: vec![],
+            activity: vec![],
+            since_last_check: None,
+        };
+
+        let envelope = MeJsonEnvelope {
+            ok: true,
+            data: MeDataJson::from_dashboard(&dashboard),
+            meta: RobotMeta::with_base_url(42, "https://gitlab.example.com"),
+        };
+
+        let value = serde_json::to_value(&envelope).unwrap();
+        assert_eq!(value["ok"], serde_json::json!(true));
+        assert_eq!(value["meta"]["elapsed_ms"], serde_json::json!(42));
+        assert_eq!(
+            value["meta"]["gitlab_base_url"],
+            serde_json::json!("https://gitlab.example.com")
+        );
+    }
+
+    /// Verify activity events carry the fields needed for URL construction
+    /// (entity_type, entity_iid, project) so consumers can combine with
+    /// meta.gitlab_base_url to build links.
+    #[test]
+    fn activity_event_carries_url_construction_fields() {
+        let dashboard = MeDashboard {
+            username: "testuser".to_string(),
+            since_ms: Some(1_700_000_000_000),
+            summary: MeSummary {
+                project_count: 1,
+                open_issue_count: 0,
+                authored_mr_count: 0,
+                reviewing_mr_count: 0,
+                mentioned_in_count: 0,
+                needs_attention_count: 0,
+            },
+            open_issues: vec![],
+            open_mrs_authored: vec![],
+            reviewing_mrs: vec![],
+            mentioned_in: vec![],
+            activity: vec![MeActivityEvent {
+                timestamp: 1_700_000_000_000,
+                event_type: ActivityEventType::Note,
+                entity_type: "mr".to_string(),
+                entity_iid: 99,
+                project_path: "group/repo".to_string(),
+                actor: Some("alice".to_string()),
+                is_own: false,
+                summary: "Commented on MR".to_string(),
+                body_preview: None,
+            }],
+            since_last_check: None,
+        };
+
+        let envelope = MeJsonEnvelope {
+            ok: true,
+            data: MeDataJson::from_dashboard(&dashboard),
+            meta: RobotMeta::with_base_url(0, "https://gitlab.example.com"),
+        };
+
+        let value = serde_json::to_value(&envelope).unwrap();
+        let event = &value["data"]["activity"][0];
+
+        // These three fields + meta.gitlab_base_url = complete URL
+        assert_eq!(event["entity_type"], "mr");
+        assert_eq!(event["entity_iid"], 99);
+        assert_eq!(event["project"], "group/repo");
+
+        // Consumer constructs: https://gitlab.example.com/group/repo/-/merge_requests/99
+        let base = value["meta"]["gitlab_base_url"].as_str().unwrap();
+        let project = event["project"].as_str().unwrap();
+        let entity_path = match event["entity_type"].as_str().unwrap() {
+            "issue" => "issues",
+            "mr" => "merge_requests",
+            other => panic!("unexpected entity_type: {other}"),
+        };
+        let iid = event["entity_iid"].as_i64().unwrap();
+        let url = format!("{base}/{project}/-/{entity_path}/{iid}");
+        assert_eq!(
+            url,
+            "https://gitlab.example.com/group/repo/-/merge_requests/99"
+        );
+    }
 }

src/cli/commands/mod.rs

@@ -5,6 +5,7 @@ pub mod cron;
 pub mod doctor;
 pub mod drift;
 pub mod embed;
+pub mod explain;
 pub mod file_history;
 pub mod generate_docs;
 pub mod ingest;
@@ -35,6 +36,7 @@ pub use cron::{
 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};
+pub use explain::{handle_explain, print_explain, print_explain_json, run_explain};
 pub use file_history::{print_file_history, print_file_history_json, run_file_history};
 pub use generate_docs::{print_generate_docs, print_generate_docs_json, run_generate_docs};
 pub use ingest::{

src/cli/commands/related.rs

@@ -558,7 +558,7 @@ pub fn print_related_human(response: &RelatedResponse) {
 }
 
 pub fn print_related_json(response: &RelatedResponse, elapsed_ms: u64) {
-    let meta = RobotMeta { elapsed_ms };
+    let meta = RobotMeta::new(elapsed_ms);
     let output = serde_json::json!({
         "ok": true,
         "data": response,

src/cli/commands/search.rs

@@ -1,6 +1,6 @@
 use std::collections::HashMap;
 
-use crate::cli::render::Theme;
+use crate::cli::render::{self, Theme};
 use serde::Serialize;
 
 use crate::Config;
@@ -20,11 +20,16 @@ use crate::search::{
 pub struct SearchResultDisplay {
     pub document_id: i64,
     pub source_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source_entity_iid: Option<i64>,
     pub title: String,
     pub url: Option<String>,
     pub author: Option<String>,
     pub created_at: Option<String>,
     pub updated_at: Option<String>,
+    /// Raw epoch ms for human rendering; not serialized to JSON.
+    #[serde(skip)]
+    pub updated_at_ms: Option<i64>,
     pub project_path: String,
     pub labels: Vec<String>,
     pub paths: Vec<String>,
@@ -216,11 +221,13 @@ pub async fn run_search(
         results.push(SearchResultDisplay {
             document_id: row.document_id,
             source_type: row.source_type.clone(),
+            source_entity_iid: row.source_entity_iid,
             title: row.title.clone().unwrap_or_default(),
             url: row.url.clone(),
             author: row.author.clone(),
             created_at: row.created_at.map(ms_to_iso),
             updated_at: row.updated_at.map(ms_to_iso),
+            updated_at_ms: row.updated_at,
             project_path: row.project_path.clone(),
             labels: row.labels.clone(),
             paths: row.paths.clone(),
@@ -242,6 +249,7 @@ pub async fn run_search(
 struct HydratedRow {
     document_id: i64,
     source_type: String,
+    source_entity_iid: Option<i64>,
     title: Option<String>,
     url: Option<String>,
     author: Option<String>,
@@ -268,7 +276,26 @@ fn hydrate_results(conn: &rusqlite::Connection, document_ids: &[i64]) -> Result<
                (SELECT json_group_array(dl.label_name)
                 FROM document_labels dl WHERE dl.document_id = d.id) AS labels_json,
                (SELECT json_group_array(dp.path)
-                FROM document_paths dp WHERE dp.document_id = d.id) AS paths_json
+                FROM document_paths dp WHERE dp.document_id = d.id) AS paths_json,
+               CASE d.source_type
+                 WHEN 'issue' THEN
+                   (SELECT i.iid FROM issues i WHERE i.id = d.source_id)
+                 WHEN 'merge_request' THEN
+                   (SELECT m.iid FROM merge_requests m WHERE m.id = d.source_id)
+                 WHEN 'discussion' THEN
+                   (SELECT COALESCE(
+                     (SELECT i.iid FROM issues i WHERE i.id = disc.issue_id),
+                     (SELECT m.iid FROM merge_requests m WHERE m.id = disc.merge_request_id)
+                   ) FROM discussions disc WHERE disc.id = d.source_id)
+                 WHEN 'note' THEN
+                   (SELECT COALESCE(
+                     (SELECT i.iid FROM issues i WHERE i.id = disc.issue_id),
+                     (SELECT m.iid FROM merge_requests m WHERE m.id = disc.merge_request_id)
+                   ) FROM notes n
+                   JOIN discussions disc ON disc.id = n.discussion_id
+                   WHERE n.id = d.source_id)
+                 ELSE NULL
+               END AS source_entity_iid
         FROM json_each(?1) AS j
         JOIN documents d ON d.id = j.value
         JOIN projects p ON p.id = d.project_id
@@ -293,6 +320,7 @@ fn hydrate_results(conn: &rusqlite::Connection, document_ids: &[i64]) -> Result<
                 project_path: row.get(8)?,
                 labels: parse_json_array(&labels_json),
                 paths: parse_json_array(&paths_json),
+                source_entity_iid: row.get(11)?,
             })
         })?
         .collect::<std::result::Result<Vec<_>, _>>()?;
@@ -309,6 +337,96 @@ fn parse_json_array(json: &str) -> Vec<String> {
         .collect()
 }
 
+/// Collapse newlines and runs of whitespace in a snippet into single spaces.
+///
+/// Document `content_text` includes multi-line metadata (Project:, URL:, Labels:, etc.).
+/// FTS5 snippet() preserves these newlines, causing unindented lines when rendered.
+fn collapse_newlines(s: &str) -> String {
+    let mut result = String::with_capacity(s.len());
+    let mut prev_was_space = false;
+    for c in s.chars() {
+        if c.is_ascii_whitespace() {
+            if !prev_was_space {
+                result.push(' ');
+                prev_was_space = true;
+            }
+        } else {
+            result.push(c);
+            prev_was_space = false;
+        }
+    }
+    result
+}
+
+/// Truncate a snippet to `max_visible` visible characters, respecting `<mark>` tag boundaries.
+///
+/// Counts only visible text (not tags) toward the limit, and ensures we never cut
+/// inside a `<mark>...</mark>` pair (which would break `render_snippet` highlighting).
+fn truncate_snippet(snippet: &str, max_visible: usize) -> String {
+    if max_visible < 4 {
+        return snippet.to_string();
+    }
+
+    let mut visible_count = 0;
+    let mut result = String::new();
+    let mut remaining = snippet;
+
+    while !remaining.is_empty() {
+        if let Some(start) = remaining.find("<mark>") {
+            // Count visible chars before the tag
+            let before = &remaining[..start];
+            let before_len = before.chars().count();
+            if visible_count + before_len >= max_visible.saturating_sub(3) {
+                // Truncate within the pre-tag text
+                let take = max_visible.saturating_sub(3).saturating_sub(visible_count);
+                let truncated: String = before.chars().take(take).collect();
+                result.push_str(&truncated);
+                result.push_str("...");
+                return result;
+            }
+            result.push_str(before);
+            visible_count += before_len;
+
+            // Find matching </mark>
+            let after_open = &remaining[start + 6..];
+            if let Some(end) = after_open.find("</mark>") {
+                let highlighted = &after_open[..end];
+                let hl_len = highlighted.chars().count();
+                if visible_count + hl_len >= max_visible.saturating_sub(3) {
+                    // Truncate within the highlighted text
+                    let take = max_visible.saturating_sub(3).saturating_sub(visible_count);
+                    let truncated: String = highlighted.chars().take(take).collect();
+                    result.push_str("<mark>");
+                    result.push_str(&truncated);
+                    result.push_str("</mark>...");
+                    return result;
+                }
+                result.push_str(&remaining[start..start + 6 + end + 7]);
+                visible_count += hl_len;
+                remaining = &after_open[end + 7..];
+            } else {
+                // Unclosed <mark> — treat rest as plain text
+                result.push_str(&remaining[start..]);
+                break;
+            }
+        } else {
+            // No more tags — handle remaining plain text
+            let rest_len = remaining.chars().count();
+            if visible_count + rest_len > max_visible && max_visible > 3 {
+                let take = max_visible.saturating_sub(3).saturating_sub(visible_count);
+                let truncated: String = remaining.chars().take(take).collect();
+                result.push_str(&truncated);
+                result.push_str("...");
+                return result;
+            }
+            result.push_str(remaining);
+            break;
+        }
+    }
+
+    result
+}
+
 /// Render FTS snippet with `<mark>` tags as terminal highlight style.
 fn render_snippet(snippet: &str) -> String {
     let mut result = String::new();
@@ -326,7 +444,7 @@ fn render_snippet(snippet: &str) -> String {
     result
 }
 
-pub fn print_search_results(response: &SearchResponse) {
+pub fn print_search_results(response: &SearchResponse, explain: bool) {
     if !response.warnings.is_empty() {
         for w in &response.warnings {
             eprintln!("{} {}", Theme::warning().render("Warning:"), w);
@@ -341,11 +459,13 @@ pub fn print_search_results(response: &SearchResponse) {
         return;
     }
 
+    // Phase 6: section divider header
     println!(
-        "\n   {} results for '{}'  {}",
-        Theme::bold().render(&response.total_results.to_string()),
-        Theme::bold().render(&response.query),
-        Theme::muted().render(&response.mode)
+        "{}",
+        render::section_divider(&format!(
+            "{} results for '{}'  {}",
+            response.total_results, response.query, response.mode
+        ))
     );
 
     for (i, result) in response.results.iter().enumerate() {
@@ -359,22 +479,75 @@ pub fn print_search_results(response: &SearchResponse) {
             _ => Theme::muted().render(&format!("{:>5}", &result.source_type)),
         };
 
-        // Title line: rank, type badge, title
-        println!(
-            "  {:>3}.  {}  {}",
-            Theme::muted().render(&(i + 1).to_string()),
-            type_badge,
-            Theme::bold().render(&result.title)
-        );
+        // Phase 1: entity ref (e.g. #42 or !99)
+        let entity_ref = result
+            .source_entity_iid
+            .map(|iid| match result.source_type.as_str() {
+                "issue" | "discussion" | "note" => Theme::issue_ref().render(&format!("#{iid}")),
+                "merge_request" => Theme::mr_ref().render(&format!("!{iid}")),
+                _ => String::new(),
+            });
 
-        // Metadata: project, author, labels — compact middle-dot line
+        // Phase 3: relative time
+        let time_str = result
+            .updated_at_ms
+            .map(|ms| Theme::dim().render(&render::format_relative_time_compact(ms)));
+
+        // Phase 2: build prefix, compute indent from its visible width
+        let prefix = format!("  {:>3}.  {}  ", i + 1, type_badge);
+        let indent = " ".repeat(render::visible_width(&prefix));
+
+        // Title line: rank, type badge, entity ref, title, relative time
+        let mut title_line = prefix;
+        if let Some(ref eref) = entity_ref {
+            title_line.push_str(eref);
+            title_line.push_str("  ");
+        }
+        title_line.push_str(&Theme::bold().render(&result.title));
+        if let Some(ref time) = time_str {
+            title_line.push_str("  ");
+            title_line.push_str(time);
+        }
+        println!("{title_line}");
+
+        // Metadata: project, author — compact middle-dot line
         let sep = Theme::muted().render(" \u{b7} ");
         let mut meta_parts: Vec<String> = Vec::new();
         meta_parts.push(Theme::muted().render(&result.project_path));
         if let Some(ref author) = result.author {
             meta_parts.push(Theme::username().render(&format!("@{author}")));
         }
-        if !result.labels.is_empty() {
+        println!("{indent}{}", meta_parts.join(&sep));
+
+        // Phase 5: limit snippet to ~2 terminal lines.
+        // First collapse newlines — content_text includes multi-line metadata
+        // (Project:, URL:, Labels:, etc.) that would print at column 0.
+        let collapsed = collapse_newlines(&result.snippet);
+        // Truncate based on visible text length (excluding <mark></mark> tags)
+        // to avoid cutting inside a highlight tag pair.
+        let max_snippet_width =
+            render::terminal_width().saturating_sub(render::visible_width(&indent));
+        let max_snippet_chars = max_snippet_width.saturating_mul(2);
+        let snippet = truncate_snippet(&collapsed, max_snippet_chars);
+        let rendered = render_snippet(&snippet);
+        println!("{indent}{rendered}");
+
+        if let Some(ref explain_data) = result.explain {
+            let mut explain_line = format!(
+                "{indent}{} vec={} fts={} rrf={:.4}",
+                Theme::accent().render("explain"),
+                explain_data
+                    .vector_rank
+                    .map(|r| r.to_string())
+                    .unwrap_or_else(|| "-".into()),
+                explain_data
+                    .fts_rank
+                    .map(|r| r.to_string())
+                    .unwrap_or_else(|| "-".into()),
+                explain_data.rrf_score
+            );
+            // Phase 5: labels shown only in explain mode
+            if explain && !result.labels.is_empty() {
                 let label_str = if result.labels.len() <= 3 {
                     result.labels.join(", ")
                 } else {
@@ -384,27 +557,26 @@ pub fn print_search_results(response: &SearchResponse) {
                         result.labels.len() - 2
                     )
                 };
-            meta_parts.push(Theme::muted().render(&label_str));
+                explain_line.push_str(&format!("  {}", Theme::muted().render(&label_str)));
+            }
+            println!("{explain_line}");
+        }
     }
-        println!("        {}", meta_parts.join(&sep));
 
-        // Snippet with highlight styling
-        let rendered = render_snippet(&result.snippet);
-        println!("        {rendered}");
-
-        if let Some(ref explain) = result.explain {
+    // Phase 4: drill-down hint footer
+    if let Some(first) = response.results.first()
+        && let Some(iid) = first.source_entity_iid
+    {
+        let cmd = match first.source_type.as_str() {
+            "issue" | "discussion" | "note" => Some(format!("lore issues {iid}")),
+            "merge_request" => Some(format!("lore mrs {iid}")),
+            _ => None,
+        };
+        if let Some(cmd) = cmd {
             println!(
-                "        {} vec={} fts={} rrf={:.4}",
-                Theme::accent().render("explain"),
-                explain
-                    .vector_rank
-                    .map(|r| r.to_string())
-                    .unwrap_or_else(|| "-".into()),
-                explain
-                    .fts_rank
-                    .map(|r| r.to_string())
-                    .unwrap_or_else(|| "-".into()),
-                explain.rrf_score
+                "\n  {} {}",
+                Theme::dim().render("Tip:"),
+                Theme::dim().render(&format!("{cmd} for details"))
             );
         }
     }
@@ -444,3 +616,89 @@ pub fn print_search_results_json(
         Err(e) => eprintln!("Error serializing to JSON: {e}"),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn truncate_snippet_short_text_unchanged() {
+        let s = "hello world";
+        assert_eq!(truncate_snippet(s, 100), "hello world");
+    }
+
+    #[test]
+    fn truncate_snippet_plain_text_truncated() {
+        let s = "this is a long string that exceeds the limit";
+        let result = truncate_snippet(s, 20);
+        assert!(result.ends_with("..."), "got: {result}");
+        // Visible chars should be <= 20
+        assert!(result.chars().count() <= 20, "got: {result}");
+    }
+
+    #[test]
+    fn truncate_snippet_preserves_mark_tags() {
+        let s = "some text <mark>keyword</mark> and more text here that is long";
+        let result = truncate_snippet(s, 30);
+        // Should not cut inside a <mark> pair
+        let open_count = result.matches("<mark>").count();
+        let close_count = result.matches("</mark>").count();
+        assert_eq!(open_count, close_count, "unbalanced tags in: {result}");
+    }
+
+    #[test]
+    fn truncate_snippet_cuts_before_mark_tag() {
+        let s = "a]very long prefix that exceeds the limit <mark>word</mark>";
+        let result = truncate_snippet(s, 15);
+        assert!(result.ends_with("..."), "got: {result}");
+        // The <mark> tag should not appear since we truncated before reaching it
+        assert!(
+            !result.contains("<mark>"),
+            "should not include tag: {result}"
+        );
+    }
+
+    #[test]
+    fn truncate_snippet_does_not_count_tags_as_visible() {
+        // With tags, raw length is 42 chars. Without tags, visible is 29.
+        let s = "prefix <mark>keyword</mark> suffix text";
+        // If max_visible = 35, the visible text (29 chars) fits — should NOT truncate
+        let result = truncate_snippet(s, 35);
+        assert_eq!(result, s, "should not truncate when visible text fits");
+    }
+
+    #[test]
+    fn truncate_snippet_small_limit_returns_as_is() {
+        let s = "text <mark>x</mark>";
+        // Very small limit should return as-is (guard clause)
+        assert_eq!(truncate_snippet(s, 3), s);
+    }
+
+    #[test]
+    fn collapse_newlines_flattens_multiline_metadata() {
+        let s = "[[Issue]] #4018: Remove math.js\nProject: vs/typescript-code\nURL: https://example.com\nLabels: []";
+        let result = collapse_newlines(s);
+        assert!(
+            !result.contains('\n'),
+            "should not contain newlines: {result}"
+        );
+        assert_eq!(
+            result,
+            "[[Issue]] #4018: Remove math.js Project: vs/typescript-code URL: https://example.com Labels: []"
+        );
+    }
+
+    #[test]
+    fn collapse_newlines_preserves_mark_tags() {
+        let s = "first line\n<mark>keyword</mark>\nsecond line";
+        let result = collapse_newlines(s);
+        assert_eq!(result, "first line <mark>keyword</mark> second line");
+    }
+
+    #[test]
+    fn collapse_newlines_collapses_runs_of_whitespace() {
+        let s = "a  \n\n  b\t\tc";
+        let result = collapse_newlines(s);
+        assert_eq!(result, "a b c");
+    }
+}

src/cli/commands/show/issue.rs

@@ -44,6 +44,7 @@ pub struct DiscussionDetail {
 
 #[derive(Debug, Serialize)]
 pub struct NoteDetail {
+    pub gitlab_id: i64,
     pub author_username: String,
     pub body: String,
     pub created_at: i64,
@@ -277,7 +278,7 @@ fn get_issue_discussions(conn: &Connection, issue_id: i64) -> Result<Vec<Discuss
         .collect::<std::result::Result<Vec<_>, _>>()?;
 
     let mut note_stmt = conn.prepare(
-        "SELECT author_username, body, created_at, is_system
+        "SELECT gitlab_id, author_username, body, created_at, is_system
          FROM notes
          WHERE discussion_id = ?
          ORDER BY position",
@@ -287,11 +288,12 @@ fn get_issue_discussions(conn: &Connection, issue_id: i64) -> Result<Vec<Discuss
     for (disc_id, individual_note) in disc_rows {
         let notes: Vec<NoteDetail> = note_stmt
             .query_map([disc_id], |row| {
-                let is_system: i64 = row.get(3)?;
+                let is_system: i64 = row.get(4)?;
                 Ok(NoteDetail {
-                    author_username: row.get(0)?,
-                    body: row.get(1)?,
-                    created_at: row.get(2)?,
+                    gitlab_id: row.get(0)?,
+                    author_username: row.get(1)?,
+                    body: row.get(2)?,
+                    created_at: row.get(3)?,
                     is_system: is_system == 1,
                 })
             })?

src/cli/commands/show/mr.rs

@@ -29,6 +29,7 @@ pub struct MrDiscussionDetail {
 
 #[derive(Debug, Serialize)]
 pub struct MrNoteDetail {
+    pub gitlab_id: i64,
     pub author_username: String,
     pub body: String,
     pub created_at: i64,
@@ -224,7 +225,7 @@ fn get_mr_discussions(conn: &Connection, mr_id: i64) -> Result<Vec<MrDiscussionD
         .collect::<std::result::Result<Vec<_>, _>>()?;
 
     let mut note_stmt = conn.prepare(
-        "SELECT author_username, body, created_at, is_system,
+        "SELECT gitlab_id, author_username, body, created_at, is_system,
                 position_old_path, position_new_path, position_old_line,
                 position_new_line, position_type
          FROM notes
@@ -236,12 +237,12 @@ fn get_mr_discussions(conn: &Connection, mr_id: i64) -> Result<Vec<MrDiscussionD
     for (disc_id, individual_note) in disc_rows {
         let notes: Vec<MrNoteDetail> = note_stmt
             .query_map([disc_id], |row| {
-                let is_system: i64 = row.get(3)?;
-                let old_path: Option<String> = row.get(4)?;
-                let new_path: Option<String> = row.get(5)?;
-                let old_line: Option<i64> = row.get(6)?;
-                let new_line: Option<i64> = row.get(7)?;
-                let position_type: Option<String> = row.get(8)?;
+                let is_system: i64 = row.get(4)?;
+                let old_path: Option<String> = row.get(5)?;
+                let new_path: Option<String> = row.get(6)?;
+                let old_line: Option<i64> = row.get(7)?;
+                let new_line: Option<i64> = row.get(8)?;
+                let position_type: Option<String> = row.get(9)?;
 
                 let position = if old_path.is_some()
                     || new_path.is_some()
@@ -260,9 +261,10 @@ fn get_mr_discussions(conn: &Connection, mr_id: i64) -> Result<Vec<MrDiscussionD
                 };
 
                 Ok(MrNoteDetail {
-                    author_username: row.get(0)?,
-                    body: row.get(1)?,
-                    created_at: row.get(2)?,
+                    gitlab_id: row.get(0)?,
+                    author_username: row.get(1)?,
+                    body: row.get(2)?,
+                    created_at: row.get(3)?,
                     is_system: is_system == 1,
                     position,
                 })

src/cli/commands/show/render.rs

@@ -398,6 +398,7 @@ pub struct DiscussionDetailJson {
 
 #[derive(Serialize)]
 pub struct NoteDetailJson {
+    pub gitlab_id: i64,
     pub author_username: String,
     pub body: String,
     pub created_at: String,
@@ -458,6 +459,7 @@ impl From<&DiscussionDetail> for DiscussionDetailJson {
 impl From<&NoteDetail> for NoteDetailJson {
     fn from(note: &NoteDetail) -> Self {
         Self {
+            gitlab_id: note.gitlab_id,
             author_username: note.author_username.clone(),
             body: note.body.clone(),
             created_at: ms_to_iso(note.created_at),
@@ -497,6 +499,7 @@ pub struct MrDiscussionDetailJson {
 
 #[derive(Serialize)]
 pub struct MrNoteDetailJson {
+    pub gitlab_id: i64,
     pub author_username: String,
     pub body: String,
     pub created_at: String,
@@ -542,6 +545,7 @@ impl From<&MrDiscussionDetail> for MrDiscussionDetailJson {
 impl From<&MrNoteDetail> for MrNoteDetailJson {
     fn from(note: &MrNoteDetail) -> Self {
         Self {
+            gitlab_id: note.gitlab_id,
             author_username: note.author_username.clone(),
             body: note.body.clone(),
             created_at: ms_to_iso(note.created_at),
@@ -553,7 +557,7 @@ impl From<&MrNoteDetail> for MrNoteDetailJson {
 
 pub fn print_show_issue_json(issue: &IssueDetail, elapsed_ms: u64) {
     let json_result = IssueDetailJson::from(issue);
-    let meta = RobotMeta { elapsed_ms };
+    let meta = RobotMeta::new(elapsed_ms);
     let output = serde_json::json!({
         "ok": true,
         "data": json_result,
@@ -567,7 +571,7 @@ pub fn print_show_issue_json(issue: &IssueDetail, elapsed_ms: u64) {
 
 pub fn print_show_mr_json(mr: &MrDetail, elapsed_ms: u64) {
     let json_result = MrDetailJson::from(mr);
-    let meta = RobotMeta { elapsed_ms };
+    let meta = RobotMeta::new(elapsed_ms);
     let output = serde_json::json!({
         "ok": true,
         "data": json_result,

src/cli/commands/stats.rs

@@ -583,7 +583,7 @@ pub fn print_stats_json(result: &StatsResult, elapsed_ms: u64) {
                 }),
             }),
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
     match serde_json::to_string(&output) {
         Ok(json) => println!("{json}"),

src/cli/commands/sync_status.rs

@@ -313,7 +313,7 @@ pub fn print_sync_status_json(result: &SyncStatusResult, elapsed_ms: u64) {
                 system_notes: result.summary.system_note_count,
             },
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
 
     match serde_json::to_string(&output) {

src/cli/commands/trace.rs

@@ -1,4 +1,5 @@
 use crate::cli::render::{Icons, Theme};
+use crate::core::error::{LoreError, Result};
 use crate::core::trace::{TraceChain, TraceResult};
 
 /// Parse a path with optional `:line` suffix.
@@ -152,7 +153,11 @@ fn truncate_body(body: &str, max: usize) -> String {
     format!("{}...", &body[..boundary])
 }
 
-pub fn print_trace_json(result: &TraceResult, elapsed_ms: u64, line_requested: Option<u32>) {
+pub fn print_trace_json(
+    result: &TraceResult,
+    elapsed_ms: u64,
+    line_requested: Option<u32>,
+) -> Result<()> {
     // Truncate discussion bodies for token efficiency in robot mode
     let chains: Vec<serde_json::Value> = result
         .trace_chains
@@ -205,7 +210,12 @@ pub fn print_trace_json(result: &TraceResult, elapsed_ms: u64, line_requested: O
         }
     });
 
-    println!("{}", serde_json::to_string(&output).unwrap_or_default());
+    println!(
+        "{}",
+        serde_json::to_string(&output)
+            .map_err(|e| LoreError::Other(format!("JSON serialization failed: {e}")))?
+    );
+    Ok(())
 }
 
 #[cfg(test)]

src/cli/commands/who/mod.rs

@@ -376,7 +376,7 @@ pub fn print_who_json(run: &WhoRun, args: &WhoArgs, elapsed_ms: u64) {
             resolved_input,
             result: data,
         },
-        meta: RobotMeta { elapsed_ms },
+        meta: RobotMeta::new(elapsed_ms),
     };
 
     let mut value = serde_json::to_value(&output).unwrap_or_else(|e| {

src/cli/mod.rs

@@ -277,6 +277,44 @@ pub enum Commands {
     /// Trace why code was introduced: file -> MR -> issue -> discussion
     Trace(TraceArgs),
 
+    /// Auto-generate a structured narrative of an issue or MR
+    #[command(after_help = "\x1b[1mExamples:\x1b[0m
+  lore explain issues 42                  # Narrative for issue #42
+  lore explain mrs 99 -p group/repo       # Narrative for MR !99 in specific project
+  lore -J explain issues 42               # JSON output for automation
+  lore explain issues 42 --sections key_decisions,open_threads  # Specific sections only
+  lore explain issues 42 --since 30d      # Narrative scoped to last 30 days
+  lore explain issues 42 --no-timeline    # Skip timeline (faster)")]
+    Explain {
+        /// Entity type: "issues" or "mrs" (singular forms also accepted)
+        #[arg(value_parser = ["issues", "mrs", "issue", "mr"])]
+        entity_type: String,
+
+        /// Entity IID
+        iid: i64,
+
+        /// Scope to project (fuzzy match)
+        #[arg(short, long)]
+        project: Option<String>,
+
+        /// Select specific sections (comma-separated)
+        /// Valid: entity, description, key_decisions, activity, open_threads, related, timeline
+        #[arg(long, value_delimiter = ',', help_heading = "Output")]
+        sections: Option<Vec<String>>,
+
+        /// Skip timeline excerpt (faster execution)
+        #[arg(long, help_heading = "Output")]
+        no_timeline: bool,
+
+        /// Maximum key decisions to include
+        #[arg(long, default_value = "10", help_heading = "Output")]
+        max_decisions: usize,
+
+        /// Time scope for events/notes (e.g. 7d, 2w, 1m, or YYYY-MM-DD)
+        #[arg(long, help_heading = "Filters")]
+        since: Option<String>,
+    },
+
     /// Detect discussion divergence from original intent
     #[command(after_help = "\x1b[1mExamples:\x1b[0m
   lore drift issues 42                    # Check drift on issue #42
@@ -381,17 +419,6 @@ pub enum Commands {
         source_branch: Option<String>,
     },
 
-    #[command(hide = true)]
-    Show {
-        #[arg(value_parser = ["issue", "mr"])]
-        entity: String,
-
-        iid: i64,
-
-        #[arg(long)]
-        project: Option<String>,
-    },
-
     #[command(hide = true, name = "auth-test")]
     AuthTest,
 

src/cli/render.rs

@@ -569,6 +569,32 @@ pub fn terminal_width() -> usize {
     80
 }
 
+/// Strip ANSI escape codes (SGR sequences) from a string.
+pub fn strip_ansi(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    let mut chars = s.chars();
+    while let Some(c) = chars.next() {
+        if c == '\x1b' {
+            // Consume `[`, then digits/semicolons, then the final letter
+            if chars.next() == Some('[') {
+                for c in chars.by_ref() {
+                    if c.is_ascii_alphabetic() {
+                        break;
+                    }
+                }
+            }
+        } else {
+            out.push(c);
+        }
+    }
+    out
+}
+
+/// Compute the visible width of a string that may contain ANSI escape sequences.
+pub fn visible_width(s: &str) -> usize {
+    strip_ansi(s).chars().count()
+}
+
 /// Truncate a string to `max` characters, appending "..." if truncated.
 pub fn truncate(s: &str, max: usize) -> String {
     if max < 4 {
@@ -1459,24 +1485,19 @@ mod tests {
 
     // ── helpers ──
 
-    /// Strip ANSI escape codes (SGR sequences) for content assertions.
+    /// Delegate to the public `strip_ansi` for test assertions.
     fn strip_ansi(s: &str) -> String {
-        let mut out = String::with_capacity(s.len());
-        let mut chars = s.chars();
-        while let Some(c) = chars.next() {
-            if c == '\x1b' {
-                // Consume `[`, then digits/semicolons, then the final letter
-                if chars.next() == Some('[') {
-                    for c in chars.by_ref() {
-                        if c.is_ascii_alphabetic() {
-                            break;
+        super::strip_ansi(s)
     }
+
+    #[test]
+    fn visible_width_strips_ansi() {
+        let styled = "\x1b[1mhello\x1b[0m".to_string();
+        assert_eq!(super::visible_width(&styled), 5);
     }
-                }
-            } else {
-                out.push(c);
-            }
-        }
-        out
+
+    #[test]
+    fn visible_width_plain_string() {
+        assert_eq!(super::visible_width("hello"), 5);
     }
 }

src/cli/robot.rs

@@ -3,6 +3,26 @@ use serde::Serialize;
 #[derive(Debug, Serialize)]
 pub struct RobotMeta {
     pub elapsed_ms: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub gitlab_base_url: Option<String>,
+}
+
+impl RobotMeta {
+    /// Standard meta with timing only.
+    pub fn new(elapsed_ms: u64) -> Self {
+        Self {
+            elapsed_ms,
+            gitlab_base_url: None,
+        }
+    }
+
+    /// Meta with GitLab base URL for URL construction by consumers.
+    pub fn with_base_url(elapsed_ms: u64, base_url: &str) -> Self {
+        Self {
+            elapsed_ms,
+            gitlab_base_url: Some(base_url.trim_end_matches('/').to_string()),
+        }
+    }
 }
 
 /// Filter JSON object fields in-place for `--fields` support.
@@ -36,7 +56,13 @@ pub fn expand_fields_preset(fields: &[String], entity: &str) -> Vec<String> {
                 .iter()
                 .map(|s| (*s).to_string())
                 .collect(),
-            "search" => ["document_id", "title", "source_type", "score"]
+            "search" => [
+                "document_id",
+                "title",
+                "source_type",
+                "source_entity_iid",
+                "score",
+            ]
             .iter()
             .map(|s| (*s).to_string())
             .collect(),
@@ -133,4 +159,27 @@ mod tests {
         let expanded = expand_fields_preset(&fields, "notes");
         assert_eq!(expanded, ["id", "body"]);
     }
+
+    #[test]
+    fn meta_new_omits_base_url() {
+        let meta = RobotMeta::new(42);
+        let json = serde_json::to_value(&meta).unwrap();
+        assert_eq!(json["elapsed_ms"], 42);
+        assert!(json.get("gitlab_base_url").is_none());
+    }
+
+    #[test]
+    fn meta_with_base_url_includes_it() {
+        let meta = RobotMeta::with_base_url(99, "https://gitlab.example.com");
+        let json = serde_json::to_value(&meta).unwrap();
+        assert_eq!(json["elapsed_ms"], 99);
+        assert_eq!(json["gitlab_base_url"], "https://gitlab.example.com");
+    }
+
+    #[test]
+    fn meta_with_base_url_strips_trailing_slash() {
+        let meta = RobotMeta::with_base_url(0, "https://gitlab.example.com/");
+        let json = serde_json::to_value(&meta).unwrap();
+        assert_eq!(json["gitlab_base_url"], "https://gitlab.example.com");
+    }
 }

src/core/error.rs

@@ -28,8 +28,11 @@ pub enum ErrorCode {
     OllamaUnavailable,
     OllamaModelNotFound,
     EmbeddingFailed,
+    EmbeddingsNotBuilt,
     NotFound,
     Ambiguous,
+    HealthCheckFailed,
+    UsageError,
     SurgicalPreflightFailed,
 }
 
@@ -52,8 +55,11 @@ impl std::fmt::Display for ErrorCode {
             Self::OllamaUnavailable => "OLLAMA_UNAVAILABLE",
             Self::OllamaModelNotFound => "OLLAMA_MODEL_NOT_FOUND",
             Self::EmbeddingFailed => "EMBEDDING_FAILED",
+            Self::EmbeddingsNotBuilt => "EMBEDDINGS_NOT_BUILT",
             Self::NotFound => "NOT_FOUND",
             Self::Ambiguous => "AMBIGUOUS",
+            Self::HealthCheckFailed => "HEALTH_CHECK_FAILED",
+            Self::UsageError => "USAGE_ERROR",
             Self::SurgicalPreflightFailed => "SURGICAL_PREFLIGHT_FAILED",
         };
         write!(f, "{code}")
@@ -79,8 +85,11 @@ impl ErrorCode {
             Self::OllamaUnavailable => 14,
             Self::OllamaModelNotFound => 15,
             Self::EmbeddingFailed => 16,
+            Self::EmbeddingsNotBuilt => 21,
             Self::NotFound => 17,
             Self::Ambiguous => 18,
+            Self::HealthCheckFailed => 19,
+            Self::UsageError => 2,
             // Shares exit code 6 with GitLabNotFound — same semantic category (resource not found).
             // Robot consumers distinguish via ErrorCode string, not exit code.
             Self::SurgicalPreflightFailed => 6,
@@ -201,7 +210,7 @@ impl LoreError {
             Self::OllamaUnavailable { .. } => ErrorCode::OllamaUnavailable,
             Self::OllamaModelNotFound { .. } => ErrorCode::OllamaModelNotFound,
             Self::EmbeddingFailed { .. } => ErrorCode::EmbeddingFailed,
-            Self::EmbeddingsNotBuilt => ErrorCode::EmbeddingFailed,
+            Self::EmbeddingsNotBuilt => ErrorCode::EmbeddingsNotBuilt,
             Self::SurgicalPreflightFailed { .. } => ErrorCode::SurgicalPreflightFailed,
         }
     }

src/core/project_tests.rs

@@ -154,3 +154,25 @@ fn test_percent_not_wildcard() {
     let id = resolve_project(&conn, "a%b").unwrap();
     assert_eq!(id, 1);
 }
+
+#[test]
+fn test_lookup_by_gitlab_project_id() {
+    use crate::test_support::{insert_project as insert_proj, setup_test_db};
+
+    let conn = setup_test_db();
+    insert_proj(&conn, 1, "team/alpha");
+    insert_proj(&conn, 2, "team/beta");
+
+    // insert_project sets gitlab_project_id = id * 100
+    let path: String = conn
+        .query_row(
+            "SELECT path_with_namespace FROM projects
+             WHERE gitlab_project_id = ?1
+             ORDER BY id LIMIT 1",
+            rusqlite::params![200_i64],
+            |row| row.get(0),
+        )
+        .unwrap();
+
+    assert_eq!(path, "team/beta");
+}

src/embedding/chunk_ids.rs

@@ -1,70 +0,0 @@
-pub const CHUNK_ROWID_MULTIPLIER: i64 = 1000;
-
-pub fn encode_rowid(document_id: i64, chunk_index: i64) -> i64 {
-    assert!(
-        (0..CHUNK_ROWID_MULTIPLIER).contains(&chunk_index),
-        "chunk_index {chunk_index} out of range [0, {CHUNK_ROWID_MULTIPLIER})"
-    );
-    document_id
-        .checked_mul(CHUNK_ROWID_MULTIPLIER)
-        .and_then(|v| v.checked_add(chunk_index))
-        .unwrap_or_else(|| {
-            panic!("encode_rowid overflow: document_id={document_id}, chunk_index={chunk_index}")
-        })
-}
-
-pub fn decode_rowid(rowid: i64) -> (i64, i64) {
-    assert!(
-        rowid >= 0,
-        "decode_rowid called with negative rowid: {rowid}"
-    );
-    let document_id = rowid / CHUNK_ROWID_MULTIPLIER;
-    let chunk_index = rowid % CHUNK_ROWID_MULTIPLIER;
-    (document_id, chunk_index)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_encode_single_chunk() {
-        assert_eq!(encode_rowid(1, 0), 1000);
-    }
-
-    #[test]
-    fn test_encode_multi_chunk() {
-        assert_eq!(encode_rowid(1, 5), 1005);
-    }
-
-    #[test]
-    fn test_encode_specific_values() {
-        assert_eq!(encode_rowid(42, 0), 42000);
-        assert_eq!(encode_rowid(42, 5), 42005);
-    }
-
-    #[test]
-    fn test_decode_zero_chunk() {
-        assert_eq!(decode_rowid(42000), (42, 0));
-    }
-
-    #[test]
-    fn test_decode_roundtrip() {
-        for doc_id in [0, 1, 42, 100, 999, 10000] {
-            for chunk_idx in [0, 1, 5, 99, 999] {
-                let rowid = encode_rowid(doc_id, chunk_idx);
-                let (decoded_doc, decoded_chunk) = decode_rowid(rowid);
-                assert_eq!(
-                    (decoded_doc, decoded_chunk),
-                    (doc_id, chunk_idx),
-                    "Roundtrip failed for doc_id={doc_id}, chunk_idx={chunk_idx}"
-                );
-            }
-        }
-    }
-
-    #[test]
-    fn test_multiplier_value() {
-        assert_eq!(CHUNK_ROWID_MULTIPLIER, 1000);
-    }
-}

src/embedding/chunking.rs

@@ -1,107 +0,0 @@
-pub const CHUNK_MAX_BYTES: usize = 1_500;
-
-pub const EXPECTED_DIMS: usize = 768;
-
-pub const CHUNK_OVERLAP_CHARS: usize = 200;
-
-pub fn split_into_chunks(content: &str) -> Vec<(usize, String)> {
-    if content.is_empty() {
-        return Vec::new();
-    }
-
-    if content.len() <= CHUNK_MAX_BYTES {
-        return vec![(0, content.to_string())];
-    }
-
-    let mut chunks: Vec<(usize, String)> = Vec::new();
-    let mut start = 0;
-    let mut chunk_index = 0;
-
-    while start < content.len() {
-        let remaining = &content[start..];
-        if remaining.len() <= CHUNK_MAX_BYTES {
-            chunks.push((chunk_index, remaining.to_string()));
-            break;
-        }
-
-        let end = floor_char_boundary(content, start + CHUNK_MAX_BYTES);
-        let window = &content[start..end];
-
-        let split_at = find_paragraph_break(window)
-            .or_else(|| find_sentence_break(window))
-            .or_else(|| find_word_break(window))
-            .unwrap_or(window.len());
-
-        let chunk_text = &content[start..start + split_at];
-        chunks.push((chunk_index, chunk_text.to_string()));
-
-        let advance = if split_at > CHUNK_OVERLAP_CHARS {
-            split_at - CHUNK_OVERLAP_CHARS
-        } else {
-            split_at
-        }
-        .max(1);
-        let old_start = start;
-        start += advance;
-        // Ensure start lands on a char boundary after overlap subtraction
-        start = floor_char_boundary(content, start);
-        // Guarantee forward progress: multi-byte chars can cause
-        // floor_char_boundary to round back to old_start
-        if start <= old_start {
-            start = old_start
-                + content[old_start..]
-                    .chars()
-                    .next()
-                    .map_or(1, |c| c.len_utf8());
-        }
-        chunk_index += 1;
-    }
-
-    chunks
-}
-
-fn find_paragraph_break(window: &str) -> Option<usize> {
-    let search_start = floor_char_boundary(window, window.len() * 2 / 3);
-    window[search_start..]
-        .rfind("\n\n")
-        .map(|pos| search_start + pos + 2)
-        .or_else(|| window[..search_start].rfind("\n\n").map(|pos| pos + 2))
-}
-
-fn find_sentence_break(window: &str) -> Option<usize> {
-    let search_start = floor_char_boundary(window, window.len() / 2);
-    for pat in &[". ", "? ", "! "] {
-        if let Some(pos) = window[search_start..].rfind(pat) {
-            return Some(search_start + pos + pat.len());
-        }
-    }
-    for pat in &[". ", "? ", "! "] {
-        if let Some(pos) = window[..search_start].rfind(pat) {
-            return Some(pos + pat.len());
-        }
-    }
-    None
-}
-
-fn find_word_break(window: &str) -> Option<usize> {
-    let search_start = floor_char_boundary(window, window.len() / 2);
-    window[search_start..]
-        .rfind(' ')
-        .map(|pos| search_start + pos + 1)
-        .or_else(|| window[..search_start].rfind(' ').map(|pos| pos + 1))
-}
-
-fn floor_char_boundary(s: &str, idx: usize) -> usize {
-    if idx >= s.len() {
-        return s.len();
-    }
-    let mut i = idx;
-    while i > 0 && !s.is_char_boundary(i) {
-        i -= 1;
-    }
-    i
-}
-
-#[cfg(test)]
-#[path = "chunking_tests.rs"]
-mod tests;

src/gitlab/transformers/discussion.rs

@@ -53,14 +53,8 @@ pub struct NormalizedNote {
     pub position_head_sha: Option<String>,
 }
 
-fn parse_timestamp(ts: &str) -> i64 {
-    match iso_to_ms(ts) {
-        Some(ms) => ms,
-        None => {
-            warn!(timestamp = ts, "Invalid timestamp, defaulting to epoch 0");
-            0
-        }
-    }
+fn parse_timestamp(ts: &str) -> Result<i64, String> {
+    iso_to_ms_strict(ts)
 }
 
 pub fn transform_discussion(
@@ -133,7 +127,15 @@ pub fn transform_notes(
         .notes
         .iter()
         .enumerate()
-        .map(|(idx, note)| transform_single_note(note, local_project_id, idx as i32, now))
+        .filter_map(|(idx, note)| {
+            match transform_single_note(note, local_project_id, idx as i32, now) {
+                Ok(n) => Some(n),
+                Err(e) => {
+                    warn!(note_id = note.id, error = %e, "Skipping note with invalid timestamp");
+                    None
+                }
+            }
+        })
         .collect()
 }
 
@@ -142,7 +144,10 @@ fn transform_single_note(
     local_project_id: i64,
     position: i32,
     now: i64,
-) -> NormalizedNote {
+) -> Result<NormalizedNote, String> {
+    let created_at = parse_timestamp(&note.created_at)?;
+    let updated_at = parse_timestamp(&note.updated_at)?;
+
     let (
         position_old_path,
         position_new_path,
@@ -156,7 +161,7 @@ fn transform_single_note(
         position_head_sha,
     ) = extract_position_fields(&note.position);
 
-    NormalizedNote {
+    Ok(NormalizedNote {
         gitlab_id: note.id,
         project_id: local_project_id,
         note_type: note.note_type.clone(),
@@ -164,8 +169,8 @@ fn transform_single_note(
         author_id: Some(note.author.id),
         author_username: note.author.username.clone(),
         body: note.body.clone(),
-        created_at: parse_timestamp(&note.created_at),
-        updated_at: parse_timestamp(&note.updated_at),
+        created_at,
+        updated_at,
         last_seen_at: now,
         position,
         resolvable: note.resolvable,
@@ -182,7 +187,7 @@ fn transform_single_note(
         position_base_sha,
         position_start_sha,
         position_head_sha,
-    }
+    })
 }
 
 #[allow(clippy::type_complexity)]

src/ingestion/discussions_tests.rs

@@ -40,7 +40,11 @@ fn setup() -> Connection {
 }
 
 fn get_discussion_id(conn: &Connection) -> i64 {
-    conn.query_row("SELECT id FROM discussions LIMIT 1", [], |row| row.get(0))
+    conn.query_row(
+        "SELECT id FROM discussions ORDER BY id LIMIT 1",
+        [],
+        |row| row.get(0),
+    )
     .unwrap()
 }
 

src/ingestion/mr_discussions.rs

@@ -786,7 +786,11 @@ mod tests {
     }
 
     fn get_mr_discussion_id(conn: &Connection) -> i64 {
-        conn.query_row("SELECT id FROM discussions LIMIT 1", [], |row| row.get(0))
+        conn.query_row(
+            "SELECT id FROM discussions ORDER BY id LIMIT 1",
+            [],
+            |row| row.get(0),
+        )
         .unwrap()
     }
 

src/ingestion/storage/queue.rs

@@ -242,14 +242,16 @@ mod tests {
         .unwrap();
 
         let project_id: i64 = conn
-            .query_row("SELECT id FROM projects LIMIT 1", [], |row| row.get(0))
+            .query_row("SELECT id FROM projects ORDER BY id LIMIT 1", [], |row| {
+                row.get(0)
+            })
             .unwrap();
 
         enqueue_job(&conn, project_id, "issue", 42, 100, "resource_events", None).unwrap();
 
         let job_id: i64 = conn
             .query_row(
-                "SELECT id FROM pending_dependent_fetches LIMIT 1",
+                "SELECT id FROM pending_dependent_fetches ORDER BY id LIMIT 1",
                 [],
                 |row| row.get(0),
             )
@@ -301,7 +303,9 @@ mod tests {
         let (conn, _job_id) = setup_db_with_job();
 
         let project_id: i64 = conn
-            .query_row("SELECT id FROM projects LIMIT 1", [], |row| row.get(0))
+            .query_row("SELECT id FROM projects ORDER BY id LIMIT 1", [], |row| {
+                row.get(0)
+            })
             .unwrap();
         let jobs = claim_jobs(&conn, "resource_events", project_id, 10).unwrap();
         assert_eq!(jobs.len(), 1);

src/main.rs

@@ -13,23 +13,24 @@ use lore::cli::autocorrect::{self, CorrectionResult};
 use lore::cli::commands::{
     IngestDisplay, InitInputs, InitOptions, InitResult, ListFilters, MrListFilters,
     NoteListFilters, RefreshOptions, RefreshResult, SearchCliFilters, SyncOptions, TimelineParams,
-    delete_orphan_projects, open_issue_in_browser, 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_init_refresh, 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,
+    delete_orphan_projects, handle_explain, open_issue_in_browser, 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_init_refresh, 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};
@@ -222,6 +223,25 @@ fn main() {
         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::Explain {
+            entity_type,
+            iid,
+            project,
+            sections,
+            no_timeline,
+            max_decisions,
+            since,
+        }) => handle_explain(
+            cli.config.as_deref(),
+            &entity_type,
+            iid,
+            project.as_deref(),
+            sections,
+            no_timeline,
+            max_decisions,
+            since.as_deref(),
+            robot_mode,
+        ),
         Some(Commands::Drift {
             entity_type,
             iid,
@@ -365,33 +385,6 @@ fn main() {
             )
             .await
         }
-        Some(Commands::Show {
-            entity,
-            iid,
-            project,
-        }) => {
-            if robot_mode {
-                eprintln!(
-                    r#"{{"warning":{{"type":"DEPRECATED","message":"'lore show' is deprecated, use 'lore {entity}s {iid}'","successor":"{entity}s"}}}}"#
-                );
-            } else {
-                eprintln!(
-                    "{}",
-                    Theme::warning().render(&format!(
-                        "warning: 'lore show' is deprecated, use 'lore {}s {}'",
-                        entity, iid
-                    ))
-                );
-            }
-            handle_show_compat(
-                cli.config.as_deref(),
-                &entity,
-                iid,
-                project.as_deref(),
-                robot_mode,
-            )
-            .await
-        }
         Some(Commands::AuthTest) => {
             if robot_mode {
                 eprintln!(

src/search/fts.rs

@@ -119,15 +119,12 @@ pub fn search_fts(
 }
 
 pub fn generate_fallback_snippet(content_text: &str, max_chars: usize) -> String {
-    if content_text.chars().count() <= max_chars {
-        return content_text.to_string();
-    }
-
-    let byte_end = content_text
-        .char_indices()
-        .nth(max_chars)
-        .map(|(i, _)| i)
-        .unwrap_or(content_text.len());
+    // Use char_indices to find the boundary at max_chars in a single pass,
+    // short-circuiting early for large strings instead of counting all chars.
+    let byte_end = match content_text.char_indices().nth(max_chars) {
+        Some((i, _)) => i,
+        None => return content_text.to_string(), // content fits within max_chars
+    };
     let truncated = &content_text[..byte_end];
 
     if let Some(last_space) = truncated.rfind(' ') {

src/timeline/seed.rs

@@ -411,7 +411,9 @@ fn round_robin_select_by_discussion(
         let mut made_progress = false;
 
         for (disc_idx, &discussion_id) in discussion_order.iter().enumerate() {
-            let notes = by_discussion.get(&discussion_id).unwrap();
+            let notes = by_discussion
+                .get(&discussion_id)
+                .expect("key present: inserted into by_discussion via discussion_order");
             let note_idx = indices[disc_idx];
 
             if note_idx < notes.len() {