diff --git a/src/cli/commands/auth_test.rs b/src/cli/commands/auth_test.rs
index 5562875..751e357 100644
--- a/src/cli/commands/auth_test.rs
+++ b/src/cli/commands/auth_test.rs
@@ -1,22 +1,16 @@
-//! Auth test command - verify GitLab authentication.
-
 use crate::core::config::Config;
 use crate::core::error::{LoreError, Result};
 use crate::gitlab::GitLabClient;
 
-/// Result of successful auth test.
 pub struct AuthTestResult {
     pub username: String,
     pub name: String,
     pub base_url: String,
 }
 
-/// Run the auth-test command.
 pub async fn run_auth_test(config_path: Option<&str>) -> Result<AuthTestResult> {
-    // 1. Load config
     let config = Config::load(config_path)?;
 
-    // 2. Get token from environment
     let token = std::env::var(&config.gitlab.token_env_var)
         .map(|t| t.trim().to_string())
         .map_err(|_| LoreError::TokenNotSet {
@@ -29,10 +23,8 @@ pub async fn run_auth_test(config_path: Option<&str>) -> Result<AuthTestResult>
         });
     }
 
-    // 3. Create client and test auth
     let client = GitLabClient::new(&config.gitlab.base_url, &token, None);
 
-    // 4. Get current user
     let user = client.get_current_user().await?;
 
     Ok(AuthTestResult {
diff --git a/src/cli/commands/count.rs b/src/cli/commands/count.rs
index 751d91e..668afcb 100644
--- a/src/cli/commands/count.rs
+++ b/src/cli/commands/count.rs
@@ -1,5 +1,3 @@
-//! Count command - display entity counts from local database.
-
 use console::style;
 use rusqlite::Connection;
 use serde::Serialize;
@@ -10,23 +8,20 @@ use crate::core::error::Result;
 use crate::core::events_db::{self, EventCounts};
 use crate::core::paths::get_db_path;
 
-/// Result of count query.
 pub struct CountResult {
     pub entity: String,
     pub count: i64,
-    pub system_count: Option<i64>,               // For notes only
-    pub state_breakdown: Option<StateBreakdown>, // For issues/MRs
+    pub system_count: Option<i64>,
+    pub state_breakdown: Option<StateBreakdown>,
 }
 
-/// State breakdown for issues or MRs.
 pub struct StateBreakdown {
     pub opened: i64,
     pub closed: i64,
-    pub merged: Option<i64>, // MRs only
-    pub locked: Option<i64>, // MRs only
+    pub merged: Option<i64>,
+    pub locked: Option<i64>,
 }
 
-/// Run the count command.
 pub fn run_count(config: &Config, entity: &str, type_filter: Option<&str>) -> Result<CountResult> {
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
@@ -45,7 +40,6 @@ pub fn run_count(config: &Config, entity: &str, type_filter: Option<&str>) -> Re
     }
 }
 
-/// Count issues with state breakdown.
 fn count_issues(conn: &Connection) -> Result<CountResult> {
     let count: i64 = conn.query_row("SELECT COUNT(*) FROM issues", [], |row| row.get(0))?;
 
@@ -74,7 +68,6 @@ fn count_issues(conn: &Connection) -> Result<CountResult> {
     })
 }
 
-/// Count merge requests with state breakdown.
 fn count_mrs(conn: &Connection) -> Result<CountResult> {
     let count: i64 = conn.query_row("SELECT COUNT(*) FROM merge_requests", [], |row| row.get(0))?;
 
@@ -115,7 +108,6 @@ fn count_mrs(conn: &Connection) -> Result<CountResult> {
     })
 }
 
-/// Count discussions with optional noteable type filter.
 fn count_discussions(conn: &Connection, type_filter: Option<&str>) -> Result<CountResult> {
     let (count, entity_name) = match type_filter {
         Some("issue") => {
@@ -149,7 +141,6 @@ fn count_discussions(conn: &Connection, type_filter: Option<&str>) -> Result<Cou
     })
 }
 
-/// Count notes with optional noteable type filter.
 fn count_notes(conn: &Connection, type_filter: Option<&str>) -> Result<CountResult> {
     let (total, system_count, entity_name) = match type_filter {
         Some("issue") => {
@@ -184,7 +175,6 @@ fn count_notes(conn: &Connection, type_filter: Option<&str>) -> Result<CountResu
         }
     };
 
-    // Non-system notes count
     let non_system = total - system_count;
 
     Ok(CountResult {
@@ -195,7 +185,6 @@ fn count_notes(conn: &Connection, type_filter: Option<&str>) -> Result<CountResu
     })
 }
 
-/// Format number with thousands separators.
 fn format_number(n: i64) -> String {
     let s = n.to_string();
     let chars: Vec<char> = s.chars().collect();
@@ -211,7 +200,6 @@ fn format_number(n: i64) -> String {
     result
 }
 
-/// JSON output structure for count command.
 #[derive(Serialize)]
 struct CountJsonOutput {
     ok: bool,
@@ -238,14 +226,12 @@ struct CountJsonBreakdown {
     locked: Option<i64>,
 }
 
-/// Run the event count query.
 pub fn run_count_events(config: &Config) -> Result<EventCounts> {
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
     events_db::count_events(&conn)
 }
 
-/// JSON output structure for event counts.
 #[derive(Serialize)]
 struct EventCountJsonOutput {
     ok: bool,
@@ -267,7 +253,6 @@ struct EventTypeCounts {
     total: usize,
 }
 
-/// Print event counts as JSON (robot mode).
 pub fn print_event_count_json(counts: &EventCounts) {
     let output = EventCountJsonOutput {
         ok: true,
@@ -294,7 +279,6 @@ pub fn print_event_count_json(counts: &EventCounts) {
     println!("{}", serde_json::to_string(&output).unwrap());
 }
 
-/// Print event counts (human-readable).
 pub fn print_event_count(counts: &EventCounts) {
     println!(
         "{:<20} {:>8} {:>8} {:>8}",
@@ -341,7 +325,6 @@ pub fn print_event_count(counts: &EventCounts) {
     );
 }
 
-/// Print count result as JSON (robot mode).
 pub fn print_count_json(result: &CountResult) {
     let breakdown = result.state_breakdown.as_ref().map(|b| CountJsonBreakdown {
         opened: b.opened,
@@ -363,7 +346,6 @@ pub fn print_count_json(result: &CountResult) {
     println!("{}", serde_json::to_string(&output).unwrap());
 }
 
-/// Print count result.
 pub fn print_count(result: &CountResult) {
     let count_str = format_number(result.count);
 
@@ -386,7 +368,6 @@ pub fn print_count(result: &CountResult) {
         );
     }
 
-    // Print state breakdown if available
     if let Some(breakdown) = &result.state_breakdown {
         println!("  opened: {}", format_number(breakdown.opened));
         if let Some(merged) = breakdown.merged {
diff --git a/src/cli/commands/doctor.rs b/src/cli/commands/doctor.rs
index 6b7e96c..a356a67 100644
--- a/src/cli/commands/doctor.rs
+++ b/src/cli/commands/doctor.rs
@@ -1,5 +1,3 @@
-//! Doctor command - check environment health.
-
 use console::style;
 use serde::Serialize;
 
@@ -100,30 +98,22 @@ pub struct LoggingCheck {
     pub total_bytes: Option<u64>,
 }
 
-/// Run the doctor command.
 pub async fn run_doctor(config_path: Option<&str>) -> DoctorResult {
     let config_path_buf = get_config_path(config_path);
     let config_path_str = config_path_buf.display().to_string();
 
-    // Check config
     let (config_check, config) = check_config(&config_path_str);
 
-    // Check database
     let database_check = check_database(config.as_ref());
 
-    // Check GitLab
     let gitlab_check = check_gitlab(config.as_ref()).await;
 
-    // Check projects
     let projects_check = check_projects(config.as_ref());
 
-    // Check Ollama
     let ollama_check = check_ollama(config.as_ref()).await;
 
-    // Check logging
     let logging_check = check_logging(config.as_ref());
 
-    // Success if all required checks pass (ollama and logging are optional)
     let success = config_check.result.status == CheckStatus::Ok
         && database_check.result.status == CheckStatus::Ok
         && gitlab_check.result.status == CheckStatus::Ok
@@ -393,7 +383,6 @@ async fn check_ollama(config: Option<&Config>) -> OllamaCheck {
     let base_url = &config.embedding.base_url;
     let model = &config.embedding.model;
 
-    // Short timeout for Ollama check
     let client = reqwest::Client::builder()
         .timeout(std::time::Duration::from_secs(2))
         .build()
@@ -418,9 +407,6 @@ async fn check_ollama(config: Option<&Config>) -> OllamaCheck {
                         .map(|m| m.name.split(':').next().unwrap_or(&m.name))
                         .collect();
 
-                    // Strip tag from configured model name too (e.g.
-                    // "nomic-embed-text:v1.5" → "nomic-embed-text") so both
-                    // sides are compared at the same granularity.
                     let model_base = model.split(':').next().unwrap_or(model);
                     if !model_names.contains(&model_base) {
                         return OllamaCheck {
@@ -531,7 +517,6 @@ fn check_logging(config: Option<&Config>) -> LoggingCheck {
     }
 }
 
-/// Format and print doctor results to console.
 pub fn print_doctor_results(result: &DoctorResult) {
     println!("\nlore doctor\n");
 
diff --git a/src/cli/commands/embed.rs b/src/cli/commands/embed.rs
index e46f88f..9f043e4 100644
--- a/src/cli/commands/embed.rs
+++ b/src/cli/commands/embed.rs
@@ -1,5 +1,3 @@
-//! Embed command: generate vector embeddings for documents via Ollama.
-
 use console::style;
 use serde::Serialize;
 
@@ -10,7 +8,6 @@ use crate::core::paths::get_db_path;
 use crate::embedding::ollama::{OllamaClient, OllamaConfig};
 use crate::embedding::pipeline::embed_documents;
 
-/// Result of the embed command.
 #[derive(Debug, Default, Serialize)]
 pub struct EmbedCommandResult {
     pub embedded: usize,
@@ -18,9 +15,6 @@ pub struct EmbedCommandResult {
     pub skipped: usize,
 }
 
-/// Run the embed command.
-///
-/// `progress_callback` reports `(processed, total)` as documents are embedded.
 pub async fn run_embed(
     config: &Config,
     full: bool,
@@ -30,7 +24,6 @@ pub async fn run_embed(
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
 
-    // Build Ollama config from user settings
     let ollama_config = OllamaConfig {
         base_url: config.embedding.base_url.clone(),
         model: config.embedding.model.clone(),
@@ -38,13 +31,9 @@ pub async fn run_embed(
     };
     let client = OllamaClient::new(ollama_config);
 
-    // Health check — fail fast if Ollama is down or model missing
     client.health_check().await?;
 
     if full {
-        // Clear ALL embeddings and metadata atomically for a complete re-embed.
-        // Wrapped in a transaction so a crash between the two DELETEs can't
-        // leave orphaned data.
         conn.execute_batch(
             "BEGIN;
              DELETE FROM embedding_metadata;
@@ -52,7 +41,6 @@ pub async fn run_embed(
              COMMIT;",
         )?;
     } else if retry_failed {
-        // Clear errors so they become pending again
         conn.execute(
             "UPDATE embedding_metadata SET last_error = NULL, attempt_count = 0
              WHERE last_error IS NOT NULL",
@@ -70,7 +58,6 @@ pub async fn run_embed(
     })
 }
 
-/// Print human-readable output.
 pub fn print_embed(result: &EmbedCommandResult) {
     println!("{} Embedding complete", style("done").green().bold(),);
     println!("  Embedded: {}", result.embedded);
@@ -82,14 +69,12 @@ pub fn print_embed(result: &EmbedCommandResult) {
     }
 }
 
-/// JSON output.
 #[derive(Serialize)]
 struct EmbedJsonOutput<'a> {
     ok: bool,
     data: &'a EmbedCommandResult,
 }
 
-/// Print JSON robot-mode output.
 pub fn print_embed_json(result: &EmbedCommandResult) {
     let output = EmbedJsonOutput {
         ok: true,
diff --git a/src/cli/commands/generate_docs.rs b/src/cli/commands/generate_docs.rs
index 64476f6..0132b5f 100644
--- a/src/cli/commands/generate_docs.rs
+++ b/src/cli/commands/generate_docs.rs
@@ -1,5 +1,3 @@
-//! Generate searchable documents from ingested GitLab data.
-
 use console::style;
 use rusqlite::Connection;
 use serde::Serialize;
@@ -14,7 +12,6 @@ use crate::documents::{SourceType, regenerate_dirty_documents};
 
 const FULL_MODE_CHUNK_SIZE: i64 = 2000;
 
-/// Result of a generate-docs run.
 #[derive(Debug, Default)]
 pub struct GenerateDocsResult {
     pub regenerated: usize,
@@ -24,12 +21,6 @@ pub struct GenerateDocsResult {
     pub full_mode: bool,
 }
 
-/// Run the generate-docs pipeline.
-///
-/// Default mode: process only existing dirty_sources entries.
-/// Full mode: seed dirty_sources with ALL entities, then drain.
-///
-/// `progress_callback` reports `(processed, estimated_total)` as documents are generated.
 pub fn run_generate_docs(
     config: &Config,
     full: bool,
@@ -56,7 +47,6 @@ pub fn run_generate_docs(
     result.errored = regen.errored;
 
     if full {
-        // Optimize FTS index after bulk rebuild
         let _ = conn.execute(
             "INSERT INTO documents_fts(documents_fts) VALUES('optimize')",
             [],
@@ -67,7 +57,6 @@ pub fn run_generate_docs(
     Ok(result)
 }
 
-/// Seed dirty_sources with all entities of the given type using keyset pagination.
 fn seed_dirty(
     conn: &Connection,
     source_type: SourceType,
@@ -113,7 +102,6 @@ fn seed_dirty(
             break;
         }
 
-        // Advance keyset cursor to the max id within the chunk window
         let max_id: i64 = conn.query_row(
             &format!(
                 "SELECT MAX(id) FROM (SELECT id FROM {table} WHERE id > ?1 ORDER BY id LIMIT ?2)",
@@ -136,7 +124,6 @@ fn seed_dirty(
     Ok(total_seeded)
 }
 
-/// Print human-readable output.
 pub fn print_generate_docs(result: &GenerateDocsResult) {
     let mode = if result.full_mode {
         "full"
@@ -159,7 +146,6 @@ pub fn print_generate_docs(result: &GenerateDocsResult) {
     }
 }
 
-/// JSON output structures.
 #[derive(Serialize)]
 struct GenerateDocsJsonOutput {
     ok: bool,
@@ -176,7 +162,6 @@ struct GenerateDocsJsonData {
     errored: usize,
 }
 
-/// Print JSON robot-mode output.
 pub fn print_generate_docs_json(result: &GenerateDocsResult) {
     let output = GenerateDocsJsonOutput {
         ok: true,
diff --git a/src/cli/commands/ingest.rs b/src/cli/commands/ingest.rs
index 4108e33..1fcd11b 100644
--- a/src/cli/commands/ingest.rs
+++ b/src/cli/commands/ingest.rs
@@ -1,5 +1,3 @@
-//! Ingest command - fetch data from GitLab.
-
 use std::sync::Arc;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
@@ -22,17 +20,14 @@ use crate::ingestion::{
     ingest_project_merge_requests_with_progress,
 };
 
-/// Result of ingest command for display.
 #[derive(Default)]
 pub struct IngestResult {
     pub resource_type: String,
     pub projects_synced: usize,
-    // Issue-specific fields
     pub issues_fetched: usize,
     pub issues_upserted: usize,
     pub issues_synced_discussions: usize,
     pub issues_skipped_discussion_sync: usize,
-    // MR-specific fields
     pub mrs_fetched: usize,
     pub mrs_upserted: usize,
     pub mrs_synced_discussions: usize,
@@ -40,17 +35,13 @@ pub struct IngestResult {
     pub assignees_linked: usize,
     pub reviewers_linked: usize,
     pub diffnotes_count: usize,
-    // Shared fields
     pub labels_created: usize,
     pub discussions_fetched: usize,
     pub notes_upserted: usize,
-    // Resource events
     pub resource_events_fetched: usize,
     pub resource_events_failed: usize,
 }
 
-/// Outcome of ingesting a single project, used to aggregate results
-/// from concurrent project processing.
 enum ProjectIngestOutcome {
     Issues {
         path: String,
@@ -62,24 +53,14 @@ enum ProjectIngestOutcome {
     },
 }
 
-/// Controls what interactive UI elements `run_ingest` displays.
-///
-/// Separates progress indicators (spinners, bars) from text output (headers,
-/// per-project summaries) so callers like `sync` can show progress without
-/// duplicating summary text.
 #[derive(Debug, Clone, Copy)]
 pub struct IngestDisplay {
-    /// Show animated spinners and progress bars.
     pub show_progress: bool,
-    /// Show the per-project spinner. When called from `sync`, the stage
-    /// spinner already covers this, so a second spinner causes flashing.
     pub show_spinner: bool,
-    /// Show text headers ("Ingesting...") and per-project summary lines.
     pub show_text: bool,
 }
 
 impl IngestDisplay {
-    /// Interactive mode: everything visible.
     pub fn interactive() -> Self {
         Self {
             show_progress: true,
@@ -88,7 +69,6 @@ impl IngestDisplay {
         }
     }
 
-    /// Robot/JSON mode: everything hidden.
     pub fn silent() -> Self {
         Self {
             show_progress: false,
@@ -97,8 +77,6 @@ impl IngestDisplay {
         }
     }
 
-    /// Progress bars only, no spinner or text (used by sync which provides its
-    /// own stage spinner).
     pub fn progress_only() -> Self {
         Self {
             show_progress: true,
@@ -108,10 +86,6 @@ impl IngestDisplay {
     }
 }
 
-/// Run the ingest command.
-///
-/// `stage_bar` is an optional `ProgressBar` (typically from sync's stage spinner)
-/// that will be updated with aggregate progress across all projects.
 pub async fn run_ingest(
     config: &Config,
     resource_type: &str,
@@ -138,7 +112,6 @@ pub async fn run_ingest(
     .await
 }
 
-/// Inner implementation of run_ingest, instrumented with a root span.
 async fn run_ingest_inner(
     config: &Config,
     resource_type: &str,
@@ -148,7 +121,6 @@ async fn run_ingest_inner(
     display: IngestDisplay,
     stage_bar: Option<ProgressBar>,
 ) -> Result<IngestResult> {
-    // Validate resource type early
     if resource_type != "issues" && resource_type != "mrs" {
         return Err(LoreError::Other(format!(
             "Invalid resource type '{}'. Valid types: issues, mrs",
@@ -156,11 +128,9 @@ async fn run_ingest_inner(
         )));
     }
 
-    // Get database path and create connection
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
 
-    // Acquire single-flight lock
     let lock_conn = create_connection(&db_path)?;
     let mut lock = AppLock::new(
         lock_conn,
@@ -172,23 +142,19 @@ async fn run_ingest_inner(
     );
     lock.acquire(force)?;
 
-    // Get token from environment
     let token =
         std::env::var(&config.gitlab.token_env_var).map_err(|_| LoreError::TokenNotSet {
             env_var: config.gitlab.token_env_var.clone(),
         })?;
 
-    // Create GitLab client
     let client = GitLabClient::new(
         &config.gitlab.base_url,
         &token,
         Some(config.sync.requests_per_second),
     );
 
-    // Get projects to sync
     let projects = get_projects_to_sync(&conn, &config.projects, project_filter)?;
 
-    // If --full flag is set, reset sync cursors and discussion watermarks for a complete re-fetch
     if full {
         if display.show_text {
             println!(
@@ -198,20 +164,17 @@ async fn run_ingest_inner(
         }
         for (local_project_id, _, path) in &projects {
             if resource_type == "issues" {
-                // Reset issue discussion and resource event watermarks so everything gets re-synced
                 conn.execute(
                     "UPDATE issues SET discussions_synced_for_updated_at = NULL, resource_events_synced_for_updated_at = NULL WHERE project_id = ?",
                     [*local_project_id],
                 )?;
             } else if resource_type == "mrs" {
-                // Reset MR discussion and resource event watermarks
                 conn.execute(
                     "UPDATE merge_requests SET discussions_synced_for_updated_at = NULL, resource_events_synced_for_updated_at = NULL WHERE project_id = ?",
                     [*local_project_id],
                 )?;
             }
 
-            // Then reset sync cursor
             conn.execute(
                 "DELETE FROM sync_cursors WHERE project_id = ? AND resource_type = ?",
                 (*local_project_id, resource_type),
@@ -248,12 +211,9 @@ async fn run_ingest_inner(
         println!();
     }
 
-    // Process projects concurrently. Each project gets its own DB connection
-    // while sharing the rate limiter through the cloned GitLabClient.
     let concurrency = config.sync.primary_concurrency as usize;
     let resource_type_owned = resource_type.to_string();
 
-    // Aggregate counters for stage_bar updates (shared across concurrent projects)
     let agg_fetched = Arc::new(AtomicUsize::new(0));
     let agg_discussions = Arc::new(AtomicUsize::new(0));
     let agg_disc_total = Arc::new(AtomicUsize::new(0));
@@ -328,7 +288,6 @@ async fn run_ingest_inner(
                 } else {
                     Box::new(move |event: ProgressEvent| match event {
                         ProgressEvent::IssuesFetchStarted | ProgressEvent::MrsFetchStarted => {
-                            // Spinner already showing fetch message
                         }
                         ProgressEvent::IssuesFetchComplete { total } | ProgressEvent::MrsFetchComplete { total } => {
                             let agg = agg_fetched_clone.fetch_add(total, Ordering::Relaxed) + total;
@@ -410,6 +369,20 @@ async fn run_ingest_inner(
                         ProgressEvent::ResourceEventsFetchComplete { .. } => {
                             disc_bar_clone.finish_and_clear();
                         }
+                        ProgressEvent::ClosesIssuesFetchStarted { total } => {
+                            disc_bar_clone.reset();
+                            disc_bar_clone.set_length(total as u64);
+                            disc_bar_clone.enable_steady_tick(std::time::Duration::from_millis(100));
+                            stage_bar_clone.set_message(
+                                "Fetching closes-issues references...".to_string()
+                            );
+                        }
+                        ProgressEvent::ClosesIssueFetched { current, total: _ } => {
+                            disc_bar_clone.set_position(current as u64);
+                        }
+                        ProgressEvent::ClosesIssuesFetchComplete { .. } => {
+                            disc_bar_clone.finish_and_clear();
+                        }
                     })
                 };
 
@@ -453,9 +426,6 @@ async fn run_ingest_inner(
         .collect()
         .await;
 
-    // Aggregate results and print per-project summaries.
-    // Process all successes first, then return the first error (if any)
-    // so that successful project summaries are always printed.
     let mut first_error: Option<LoreError> = None;
     for project_result in project_results {
         match project_result {
@@ -510,21 +480,17 @@ async fn run_ingest_inner(
         return Err(e);
     }
 
-    // Lock is released on drop
     Ok(total)
 }
 
-/// Get projects to sync from database, optionally filtered.
 fn get_projects_to_sync(
     conn: &Connection,
     configured_projects: &[crate::core::config::ProjectConfig],
     filter: Option<&str>,
 ) -> Result<Vec<(i64, i64, String)>> {
-    // If a filter is provided, resolve it to a specific project
     if let Some(filter_str) = filter {
         let project_id = resolve_project(conn, filter_str)?;
 
-        // Verify the resolved project is in our config
         let row: Option<(i64, String)> = conn
             .query_row(
                 "SELECT gitlab_project_id, path_with_namespace FROM projects WHERE id = ?1",
@@ -534,7 +500,6 @@ fn get_projects_to_sync(
             .ok();
 
         if let Some((gitlab_id, path)) = row {
-            // Confirm it's a configured project
             if configured_projects.iter().any(|p| p.path == path) {
                 return Ok(vec![(project_id, gitlab_id, path)]);
             }
@@ -550,7 +515,6 @@ fn get_projects_to_sync(
         )));
     }
 
-    // No filter: return all configured projects
     let mut projects = Vec::new();
     for project_config in configured_projects {
         let result: Option<(i64, i64)> = conn
@@ -569,7 +533,6 @@ fn get_projects_to_sync(
     Ok(projects)
 }
 
-/// Print summary for a single project (issues).
 fn print_issue_project_summary(path: &str, result: &IngestProjectResult) {
     let labels_str = if result.labels_created > 0 {
         format!(", {} new labels", result.labels_created)
@@ -599,7 +562,6 @@ fn print_issue_project_summary(path: &str, result: &IngestProjectResult) {
     }
 }
 
-/// Print summary for a single project (merge requests).
 fn print_mr_project_summary(path: &str, result: &IngestMrProjectResult) {
     let labels_str = if result.labels_created > 0 {
         format!(", {} new labels", result.labels_created)
@@ -647,7 +609,6 @@ fn print_mr_project_summary(path: &str, result: &IngestMrProjectResult) {
     }
 }
 
-/// JSON output structures for robot mode.
 #[derive(Serialize)]
 struct IngestJsonOutput {
     ok: bool,
@@ -688,7 +649,6 @@ struct IngestMrStats {
     diffnotes_count: usize,
 }
 
-/// Print final summary as JSON (robot mode).
 pub fn print_ingest_summary_json(result: &IngestResult) {
     let (issues, merge_requests) = if result.resource_type == "issues" {
         (
@@ -733,7 +693,6 @@ pub fn print_ingest_summary_json(result: &IngestResult) {
     println!("{}", serde_json::to_string(&output).unwrap());
 }
 
-/// Print final summary.
 pub fn print_ingest_summary(result: &IngestResult) {
     println!();
 
diff --git a/src/cli/commands/init.rs b/src/cli/commands/init.rs
index 3dfaaba..5c5a2d0 100644
--- a/src/cli/commands/init.rs
+++ b/src/cli/commands/init.rs
@@ -1,5 +1,3 @@
-//! Init command - initialize configuration and database.
-
 use std::fs;
 
 use crate::core::config::{MinimalConfig, MinimalGitLabConfig, ProjectConfig};
@@ -8,21 +6,18 @@ use crate::core::error::{LoreError, Result};
 use crate::core::paths::{get_config_path, get_data_dir};
 use crate::gitlab::{GitLabClient, GitLabProject};
 
-/// Input data for init command.
 pub struct InitInputs {
     pub gitlab_url: String,
     pub token_env_var: String,
     pub project_paths: Vec<String>,
 }
 
-/// Options for init command.
 pub struct InitOptions {
     pub config_path: Option<String>,
     pub force: bool,
     pub non_interactive: bool,
 }
 
-/// Result of successful init.
 pub struct InitResult {
     pub config_path: String,
     pub data_dir: String,
@@ -40,12 +35,10 @@ pub struct ProjectInfo {
     pub name: String,
 }
 
-/// Run the init command programmatically.
 pub async fn run_init(inputs: InitInputs, options: InitOptions) -> Result<InitResult> {
     let config_path = get_config_path(options.config_path.as_deref());
     let data_dir = get_data_dir();
 
-    // 1. Check if config exists (force takes precedence over non_interactive)
     if config_path.exists() && !options.force {
         if options.non_interactive {
             return Err(LoreError::Other(format!(
@@ -59,7 +52,6 @@ pub async fn run_init(inputs: InitInputs, options: InitOptions) -> Result<InitRe
         ));
     }
 
-    // 2. Validate GitLab URL format
     if url::Url::parse(&inputs.gitlab_url).is_err() {
         return Err(LoreError::Other(format!(
             "Invalid GitLab URL: {}",
@@ -67,12 +59,10 @@ pub async fn run_init(inputs: InitInputs, options: InitOptions) -> Result<InitRe
         )));
     }
 
-    // 3. Check token is set in environment
     let token = std::env::var(&inputs.token_env_var).map_err(|_| LoreError::TokenNotSet {
         env_var: inputs.token_env_var.clone(),
     })?;
 
-    // 4. Create GitLab client and test authentication
     let client = GitLabClient::new(&inputs.gitlab_url, &token, None);
 
     let gitlab_user = client.get_current_user().await.map_err(|e| {
@@ -88,7 +78,6 @@ pub async fn run_init(inputs: InitInputs, options: InitOptions) -> Result<InitRe
         name: gitlab_user.name,
     };
 
-    // 5. Validate each project path
     let mut validated_projects: Vec<(ProjectInfo, GitLabProject)> = Vec::new();
 
     for project_path in &inputs.project_paths {
@@ -115,14 +104,10 @@ pub async fn run_init(inputs: InitInputs, options: InitOptions) -> Result<InitRe
         ));
     }
 
-    // 6. All validations passed - now write config and setup DB
-
-    // Create config directory if needed
     if let Some(parent) = config_path.parent() {
         fs::create_dir_all(parent)?;
     }
 
-    // Write minimal config (rely on serde defaults)
     let config = MinimalConfig {
         gitlab: MinimalGitLabConfig {
             base_url: inputs.gitlab_url,
@@ -138,16 +123,13 @@ pub async fn run_init(inputs: InitInputs, options: InitOptions) -> Result<InitRe
     let config_json = serde_json::to_string_pretty(&config)?;
     fs::write(&config_path, format!("{config_json}\n"))?;
 
-    // 7. Create data directory and initialize database
     fs::create_dir_all(&data_dir)?;
 
     let db_path = data_dir.join("lore.db");
     let conn = create_connection(&db_path)?;
 
-    // Run embedded migrations
     run_migrations(&conn)?;
 
-    // 8. Insert validated projects
     for (_, gitlab_project) in &validated_projects {
         conn.execute(
             "INSERT INTO projects (gitlab_project_id, path_with_namespace, default_branch, web_url)
diff --git a/src/cli/commands/list.rs b/src/cli/commands/list.rs
index ff0ccb9..7312c9b 100644
--- a/src/cli/commands/list.rs
+++ b/src/cli/commands/list.rs
@@ -1,5 +1,3 @@
-//! List command - display issues/MRs from local database.
-
 use comfy_table::{Attribute, Cell, Color, ContentArrangement, Table};
 use rusqlite::Connection;
 use serde::Serialize;
@@ -11,7 +9,6 @@ use crate::core::paths::get_db_path;
 use crate::core::project::resolve_project;
 use crate::core::time::{ms_to_iso, now_ms, parse_since};
 
-/// Apply foreground color to a Cell only if colors are enabled.
 fn colored_cell(content: impl std::fmt::Display, color: Color) -> Cell {
     let cell = Cell::new(content);
     if console::colors_enabled() {
@@ -21,7 +18,6 @@ fn colored_cell(content: impl std::fmt::Display, color: Color) -> Cell {
     }
 }
 
-/// Issue row for display.
 #[derive(Debug, Serialize)]
 pub struct IssueListRow {
     pub iid: i64,
@@ -39,7 +35,6 @@ pub struct IssueListRow {
     pub unresolved_count: i64,
 }
 
-/// Serializable version for JSON output.
 #[derive(Serialize)]
 pub struct IssueListRowJson {
     pub iid: i64,
@@ -76,14 +71,12 @@ impl From<&IssueListRow> for IssueListRowJson {
     }
 }
 
-/// Result of list query.
 #[derive(Serialize)]
 pub struct ListResult {
     pub issues: Vec<IssueListRow>,
     pub total_count: usize,
 }
 
-/// JSON output structure.
 #[derive(Serialize)]
 pub struct ListResultJson {
     pub issues: Vec<IssueListRowJson>,
@@ -101,7 +94,6 @@ impl From<&ListResult> for ListResultJson {
     }
 }
 
-/// MR row for display.
 #[derive(Debug, Serialize)]
 pub struct MrListRow {
     pub iid: i64,
@@ -123,7 +115,6 @@ pub struct MrListRow {
     pub unresolved_count: i64,
 }
 
-/// Serializable version for JSON output.
 #[derive(Serialize)]
 pub struct MrListRowJson {
     pub iid: i64,
@@ -168,14 +159,12 @@ impl From<&MrListRow> for MrListRowJson {
     }
 }
 
-/// Result of MR list query.
 #[derive(Serialize)]
 pub struct MrListResult {
     pub mrs: Vec<MrListRow>,
     pub total_count: usize,
 }
 
-/// JSON output structure for MRs.
 #[derive(Serialize)]
 pub struct MrListResultJson {
     pub mrs: Vec<MrListRowJson>,
@@ -193,7 +182,6 @@ impl From<&MrListResult> for MrListResultJson {
     }
 }
 
-/// Filter options for issue list query.
 pub struct ListFilters<'a> {
     pub limit: usize,
     pub project: Option<&'a str>,
@@ -209,7 +197,6 @@ pub struct ListFilters<'a> {
     pub order: &'a str,
 }
 
-/// Filter options for MR list query.
 pub struct MrListFilters<'a> {
     pub limit: usize,
     pub project: Option<&'a str>,
@@ -227,7 +214,6 @@ pub struct MrListFilters<'a> {
     pub order: &'a str,
 }
 
-/// Run the list issues command.
 pub fn run_list_issues(config: &Config, filters: ListFilters) -> Result<ListResult> {
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
@@ -236,9 +222,7 @@ pub fn run_list_issues(config: &Config, filters: ListFilters) -> Result<ListResu
     Ok(result)
 }
 
-/// Query issues from database with enriched data.
 fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult> {
-    // Build WHERE clause
     let mut where_clauses = Vec::new();
     let mut params: Vec<Box<dyn rusqlite::ToSql>> = Vec::new();
 
@@ -255,14 +239,12 @@ fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult>
         params.push(Box::new(state.to_string()));
     }
 
-    // Handle author filter (strip leading @ if present)
     if let Some(author) = filters.author {
         let username = author.strip_prefix('@').unwrap_or(author);
         where_clauses.push("i.author_username = ?");
         params.push(Box::new(username.to_string()));
     }
 
-    // Handle assignee filter (strip leading @ if present)
     if let Some(assignee) = filters.assignee {
         let username = assignee.strip_prefix('@').unwrap_or(assignee);
         where_clauses.push(
@@ -272,7 +254,6 @@ fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult>
         params.push(Box::new(username.to_string()));
     }
 
-    // Handle since filter
     if let Some(since_str) = filters.since {
         let cutoff_ms = parse_since(since_str).ok_or_else(|| {
             LoreError::Other(format!(
@@ -284,7 +265,6 @@ fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult>
         params.push(Box::new(cutoff_ms));
     }
 
-    // Handle label filters (AND logic - all labels must be present)
     if let Some(labels) = filters.labels {
         for label in labels {
             where_clauses.push(
@@ -296,19 +276,16 @@ fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult>
         }
     }
 
-    // Handle milestone filter
     if let Some(milestone) = filters.milestone {
         where_clauses.push("i.milestone_title = ?");
         params.push(Box::new(milestone.to_string()));
     }
 
-    // Handle due_before filter
     if let Some(due_before) = filters.due_before {
         where_clauses.push("i.due_date IS NOT NULL AND i.due_date <= ?");
         params.push(Box::new(due_before.to_string()));
     }
 
-    // Handle has_due_date filter
     if filters.has_due_date {
         where_clauses.push("i.due_date IS NOT NULL");
     }
@@ -319,7 +296,6 @@ fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult>
         format!("WHERE {}", where_clauses.join(" AND "))
     };
 
-    // Get total count
     let count_sql = format!(
         "SELECT COUNT(*) FROM issues i
          JOIN projects p ON i.project_id = p.id
@@ -330,11 +306,10 @@ fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult>
     let total_count: i64 = conn.query_row(&count_sql, param_refs.as_slice(), |row| row.get(0))?;
     let total_count = total_count as usize;
 
-    // Build ORDER BY
     let sort_column = match filters.sort {
         "created" => "i.created_at",
         "iid" => "i.iid",
-        _ => "i.updated_at", // default
+        _ => "i.updated_at",
     };
     let order = if filters.order == "asc" {
         "ASC"
@@ -342,7 +317,6 @@ fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult>
         "DESC"
     };
 
-    // Get issues with enriched data
     let query_sql = format!(
         "SELECT
             i.iid,
@@ -416,7 +390,6 @@ fn query_issues(conn: &Connection, filters: &ListFilters) -> Result<ListResult>
     })
 }
 
-/// Run the list MRs command.
 pub fn run_list_mrs(config: &Config, filters: MrListFilters) -> Result<MrListResult> {
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
@@ -425,9 +398,7 @@ pub fn run_list_mrs(config: &Config, filters: MrListFilters) -> Result<MrListRes
     Ok(result)
 }
 
-/// Query MRs from database with enriched data.
 fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult> {
-    // Build WHERE clause
     let mut where_clauses = Vec::new();
     let mut params: Vec<Box<dyn rusqlite::ToSql>> = Vec::new();
 
@@ -444,14 +415,12 @@ fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult>
         params.push(Box::new(state.to_string()));
     }
 
-    // Handle author filter (strip leading @ if present)
     if let Some(author) = filters.author {
         let username = author.strip_prefix('@').unwrap_or(author);
         where_clauses.push("m.author_username = ?");
         params.push(Box::new(username.to_string()));
     }
 
-    // Handle assignee filter (strip leading @ if present)
     if let Some(assignee) = filters.assignee {
         let username = assignee.strip_prefix('@').unwrap_or(assignee);
         where_clauses.push(
@@ -461,7 +430,6 @@ fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult>
         params.push(Box::new(username.to_string()));
     }
 
-    // Handle reviewer filter (strip leading @ if present)
     if let Some(reviewer) = filters.reviewer {
         let username = reviewer.strip_prefix('@').unwrap_or(reviewer);
         where_clauses.push(
@@ -471,7 +439,6 @@ fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult>
         params.push(Box::new(username.to_string()));
     }
 
-    // Handle since filter
     if let Some(since_str) = filters.since {
         let cutoff_ms = parse_since(since_str).ok_or_else(|| {
             LoreError::Other(format!(
@@ -483,7 +450,6 @@ fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult>
         params.push(Box::new(cutoff_ms));
     }
 
-    // Handle label filters (AND logic - all labels must be present)
     if let Some(labels) = filters.labels {
         for label in labels {
             where_clauses.push(
@@ -495,20 +461,17 @@ fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult>
         }
     }
 
-    // Handle draft filter
     if filters.draft {
         where_clauses.push("m.draft = 1");
     } else if filters.no_draft {
         where_clauses.push("m.draft = 0");
     }
 
-    // Handle target branch filter
     if let Some(target_branch) = filters.target_branch {
         where_clauses.push("m.target_branch = ?");
         params.push(Box::new(target_branch.to_string()));
     }
 
-    // Handle source branch filter
     if let Some(source_branch) = filters.source_branch {
         where_clauses.push("m.source_branch = ?");
         params.push(Box::new(source_branch.to_string()));
@@ -520,7 +483,6 @@ fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult>
         format!("WHERE {}", where_clauses.join(" AND "))
     };
 
-    // Get total count
     let count_sql = format!(
         "SELECT COUNT(*) FROM merge_requests m
          JOIN projects p ON m.project_id = p.id
@@ -531,11 +493,10 @@ fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult>
     let total_count: i64 = conn.query_row(&count_sql, param_refs.as_slice(), |row| row.get(0))?;
     let total_count = total_count as usize;
 
-    // Build ORDER BY
     let sort_column = match filters.sort {
         "created" => "m.created_at",
         "iid" => "m.iid",
-        _ => "m.updated_at", // default
+        _ => "m.updated_at",
     };
     let order = if filters.order == "asc" {
         "ASC"
@@ -543,7 +504,6 @@ fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult>
         "DESC"
     };
 
-    // Get MRs with enriched data
     let query_sql = format!(
         "SELECT
             m.iid,
@@ -631,7 +591,6 @@ fn query_mrs(conn: &Connection, filters: &MrListFilters) -> Result<MrListResult>
     Ok(MrListResult { mrs, total_count })
 }
 
-/// Format relative time from ms epoch.
 fn format_relative_time(ms_epoch: i64) -> String {
     let now = now_ms();
     let diff = now - ms_epoch;
@@ -662,7 +621,6 @@ fn format_relative_time(ms_epoch: i64) -> String {
     }
 }
 
-/// Truncate string to max width with ellipsis.
 fn truncate_with_ellipsis(s: &str, max_width: usize) -> String {
     if s.chars().count() <= max_width {
         s.to_string()
@@ -672,7 +630,6 @@ fn truncate_with_ellipsis(s: &str, max_width: usize) -> String {
     }
 }
 
-/// Format labels for display: [bug, urgent +2]
 fn format_labels(labels: &[String], max_shown: usize) -> String {
     if labels.is_empty() {
         return String::new();
@@ -688,7 +645,6 @@ fn format_labels(labels: &[String], max_shown: usize) -> String {
     }
 }
 
-/// Format assignees for display: @user1, @user2 +1
 fn format_assignees(assignees: &[String]) -> String {
     if assignees.is_empty() {
         return "-".to_string();
@@ -709,7 +665,6 @@ fn format_assignees(assignees: &[String]) -> String {
     }
 }
 
-/// Format discussion count: "3/1!" (3 total, 1 unresolved)
 fn format_discussions(total: i64, unresolved: i64) -> String {
     if total == 0 {
         return String::new();
@@ -722,13 +677,11 @@ fn format_discussions(total: i64, unresolved: i64) -> String {
     }
 }
 
-/// Format branch info: target <- source
 fn format_branches(target: &str, source: &str, max_width: usize) -> String {
     let full = format!("{} <- {}", target, source);
     truncate_with_ellipsis(&full, max_width)
 }
 
-/// Print issues list as a formatted table.
 pub fn print_list_issues(result: &ListResult) {
     if result.issues.is_empty() {
         println!("No issues found.");
@@ -781,7 +734,6 @@ pub fn print_list_issues(result: &ListResult) {
     println!("{table}");
 }
 
-/// Print issues list as JSON.
 pub fn print_list_issues_json(result: &ListResult) {
     let json_result = ListResultJson::from(result);
     match serde_json::to_string_pretty(&json_result) {
@@ -790,7 +742,6 @@ pub fn print_list_issues_json(result: &ListResult) {
     }
 }
 
-/// Open issue in browser. Returns the URL that was opened.
 pub fn open_issue_in_browser(result: &ListResult) -> Option<String> {
     let first_issue = result.issues.first()?;
     let url = first_issue.web_url.as_ref()?;
@@ -807,7 +758,6 @@ pub fn open_issue_in_browser(result: &ListResult) -> Option<String> {
     }
 }
 
-/// Print MRs list as a formatted table.
 pub fn print_list_mrs(result: &MrListResult) {
     if result.mrs.is_empty() {
         println!("No merge requests found.");
@@ -869,7 +819,6 @@ pub fn print_list_mrs(result: &MrListResult) {
     println!("{table}");
 }
 
-/// Print MRs list as JSON.
 pub fn print_list_mrs_json(result: &MrListResult) {
     let json_result = MrListResultJson::from(result);
     match serde_json::to_string_pretty(&json_result) {
@@ -878,7 +827,6 @@ pub fn print_list_mrs_json(result: &MrListResult) {
     }
 }
 
-/// Open MR in browser. Returns the URL that was opened.
 pub fn open_mr_in_browser(result: &MrListResult) -> Option<String> {
     let first_mr = result.mrs.first()?;
     let url = first_mr.web_url.as_ref()?;
@@ -921,10 +869,10 @@ mod tests {
     fn relative_time_formats_correctly() {
         let now = now_ms();
 
-        assert_eq!(format_relative_time(now - 30_000), "just now"); // 30s ago
-        assert_eq!(format_relative_time(now - 120_000), "2 min ago"); // 2 min ago
-        assert_eq!(format_relative_time(now - 7_200_000), "2 hours ago"); // 2 hours ago
-        assert_eq!(format_relative_time(now - 172_800_000), "2 days ago"); // 2 days ago
+        assert_eq!(format_relative_time(now - 30_000), "just now");
+        assert_eq!(format_relative_time(now - 120_000), "2 min ago");
+        assert_eq!(format_relative_time(now - 7_200_000), "2 hours ago");
+        assert_eq!(format_relative_time(now - 172_800_000), "2 days ago");
     }
 
     #[test]
diff --git a/src/cli/commands/mod.rs b/src/cli/commands/mod.rs
index 8bb3735..bb0eb41 100644
--- a/src/cli/commands/mod.rs
+++ b/src/cli/commands/mod.rs
@@ -1,5 +1,3 @@
-//! CLI command implementations.
-
 pub mod auth_test;
 pub mod count;
 pub mod doctor;
diff --git a/src/cli/commands/search.rs b/src/cli/commands/search.rs
index 63004d5..3f62701 100644
--- a/src/cli/commands/search.rs
+++ b/src/cli/commands/search.rs
@@ -1,5 +1,3 @@
-//! Search command: lexical (FTS5) search with filter support and single-query hydration.
-
 use console::style;
 use serde::Serialize;
 
@@ -15,7 +13,6 @@ use crate::search::{
     search_fts,
 };
 
-/// Display-ready search result with all fields hydrated.
 #[derive(Debug, Serialize)]
 pub struct SearchResultDisplay {
     pub document_id: i64,
@@ -34,7 +31,6 @@ pub struct SearchResultDisplay {
     pub explain: Option<ExplainData>,
 }
 
-/// Ranking explanation for --explain output.
 #[derive(Debug, Serialize)]
 pub struct ExplainData {
     pub vector_rank: Option<usize>,
@@ -42,7 +38,6 @@ pub struct ExplainData {
     pub rrf_score: f64,
 }
 
-/// Search response wrapper.
 #[derive(Debug, Serialize)]
 pub struct SearchResponse {
     pub query: String,
@@ -52,7 +47,6 @@ pub struct SearchResponse {
     pub warnings: Vec<String>,
 }
 
-/// Build SearchFilters from CLI args.
 pub struct SearchCliFilters {
     pub source_type: Option<String>,
     pub author: Option<String>,
@@ -64,7 +58,6 @@ pub struct SearchCliFilters {
     pub limit: usize,
 }
 
-/// Run a lexical search query.
 pub fn run_search(
     config: &Config,
     query: &str,
@@ -75,7 +68,6 @@ pub fn run_search(
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
 
-    // Check if any documents exist
     let doc_count: i64 = conn
         .query_row("SELECT COUNT(*) FROM documents", [], |row| row.get(0))
         .unwrap_or(0);
@@ -90,7 +82,6 @@ pub fn run_search(
         });
     }
 
-    // Build filters
     let source_type = cli_filters
         .source_type
         .as_deref()
@@ -146,7 +137,6 @@ pub fn run_search(
         limit: cli_filters.limit,
     };
 
-    // Adaptive recall: wider initial fetch when filters applied
     let requested = filters.clamp_limit();
     let top_k = if filters.has_any_filter() {
         (requested * 50).clamp(200, 1500)
@@ -154,24 +144,20 @@ pub fn run_search(
         (requested * 10).clamp(50, 1500)
     };
 
-    // FTS search
     let fts_results = search_fts(&conn, query, top_k, fts_mode)?;
     let fts_tuples: Vec<(i64, f64)> = fts_results
         .iter()
         .map(|r| (r.document_id, r.bm25_score))
         .collect();
 
-    // Build snippet map before ranking
     let snippet_map: std::collections::HashMap<i64, String> = fts_results
         .iter()
         .map(|r| (r.document_id, r.snippet.clone()))
         .collect();
 
-    // RRF ranking (single-list for lexical mode)
     let ranked = rank_rrf(&[], &fts_tuples);
     let ranked_ids: Vec<i64> = ranked.iter().map(|r| r.document_id).collect();
 
-    // Apply post-retrieval filters
     let filtered_ids = apply_filters(&conn, &ranked_ids, &filters)?;
 
     if filtered_ids.is_empty() {
@@ -184,10 +170,8 @@ pub fn run_search(
         });
     }
 
-    // Hydrate results in single round-trip
     let hydrated = hydrate_results(&conn, &filtered_ids)?;
 
-    // Build display results preserving filter order
     let rrf_map: std::collections::HashMap<i64, &crate::search::RrfResult> =
         ranked.iter().map(|r| (r.document_id, r)).collect();
 
@@ -233,7 +217,6 @@ pub fn run_search(
     })
 }
 
-/// Raw row from hydration query.
 struct HydratedRow {
     document_id: i64,
     source_type: String,
@@ -248,10 +231,6 @@ struct HydratedRow {
     paths: Vec<String>,
 }
 
-/// Hydrate document IDs into full display rows in a single query.
-///
-/// Uses json_each() to pass ranked IDs and preserve ordering via ORDER BY j.key.
-/// Labels and paths fetched via correlated json_group_array subqueries.
 fn hydrate_results(conn: &rusqlite::Connection, document_ids: &[i64]) -> Result<Vec<HydratedRow>> {
     if document_ids.is_empty() {
         return Ok(Vec::new());
@@ -299,7 +278,6 @@ fn hydrate_results(conn: &rusqlite::Connection, document_ids: &[i64]) -> Result<
     Ok(rows)
 }
 
-/// Parse a JSON array string into a Vec<String>, filtering out null/empty.
 fn parse_json_array(json: &str) -> Vec<String> {
     serde_json::from_str::<Vec<serde_json::Value>>(json)
         .unwrap_or_default()
@@ -309,7 +287,6 @@ fn parse_json_array(json: &str) -> Vec<String> {
         .collect()
 }
 
-/// Print human-readable search results.
 pub fn print_search_results(response: &SearchResponse) {
     if !response.warnings.is_empty() {
         for w in &response.warnings {
@@ -364,7 +341,6 @@ pub fn print_search_results(response: &SearchResponse) {
             println!("    Labels: {}", result.labels.join(", "));
         }
 
-        // Strip HTML tags from snippet for terminal display
         let clean_snippet = result.snippet.replace("<mark>", "").replace("</mark>", "");
         println!("    {}", style(clean_snippet).dim());
 
@@ -384,7 +360,6 @@ pub fn print_search_results(response: &SearchResponse) {
     }
 }
 
-/// JSON output structures.
 #[derive(Serialize)]
 struct SearchJsonOutput<'a> {
     ok: bool,
@@ -397,7 +372,6 @@ struct SearchMeta {
     elapsed_ms: u64,
 }
 
-/// Print JSON robot-mode output.
 pub fn print_search_results_json(response: &SearchResponse, elapsed_ms: u64) {
     let output = SearchJsonOutput {
         ok: true,
diff --git a/src/cli/commands/show.rs b/src/cli/commands/show.rs
index 8855b95..28e23a4 100644
--- a/src/cli/commands/show.rs
+++ b/src/cli/commands/show.rs
@@ -1,5 +1,3 @@
-//! Show command - display detailed entity information from local database.
-
 use console::style;
 use rusqlite::Connection;
 use serde::Serialize;
@@ -11,7 +9,6 @@ use crate::core::paths::get_db_path;
 use crate::core::project::resolve_project;
 use crate::core::time::ms_to_iso;
 
-/// Merge request metadata for display.
 #[derive(Debug, Serialize)]
 pub struct MrDetail {
     pub id: i64,
@@ -35,14 +32,12 @@ pub struct MrDetail {
     pub discussions: Vec<MrDiscussionDetail>,
 }
 
-/// MR discussion detail for display.
 #[derive(Debug, Serialize)]
 pub struct MrDiscussionDetail {
     pub notes: Vec<MrNoteDetail>,
     pub individual_note: bool,
 }
 
-/// MR note detail for display (includes DiffNote position).
 #[derive(Debug, Serialize)]
 pub struct MrNoteDetail {
     pub author_username: String,
@@ -52,7 +47,6 @@ pub struct MrNoteDetail {
     pub position: Option<DiffNotePosition>,
 }
 
-/// DiffNote position context for display.
 #[derive(Debug, Clone, Serialize)]
 pub struct DiffNotePosition {
     pub old_path: Option<String>,
@@ -62,7 +56,6 @@ pub struct DiffNotePosition {
     pub position_type: Option<String>,
 }
 
-/// Issue metadata for display.
 #[derive(Debug, Serialize)]
 pub struct IssueDetail {
     pub id: i64,
@@ -79,14 +72,12 @@ pub struct IssueDetail {
     pub discussions: Vec<DiscussionDetail>,
 }
 
-/// Discussion detail for display.
 #[derive(Debug, Serialize)]
 pub struct DiscussionDetail {
     pub notes: Vec<NoteDetail>,
     pub individual_note: bool,
 }
 
-/// Note detail for display.
 #[derive(Debug, Serialize)]
 pub struct NoteDetail {
     pub author_username: String,
@@ -95,7 +86,6 @@ pub struct NoteDetail {
     pub is_system: bool,
 }
 
-/// Run the show issue command.
 pub fn run_show_issue(
     config: &Config,
     iid: i64,
@@ -104,13 +94,10 @@ pub fn run_show_issue(
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
 
-    // Find the issue
     let issue = find_issue(&conn, iid, project_filter)?;
 
-    // Load labels
     let labels = get_issue_labels(&conn, issue.id)?;
 
-    // Load discussions with notes
     let discussions = get_issue_discussions(&conn, issue.id)?;
 
     Ok(IssueDetail {
@@ -129,7 +116,6 @@ pub fn run_show_issue(
     })
 }
 
-/// Internal issue row from query.
 struct IssueRow {
     id: i64,
     iid: i64,
@@ -143,7 +129,6 @@ struct IssueRow {
     project_path: String,
 }
 
-/// Find issue by iid, optionally filtered by project.
 fn find_issue(conn: &Connection, iid: i64, project_filter: Option<&str>) -> Result<IssueRow> {
     let (sql, params): (&str, Vec<Box<dyn rusqlite::ToSql>>) = match project_filter {
         Some(project) => {
@@ -201,7 +186,6 @@ fn find_issue(conn: &Connection, iid: i64, project_filter: Option<&str>) -> Resu
     }
 }
 
-/// Get labels for an issue.
 fn get_issue_labels(conn: &Connection, issue_id: i64) -> Result<Vec<String>> {
     let mut stmt = conn.prepare(
         "SELECT l.name FROM labels l
@@ -217,9 +201,7 @@ fn get_issue_labels(conn: &Connection, issue_id: i64) -> Result<Vec<String>> {
     Ok(labels)
 }
 
-/// Get discussions with notes for an issue.
 fn get_issue_discussions(conn: &Connection, issue_id: i64) -> Result<Vec<DiscussionDetail>> {
-    // First get all discussions
     let mut disc_stmt = conn.prepare(
         "SELECT id, individual_note FROM discussions
          WHERE issue_id = ?
@@ -233,7 +215,6 @@ fn get_issue_discussions(conn: &Connection, issue_id: i64) -> Result<Vec<Discuss
         })?
         .collect::<std::result::Result<Vec<_>, _>>()?;
 
-    // Then get notes for each discussion
     let mut note_stmt = conn.prepare(
         "SELECT author_username, body, created_at, is_system
          FROM notes
@@ -255,7 +236,6 @@ fn get_issue_discussions(conn: &Connection, issue_id: i64) -> Result<Vec<Discuss
             })?
             .collect::<std::result::Result<Vec<_>, _>>()?;
 
-        // Filter out discussions with only system notes
         let has_user_notes = notes.iter().any(|n| !n.is_system);
         if has_user_notes || notes.is_empty() {
             discussions.push(DiscussionDetail {
@@ -268,24 +248,18 @@ fn get_issue_discussions(conn: &Connection, issue_id: i64) -> Result<Vec<Discuss
     Ok(discussions)
 }
 
-/// Run the show MR command.
 pub fn run_show_mr(config: &Config, iid: i64, project_filter: Option<&str>) -> Result<MrDetail> {
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
 
-    // Find the MR
     let mr = find_mr(&conn, iid, project_filter)?;
 
-    // Load labels
     let labels = get_mr_labels(&conn, mr.id)?;
 
-    // Load assignees
     let assignees = get_mr_assignees(&conn, mr.id)?;
 
-    // Load reviewers
     let reviewers = get_mr_reviewers(&conn, mr.id)?;
 
-    // Load discussions with notes
     let discussions = get_mr_discussions(&conn, mr.id)?;
 
     Ok(MrDetail {
@@ -311,7 +285,6 @@ pub fn run_show_mr(config: &Config, iid: i64, project_filter: Option<&str>) -> R
     })
 }
 
-/// Internal MR row from query.
 struct MrRow {
     id: i64,
     iid: i64,
@@ -330,7 +303,6 @@ struct MrRow {
     project_path: String,
 }
 
-/// Find MR by iid, optionally filtered by project.
 fn find_mr(conn: &Connection, iid: i64, project_filter: Option<&str>) -> Result<MrRow> {
     let (sql, params): (&str, Vec<Box<dyn rusqlite::ToSql>>) = match project_filter {
         Some(project) => {
@@ -398,7 +370,6 @@ fn find_mr(conn: &Connection, iid: i64, project_filter: Option<&str>) -> Result<
     }
 }
 
-/// Get labels for an MR.
 fn get_mr_labels(conn: &Connection, mr_id: i64) -> Result<Vec<String>> {
     let mut stmt = conn.prepare(
         "SELECT l.name FROM labels l
@@ -414,7 +385,6 @@ fn get_mr_labels(conn: &Connection, mr_id: i64) -> Result<Vec<String>> {
     Ok(labels)
 }
 
-/// Get assignees for an MR.
 fn get_mr_assignees(conn: &Connection, mr_id: i64) -> Result<Vec<String>> {
     let mut stmt = conn.prepare(
         "SELECT username FROM mr_assignees
@@ -429,7 +399,6 @@ fn get_mr_assignees(conn: &Connection, mr_id: i64) -> Result<Vec<String>> {
     Ok(assignees)
 }
 
-/// Get reviewers for an MR.
 fn get_mr_reviewers(conn: &Connection, mr_id: i64) -> Result<Vec<String>> {
     let mut stmt = conn.prepare(
         "SELECT username FROM mr_reviewers
@@ -444,9 +413,7 @@ fn get_mr_reviewers(conn: &Connection, mr_id: i64) -> Result<Vec<String>> {
     Ok(reviewers)
 }
 
-/// Get discussions with notes for an MR.
 fn get_mr_discussions(conn: &Connection, mr_id: i64) -> Result<Vec<MrDiscussionDetail>> {
-    // First get all discussions
     let mut disc_stmt = conn.prepare(
         "SELECT id, individual_note FROM discussions
          WHERE merge_request_id = ?
@@ -460,7 +427,6 @@ fn get_mr_discussions(conn: &Connection, mr_id: i64) -> Result<Vec<MrDiscussionD
         })?
         .collect::<std::result::Result<Vec<_>, _>>()?;
 
-    // Then get notes for each discussion (with DiffNote position fields)
     let mut note_stmt = conn.prepare(
         "SELECT author_username, body, created_at, is_system,
                 position_old_path, position_new_path, position_old_line,
@@ -507,7 +473,6 @@ fn get_mr_discussions(conn: &Connection, mr_id: i64) -> Result<Vec<MrDiscussionD
             })?
             .collect::<std::result::Result<Vec<_>, _>>()?;
 
-        // Filter out discussions with only system notes
         let has_user_notes = notes.iter().any(|n| !n.is_system);
         if has_user_notes || notes.is_empty() {
             discussions.push(MrDiscussionDetail {
@@ -520,14 +485,11 @@ fn get_mr_discussions(conn: &Connection, mr_id: i64) -> Result<Vec<MrDiscussionD
     Ok(discussions)
 }
 
-/// Format date from ms epoch.
 fn format_date(ms: i64) -> String {
     let iso = ms_to_iso(ms);
-    // Extract just the date part (YYYY-MM-DD)
     iso.split('T').next().unwrap_or(&iso).to_string()
 }
 
-/// Truncate text with ellipsis (character-safe for UTF-8).
 fn truncate(s: &str, max_len: usize) -> String {
     if s.chars().count() <= max_len {
         s.to_string()
@@ -537,7 +499,6 @@ fn truncate(s: &str, max_len: usize) -> String {
     }
 }
 
-/// Wrap text to width, with indent prefix on continuation lines.
 fn wrap_text(text: &str, width: usize, indent: &str) -> String {
     let mut result = String::new();
     let mut current_line = String::new();
@@ -569,15 +530,12 @@ fn wrap_text(text: &str, width: usize, indent: &str) -> String {
     result
 }
 
-/// Print issue detail.
 pub fn print_show_issue(issue: &IssueDetail) {
-    // Header
     let header = format!("Issue #{}: {}", issue.iid, issue.title);
     println!("{}", style(&header).bold());
     println!("{}", "━".repeat(header.len().min(80)));
     println!();
 
-    // Metadata
     println!("Project:  {}", style(&issue.project_path).cyan());
 
     let state_styled = if issue.state == "opened" {
@@ -603,7 +561,6 @@ pub fn print_show_issue(issue: &IssueDetail) {
 
     println!();
 
-    // Description
     println!("{}", style("Description:").bold());
     if let Some(desc) = &issue.description {
         let truncated = truncate(desc, 500);
@@ -615,7 +572,6 @@ pub fn print_show_issue(issue: &IssueDetail) {
 
     println!();
 
-    // Discussions
     let user_discussions: Vec<&DiscussionDetail> = issue
         .discussions
         .iter()
@@ -636,7 +592,6 @@ pub fn print_show_issue(issue: &IssueDetail) {
                 discussion.notes.iter().filter(|n| !n.is_system).collect();
 
             if let Some(first_note) = user_notes.first() {
-                // First note of discussion (not indented)
                 println!(
                     "  {} ({}):",
                     style(format!("@{}", first_note.author_username)).cyan(),
@@ -646,7 +601,6 @@ pub fn print_show_issue(issue: &IssueDetail) {
                 println!("    {}", wrapped);
                 println!();
 
-                // Replies (indented)
                 for reply in user_notes.iter().skip(1) {
                     println!(
                         "      {} ({}):",
@@ -662,16 +616,13 @@ pub fn print_show_issue(issue: &IssueDetail) {
     }
 }
 
-/// Print MR detail.
 pub fn print_show_mr(mr: &MrDetail) {
-    // Header with draft indicator
     let draft_prefix = if mr.draft { "[Draft] " } else { "" };
     let header = format!("MR !{}: {}{}", mr.iid, draft_prefix, mr.title);
     println!("{}", style(&header).bold());
     println!("{}", "━".repeat(header.len().min(80)));
     println!();
 
-    // Metadata
     println!("Project:  {}", style(&mr.project_path).cyan());
 
     let state_styled = match mr.state.as_str() {
@@ -735,7 +686,6 @@ pub fn print_show_mr(mr: &MrDetail) {
 
     println!();
 
-    // Description
     println!("{}", style("Description:").bold());
     if let Some(desc) = &mr.description {
         let truncated = truncate(desc, 500);
@@ -747,7 +697,6 @@ pub fn print_show_mr(mr: &MrDetail) {
 
     println!();
 
-    // Discussions
     let user_discussions: Vec<&MrDiscussionDetail> = mr
         .discussions
         .iter()
@@ -768,12 +717,10 @@ pub fn print_show_mr(mr: &MrDetail) {
                 discussion.notes.iter().filter(|n| !n.is_system).collect();
 
             if let Some(first_note) = user_notes.first() {
-                // Print DiffNote position context if present
                 if let Some(pos) = &first_note.position {
                     print_diff_position(pos);
                 }
 
-                // First note of discussion (not indented)
                 println!(
                     "  {} ({}):",
                     style(format!("@{}", first_note.author_username)).cyan(),
@@ -783,7 +730,6 @@ pub fn print_show_mr(mr: &MrDetail) {
                 println!("    {}", wrapped);
                 println!();
 
-                // Replies (indented)
                 for reply in user_notes.iter().skip(1) {
                     println!(
                         "      {} ({}):",
@@ -799,7 +745,6 @@ pub fn print_show_mr(mr: &MrDetail) {
     }
 }
 
-/// Print DiffNote position context.
 fn print_diff_position(pos: &DiffNotePosition) {
     let file = pos.new_path.as_ref().or(pos.old_path.as_ref());
 
@@ -821,11 +766,6 @@ fn print_diff_position(pos: &DiffNotePosition) {
     }
 }
 
-// ============================================================================
-// JSON Output Structs (with ISO timestamps for machine consumption)
-// ============================================================================
-
-/// JSON output for issue detail.
 #[derive(Serialize)]
 pub struct IssueDetailJson {
     pub id: i64,
@@ -842,14 +782,12 @@ pub struct IssueDetailJson {
     pub discussions: Vec<DiscussionDetailJson>,
 }
 
-/// JSON output for discussion detail.
 #[derive(Serialize)]
 pub struct DiscussionDetailJson {
     pub notes: Vec<NoteDetailJson>,
     pub individual_note: bool,
 }
 
-/// JSON output for note detail.
 #[derive(Serialize)]
 pub struct NoteDetailJson {
     pub author_username: String,
@@ -897,7 +835,6 @@ impl From<&NoteDetail> for NoteDetailJson {
     }
 }
 
-/// JSON output for MR detail.
 #[derive(Serialize)]
 pub struct MrDetailJson {
     pub id: i64,
@@ -921,14 +858,12 @@ pub struct MrDetailJson {
     pub discussions: Vec<MrDiscussionDetailJson>,
 }
 
-/// JSON output for MR discussion detail.
 #[derive(Serialize)]
 pub struct MrDiscussionDetailJson {
     pub notes: Vec<MrNoteDetailJson>,
     pub individual_note: bool,
 }
 
-/// JSON output for MR note detail.
 #[derive(Serialize)]
 pub struct MrNoteDetailJson {
     pub author_username: String,
@@ -985,7 +920,6 @@ impl From<&MrNoteDetail> for MrNoteDetailJson {
     }
 }
 
-/// Print issue detail as JSON.
 pub fn print_show_issue_json(issue: &IssueDetail) {
     let json_result = IssueDetailJson::from(issue);
     match serde_json::to_string_pretty(&json_result) {
@@ -994,7 +928,6 @@ pub fn print_show_issue_json(issue: &IssueDetail) {
     }
 }
 
-/// Print MR detail as JSON.
 pub fn print_show_mr_json(mr: &MrDetail) {
     let json_result = MrDetailJson::from(mr);
     match serde_json::to_string_pretty(&json_result) {
@@ -1030,7 +963,6 @@ mod tests {
 
     #[test]
     fn format_date_extracts_date_part() {
-        // 2024-01-15T00:00:00Z in milliseconds
         let ms = 1705276800000;
         let date = format_date(ms);
         assert!(date.starts_with("2024-01-15"));
diff --git a/src/cli/commands/stats.rs b/src/cli/commands/stats.rs
index 2303ad4..38ec6c1 100644
--- a/src/cli/commands/stats.rs
+++ b/src/cli/commands/stats.rs
@@ -1,5 +1,3 @@
-//! Stats command: document counts, embedding coverage, queue status, integrity checks.
-
 use console::style;
 use rusqlite::Connection;
 use serde::Serialize;
@@ -9,7 +7,6 @@ use crate::core::db::create_connection;
 use crate::core::error::Result;
 use crate::core::paths::get_db_path;
 
-/// Result of the stats command.
 #[derive(Debug, Default, Serialize)]
 pub struct StatsResult {
     pub documents: DocumentStats,
@@ -74,14 +71,12 @@ pub struct RepairResult {
     pub stale_cleared: i64,
 }
 
-/// Run the stats command.
 pub fn run_stats(config: &Config, check: bool, repair: bool) -> Result<StatsResult> {
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
 
     let mut result = StatsResult::default();
 
-    // Document counts
     result.documents.total = count_query(&conn, "SELECT COUNT(*) FROM documents")?;
     result.documents.issues = count_query(
         &conn,
@@ -100,7 +95,6 @@ pub fn run_stats(config: &Config, check: bool, repair: bool) -> Result<StatsResu
         "SELECT COUNT(*) FROM documents WHERE is_truncated = 1",
     )?;
 
-    // Embedding stats — skip gracefully if table doesn't exist (Gate A only)
     if table_exists(&conn, "embedding_metadata") {
         let embedded = count_query(
             &conn,
@@ -119,10 +113,8 @@ pub fn run_stats(config: &Config, check: bool, repair: bool) -> Result<StatsResu
         };
     }
 
-    // FTS stats
     result.fts.indexed = count_query(&conn, "SELECT COUNT(*) FROM documents_fts")?;
 
-    // Queue stats
     result.queues.dirty_sources = count_query(
         &conn,
         "SELECT COUNT(*) FROM dirty_sources WHERE last_error IS NULL",
@@ -158,15 +150,12 @@ pub fn run_stats(config: &Config, check: bool, repair: bool) -> Result<StatsResu
         )?;
     }
 
-    // Integrity check
     #[allow(clippy::field_reassign_with_default)]
     if check {
         let mut integrity = IntegrityResult::default();
 
-        // FTS/doc count mismatch
         integrity.fts_doc_mismatch = result.fts.indexed != result.documents.total;
 
-        // Orphan embeddings (rowid/1000 should match a document ID)
         if table_exists(&conn, "embeddings") {
             integrity.orphan_embeddings = count_query(
                 &conn,
@@ -175,7 +164,6 @@ pub fn run_stats(config: &Config, check: bool, repair: bool) -> Result<StatsResu
             )?;
         }
 
-        // Stale metadata (document_hash != current content_hash)
         if table_exists(&conn, "embedding_metadata") {
             integrity.stale_metadata = count_query(
                 &conn,
@@ -185,7 +173,6 @@ pub fn run_stats(config: &Config, check: bool, repair: bool) -> Result<StatsResu
             )?;
         }
 
-        // Orphaned resource events (FK targets missing)
         if table_exists(&conn, "resource_state_events") {
             integrity.orphan_state_events = count_query(
                 &conn,
@@ -211,7 +198,6 @@ pub fn run_stats(config: &Config, check: bool, repair: bool) -> Result<StatsResu
             )?;
         }
 
-        // Queue health: stuck locks and max retry attempts
         if table_exists(&conn, "pending_dependent_fetches") {
             integrity.queue_stuck_locks = count_query(
                 &conn,
@@ -232,7 +218,6 @@ pub fn run_stats(config: &Config, check: bool, repair: bool) -> Result<StatsResu
             && integrity.stale_metadata == 0
             && orphan_events == 0;
 
-        // Repair
         if repair {
             let mut repair_result = RepairResult::default();
 
@@ -252,7 +237,6 @@ pub fn run_stats(config: &Config, check: bool, repair: bool) -> Result<StatsResu
                 )?;
                 repair_result.orphans_deleted = deleted as i64;
 
-                // Also clean orphaned vectors if vec0 table exists
                 if table_exists(&conn, "embeddings") {
                     let _ = conn.execute(
                         "DELETE FROM embeddings
@@ -299,7 +283,6 @@ fn table_exists(conn: &Connection, table: &str) -> bool {
         > 0
 }
 
-/// Print human-readable stats.
 pub fn print_stats(result: &StatsResult) {
     println!("{}", style("Documents").cyan().bold());
     println!("  Total:           {}", result.documents.total);
@@ -429,14 +412,12 @@ pub fn print_stats(result: &StatsResult) {
     }
 }
 
-/// JSON output structures.
 #[derive(Serialize)]
 struct StatsJsonOutput {
     ok: bool,
     data: StatsResult,
 }
 
-/// Print JSON robot-mode output.
 pub fn print_stats_json(result: &StatsResult) {
     let output = StatsJsonOutput {
         ok: true,
diff --git a/src/cli/commands/sync.rs b/src/cli/commands/sync.rs
index 969e531..4c40380 100644
--- a/src/cli/commands/sync.rs
+++ b/src/cli/commands/sync.rs
@@ -1,10 +1,8 @@
-//! Sync command: unified orchestrator for ingest -> generate-docs -> embed.
-
 use console::style;
 use indicatif::{ProgressBar, ProgressStyle};
 use serde::Serialize;
-use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
 use tracing::Instrument;
 use tracing::{info, warn};
 
@@ -16,7 +14,6 @@ use super::embed::run_embed;
 use super::generate_docs::run_generate_docs;
 use super::ingest::{IngestDisplay, run_ingest};
 
-/// Options for the sync command.
 #[derive(Debug, Default)]
 pub struct SyncOptions {
     pub full: bool,
@@ -27,7 +24,6 @@ pub struct SyncOptions {
     pub robot_mode: bool,
 }
 
-/// Result of the sync command.
 #[derive(Debug, Default, Serialize)]
 pub struct SyncResult {
     #[serde(skip)]
@@ -41,10 +37,6 @@ pub struct SyncResult {
     pub documents_embedded: usize,
 }
 
-/// Create a styled spinner for a sync stage.
-///
-/// Uses `{prefix}` for the `[N/M]` stage label so callers can update `{msg}`
-/// independently without losing the stage context.
 fn stage_spinner(stage: u8, total: u8, msg: &str, robot_mode: bool) -> ProgressBar {
     if robot_mode {
         return ProgressBar::hidden();
@@ -61,11 +53,6 @@ fn stage_spinner(stage: u8, total: u8, msg: &str, robot_mode: bool) -> ProgressB
     pb
 }
 
-/// Run the full sync pipeline: ingest -> generate-docs -> embed.
-///
-/// `run_id` is an optional correlation ID for log/metrics tracing.
-/// When called from `handle_sync_cmd`, this should be the same ID
-/// stored in the `sync_runs` table so logs and DB records correlate.
 pub async fn run_sync(
     config: &Config,
     options: SyncOptions,
@@ -102,7 +89,6 @@ pub async fn run_sync(
         };
         let mut current_stage: u8 = 0;
 
-        // Stage 1: Ingest issues
         current_stage += 1;
         let spinner = stage_spinner(
             current_stage,
@@ -127,7 +113,6 @@ pub async fn run_sync(
         result.resource_events_failed += issues_result.resource_events_failed;
         spinner.finish_and_clear();
 
-        // Stage 2: Ingest MRs
         current_stage += 1;
         let spinner = stage_spinner(
             current_stage,
@@ -152,7 +137,6 @@ pub async fn run_sync(
         result.resource_events_failed += mrs_result.resource_events_failed;
         spinner.finish_and_clear();
 
-        // Stage 3: Generate documents (unless --no-docs)
         if !options.no_docs {
             current_stage += 1;
             let spinner = stage_spinner(
@@ -163,7 +147,6 @@ pub async fn run_sync(
             );
             info!("Sync stage {current_stage}/{total_stages}: generating documents");
 
-            // Create a dedicated progress bar matching the ingest stage style
             let docs_bar = if options.robot_mode {
                 ProgressBar::hidden()
             } else {
@@ -186,8 +169,6 @@ pub async fn run_sync(
                     if !tick_started_clone.swap(true, Ordering::Relaxed) {
                         docs_bar_clone.enable_steady_tick(std::time::Duration::from_millis(100));
                     }
-                    // Update length every callback — the regenerator's estimated_total
-                    // can grow if new dirty items are queued during processing.
                     docs_bar_clone.set_length(total as u64);
                     docs_bar_clone.set_position(processed as u64);
                 }
@@ -200,7 +181,6 @@ pub async fn run_sync(
             info!("Sync: skipping document generation (--no-docs)");
         }
 
-        // Stage 4: Embed documents (unless --no-embed)
         if !options.no_embed {
             current_stage += 1;
             let spinner = stage_spinner(
@@ -211,7 +191,6 @@ pub async fn run_sync(
             );
             info!("Sync stage {current_stage}/{total_stages}: embedding documents");
 
-            // Create a dedicated progress bar matching the ingest stage style
             let embed_bar = if options.robot_mode {
                 ProgressBar::hidden()
             } else {
@@ -245,7 +224,6 @@ pub async fn run_sync(
                     spinner.finish_and_clear();
                 }
                 Err(e) => {
-                    // Graceful degradation: Ollama down is a warning, not an error
                     embed_bar.finish_and_clear();
                     spinner.finish_and_clear();
                     if !options.robot_mode {
@@ -275,7 +253,6 @@ pub async fn run_sync(
     .await
 }
 
-/// Print human-readable sync summary.
 pub fn print_sync(
     result: &SyncResult,
     elapsed: std::time::Duration,
@@ -307,7 +284,6 @@ pub fn print_sync(
     println!("  Documents embedded:        {}", result.documents_embedded);
     println!("  Elapsed: {:.1}s", elapsed.as_secs_f64());
 
-    // Print per-stage timing breakdown if metrics are available
     if let Some(metrics) = metrics {
         let stages = metrics.extract_timings();
         if !stages.is_empty() {
@@ -316,7 +292,6 @@ pub fn print_sync(
     }
 }
 
-/// Print per-stage timing breakdown for interactive users.
 fn print_timing_summary(stages: &[StageTiming]) {
     println!();
     println!("{}", style("Stage timing:").dim());
@@ -327,7 +302,6 @@ fn print_timing_summary(stages: &[StageTiming]) {
     }
 }
 
-/// Print a single stage timing line with indentation.
 fn print_stage_line(stage: &StageTiming, depth: usize) {
     let indent = "  ".repeat(depth);
     let name = if let Some(ref project) = stage.project {
@@ -367,7 +341,6 @@ fn print_stage_line(stage: &StageTiming, depth: usize) {
     }
 }
 
-/// JSON output for sync.
 #[derive(Serialize)]
 struct SyncJsonOutput<'a> {
     ok: bool,
@@ -383,7 +356,6 @@ struct SyncMeta {
     stages: Vec<StageTiming>,
 }
 
-/// Print JSON robot-mode sync output with optional metrics.
 pub fn print_sync_json(result: &SyncResult, elapsed_ms: u64, metrics: Option<&MetricsLayer>) {
     let stages = metrics.map_or_else(Vec::new, MetricsLayer::extract_timings);
     let output = SyncJsonOutput {
diff --git a/src/cli/commands/sync_status.rs b/src/cli/commands/sync_status.rs
index a68ab92..69f4708 100644
--- a/src/cli/commands/sync_status.rs
+++ b/src/cli/commands/sync_status.rs
@@ -1,5 +1,3 @@
-//! Sync status command - display synchronization state from local database.
-
 use console::style;
 use rusqlite::Connection;
 use serde::Serialize;
@@ -13,7 +11,6 @@ use crate::core::time::{format_full_datetime, ms_to_iso};
 
 const RECENT_RUNS_LIMIT: usize = 10;
 
-/// Sync run information.
 #[derive(Debug)]
 pub struct SyncRunInfo {
     pub id: i64,
@@ -28,7 +25,6 @@ pub struct SyncRunInfo {
     pub stages: Option<Vec<StageTiming>>,
 }
 
-/// Cursor position information.
 #[derive(Debug)]
 pub struct CursorInfo {
     pub project_path: String,
@@ -37,7 +33,6 @@ pub struct CursorInfo {
     pub tie_breaker_id: Option<i64>,
 }
 
-/// Data summary counts.
 #[derive(Debug)]
 pub struct DataSummary {
     pub issue_count: i64,
@@ -47,7 +42,6 @@ pub struct DataSummary {
     pub system_note_count: i64,
 }
 
-/// Complete sync status result.
 #[derive(Debug)]
 pub struct SyncStatusResult {
     pub runs: Vec<SyncRunInfo>,
@@ -55,7 +49,6 @@ pub struct SyncStatusResult {
     pub summary: DataSummary,
 }
 
-/// Run the sync-status command.
 pub fn run_sync_status(config: &Config) -> Result<SyncStatusResult> {
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let conn = create_connection(&db_path)?;
@@ -71,7 +64,6 @@ pub fn run_sync_status(config: &Config) -> Result<SyncStatusResult> {
     })
 }
 
-/// Get the most recent sync runs.
 fn get_recent_sync_runs(conn: &Connection, limit: usize) -> Result<Vec<SyncRunInfo>> {
     let mut stmt = conn.prepare(
         "SELECT id, started_at, finished_at, status, command, error,
@@ -105,7 +97,6 @@ fn get_recent_sync_runs(conn: &Connection, limit: usize) -> Result<Vec<SyncRunIn
     Ok(runs?)
 }
 
-/// Get cursor positions for all projects/resource types.
 fn get_cursor_positions(conn: &Connection) -> Result<Vec<CursorInfo>> {
     let mut stmt = conn.prepare(
         "SELECT p.path_with_namespace, sc.resource_type, sc.updated_at_cursor, sc.tie_breaker_id
@@ -128,7 +119,6 @@ fn get_cursor_positions(conn: &Connection) -> Result<Vec<CursorInfo>> {
     Ok(cursors?)
 }
 
-/// Get data summary counts.
 fn get_data_summary(conn: &Connection) -> Result<DataSummary> {
     let issue_count: i64 = conn
         .query_row("SELECT COUNT(*) FROM issues", [], |row| row.get(0))
@@ -159,7 +149,6 @@ fn get_data_summary(conn: &Connection) -> Result<DataSummary> {
     })
 }
 
-/// Format duration in milliseconds to human-readable string.
 fn format_duration(ms: i64) -> String {
     let seconds = ms / 1000;
     let minutes = seconds / 60;
@@ -176,7 +165,6 @@ fn format_duration(ms: i64) -> String {
     }
 }
 
-/// Format number with thousands separators.
 fn format_number(n: i64) -> String {
     let is_negative = n < 0;
     let abs_n = n.unsigned_abs();
@@ -198,10 +186,6 @@ fn format_number(n: i64) -> String {
     result
 }
 
-// ============================================================================
-// JSON output structures for robot mode
-// ============================================================================
-
 #[derive(Serialize)]
 struct SyncStatusJsonOutput {
     ok: bool,
@@ -254,7 +238,6 @@ struct SummaryJsonInfo {
     system_notes: i64,
 }
 
-/// Print sync status as JSON (robot mode).
 pub fn print_sync_status_json(result: &SyncStatusResult) {
     let runs = result
         .runs
@@ -306,13 +289,7 @@ pub fn print_sync_status_json(result: &SyncStatusResult) {
     println!("{}", serde_json::to_string(&output).unwrap());
 }
 
-// ============================================================================
-// Human-readable output
-// ============================================================================
-
-/// Print sync status result.
 pub fn print_sync_status(result: &SyncStatusResult) {
-    // Recent Runs section
     println!("{}", style("Recent Sync Runs").bold().underlined());
     println!();
 
@@ -330,7 +307,6 @@ pub fn print_sync_status(result: &SyncStatusResult) {
 
     println!();
 
-    // Cursor Positions section
     println!("{}", style("Cursor Positions").bold().underlined());
     println!();
 
@@ -361,7 +337,6 @@ pub fn print_sync_status(result: &SyncStatusResult) {
 
     println!();
 
-    // Data Summary section
     println!("{}", style("Data Summary").bold().underlined());
     println!();
 
@@ -390,7 +365,6 @@ pub fn print_sync_status(result: &SyncStatusResult) {
     );
 }
 
-/// Print a single run as a compact one-liner.
 fn print_run_line(run: &SyncRunInfo) {
     let status_styled = match run.status.as_str() {
         "succeeded" => style(&run.status).green(),
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 8692577..d6a1897 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1,41 +1,31 @@
-//! CLI module with clap command definitions.
-
 pub mod commands;
 pub mod progress;
 
 use clap::{Parser, Subcommand};
 use std::io::IsTerminal;
 
-/// Gitlore - Local GitLab data management with semantic search
 #[derive(Parser)]
 #[command(name = "lore")]
 #[command(version, about, long_about = None)]
 pub struct Cli {
-    /// Path to config file
     #[arg(short = 'c', long, global = true)]
     pub config: Option<String>,
 
-    /// Machine-readable JSON output (auto-enabled when piped)
     #[arg(long, global = true, env = "LORE_ROBOT")]
     pub robot: bool,
 
-    /// JSON output (global shorthand)
     #[arg(short = 'J', long = "json", global = true)]
     pub json: bool,
 
-    /// Color output: auto (default), always, or never
     #[arg(long, global = true, value_parser = ["auto", "always", "never"], default_value = "auto")]
     pub color: String,
 
-    /// Suppress non-essential output
     #[arg(short = 'q', long, global = true)]
     pub quiet: bool,
 
-    /// Increase log verbosity (-v, -vv, -vvv)
     #[arg(short = 'v', long = "verbose", action = clap::ArgAction::Count, global = true)]
     pub verbose: u8,
 
-    /// Log format for stderr output: text (default) or json
     #[arg(long = "log-format", global = true, value_parser = ["text", "json"], default_value = "text")]
     pub log_format: String,
 
@@ -44,7 +34,6 @@ pub struct Cli {
 }
 
 impl Cli {
-    /// Check if robot mode is active (explicit flag, env var, or non-TTY stdout)
     pub fn is_robot_mode(&self) -> bool {
         self.robot || self.json || !std::io::stdout().is_terminal()
     }
@@ -53,104 +42,74 @@ impl Cli {
 #[derive(Subcommand)]
 #[allow(clippy::large_enum_variant)]
 pub enum Commands {
-    /// List or show issues
     Issues(IssuesArgs),
 
-    /// List or show merge requests
     Mrs(MrsArgs),
 
-    /// Ingest data from GitLab
     Ingest(IngestArgs),
 
-    /// Count entities in local database
     Count(CountArgs),
 
-    /// Show sync state
     Status,
 
-    /// Verify GitLab authentication
     Auth,
 
-    /// Check environment health
     Doctor,
 
-    /// Show version information
     Version,
 
-    /// Initialize configuration and database
     Init {
-        /// Skip overwrite confirmation
         #[arg(short = 'f', long)]
         force: bool,
 
-        /// Fail if prompts would be shown
         #[arg(long)]
         non_interactive: bool,
 
-        /// GitLab base URL (required in robot mode)
         #[arg(long)]
         gitlab_url: Option<String>,
 
-        /// Environment variable name holding GitLab token (required in robot mode)
         #[arg(long)]
         token_env_var: Option<String>,
 
-        /// Comma-separated project paths (required in robot mode)
         #[arg(long)]
         projects: Option<String>,
     },
 
-    /// Create timestamped database backup
     #[command(hide = true)]
     Backup,
 
-    /// Delete database and reset all state
     #[command(hide = true)]
     Reset {
-        /// Skip confirmation prompt
         #[arg(short = 'y', long)]
         yes: bool,
     },
 
-    /// Search indexed documents
     Search(SearchArgs),
 
-    /// Show document and index statistics
     Stats(StatsArgs),
 
-    /// Generate searchable documents from ingested data
     #[command(name = "generate-docs")]
     GenerateDocs(GenerateDocsArgs),
 
-    /// Generate vector embeddings for documents via Ollama
     Embed(EmbedArgs),
 
-    /// Run full sync pipeline: ingest -> generate-docs -> embed
     Sync(SyncArgs),
 
-    /// Run pending database migrations
     Migrate,
 
-    /// Quick health check: config, database, schema version
     Health,
 
-    /// Machine-readable command manifest for agent self-discovery
     #[command(name = "robot-docs")]
     RobotDocs,
 
-    /// Generate shell completions
     #[command(hide = true)]
     Completions {
-        /// Shell to generate completions for
         #[arg(value_parser = ["bash", "zsh", "fish", "powershell"])]
         shell: String,
     },
 
-    // --- Hidden backward-compat aliases ---
-    /// List issues or MRs (deprecated: use 'lore issues' or 'lore mrs')
     #[command(hide = true)]
     List {
-        /// Entity type to list
         #[arg(value_parser = ["issues", "mrs"])]
         entity: String,
 
@@ -192,36 +151,28 @@ pub enum Commands {
         source_branch: Option<String>,
     },
 
-    /// Show detailed entity information (deprecated: use 'lore issues <IID>' or 'lore mrs <IID>')
     #[command(hide = true)]
     Show {
-        /// Entity type to show
         #[arg(value_parser = ["issue", "mr"])]
         entity: String,
 
-        /// Entity IID
         iid: i64,
 
         #[arg(long)]
         project: Option<String>,
     },
 
-    /// Verify GitLab authentication (deprecated: use 'lore auth')
     #[command(hide = true, name = "auth-test")]
     AuthTest,
 
-    /// Show sync state (deprecated: use 'lore status')
     #[command(hide = true, name = "sync-status")]
     SyncStatus,
 }
 
-/// Arguments for `lore issues [IID]`
 #[derive(Parser)]
 pub struct IssuesArgs {
-    /// Issue IID (omit to list, provide to show details)
     pub iid: Option<i64>,
 
-    /// Maximum results
     #[arg(
         short = 'n',
         long = "limit",
@@ -230,39 +181,30 @@ pub struct IssuesArgs {
     )]
     pub limit: usize,
 
-    /// Filter by state (opened, closed, all)
     #[arg(short = 's', long, help_heading = "Filters")]
     pub state: Option<String>,
 
-    /// Filter by project path
     #[arg(short = 'p', long, help_heading = "Filters")]
     pub project: Option<String>,
 
-    /// Filter by author username
     #[arg(short = 'a', long, help_heading = "Filters")]
     pub author: Option<String>,
 
-    /// Filter by assignee username
     #[arg(short = 'A', long, help_heading = "Filters")]
     pub assignee: Option<String>,
 
-    /// Filter by label (repeatable, AND logic)
     #[arg(short = 'l', long, help_heading = "Filters")]
     pub label: Option<Vec<String>>,
 
-    /// Filter by milestone title
     #[arg(short = 'm', long, help_heading = "Filters")]
     pub milestone: Option<String>,
 
-    /// Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
     #[arg(long, help_heading = "Filters")]
     pub since: Option<String>,
 
-    /// Filter by due date (before this date, YYYY-MM-DD)
     #[arg(long = "due-before", help_heading = "Filters")]
     pub due_before: Option<String>,
 
-    /// Show only issues with a due date
     #[arg(
         long = "has-due",
         help_heading = "Filters",
@@ -273,18 +215,15 @@ pub struct IssuesArgs {
     #[arg(long = "no-has-due", hide = true, overrides_with = "has_due")]
     pub no_has_due: bool,
 
-    /// Sort field (updated, created, iid)
     #[arg(long, value_parser = ["updated", "created", "iid"], default_value = "updated", help_heading = "Sorting")]
     pub sort: String,
 
-    /// Sort ascending (default: descending)
     #[arg(long, help_heading = "Sorting", overrides_with = "no_asc")]
     pub asc: bool,
 
     #[arg(long = "no-asc", hide = true, overrides_with = "asc")]
     pub no_asc: bool,
 
-    /// Open first matching item in browser
     #[arg(
         short = 'o',
         long,
@@ -297,13 +236,10 @@ pub struct IssuesArgs {
     pub no_open: bool,
 }
 
-/// Arguments for `lore mrs [IID]`
 #[derive(Parser)]
 pub struct MrsArgs {
-    /// MR IID (omit to list, provide to show details)
     pub iid: Option<i64>,
 
-    /// Maximum results
     #[arg(
         short = 'n',
         long = "limit",
@@ -312,35 +248,27 @@ pub struct MrsArgs {
     )]
     pub limit: usize,
 
-    /// Filter by state (opened, merged, closed, locked, all)
     #[arg(short = 's', long, help_heading = "Filters")]
     pub state: Option<String>,
 
-    /// Filter by project path
     #[arg(short = 'p', long, help_heading = "Filters")]
     pub project: Option<String>,
 
-    /// Filter by author username
     #[arg(short = 'a', long, help_heading = "Filters")]
     pub author: Option<String>,
 
-    /// Filter by assignee username
     #[arg(short = 'A', long, help_heading = "Filters")]
     pub assignee: Option<String>,
 
-    /// Filter by reviewer username
     #[arg(short = 'r', long, help_heading = "Filters")]
     pub reviewer: Option<String>,
 
-    /// Filter by label (repeatable, AND logic)
     #[arg(short = 'l', long, help_heading = "Filters")]
     pub label: Option<Vec<String>>,
 
-    /// Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
     #[arg(long, help_heading = "Filters")]
     pub since: Option<String>,
 
-    /// Show only draft MRs
     #[arg(
         short = 'd',
         long,
@@ -349,7 +277,6 @@ pub struct MrsArgs {
     )]
     pub draft: bool,
 
-    /// Exclude draft MRs
     #[arg(
         short = 'D',
         long = "no-draft",
@@ -358,26 +285,21 @@ pub struct MrsArgs {
     )]
     pub no_draft: bool,
 
-    /// Filter by target branch
     #[arg(long, help_heading = "Filters")]
     pub target: Option<String>,
 
-    /// Filter by source branch
     #[arg(long, help_heading = "Filters")]
     pub source: Option<String>,
 
-    /// Sort field (updated, created, iid)
     #[arg(long, value_parser = ["updated", "created", "iid"], default_value = "updated", help_heading = "Sorting")]
     pub sort: String,
 
-    /// Sort ascending (default: descending)
     #[arg(long, help_heading = "Sorting", overrides_with = "no_asc")]
     pub asc: bool,
 
     #[arg(long = "no-asc", hide = true, overrides_with = "asc")]
     pub no_asc: bool,
 
-    /// Open first matching item in browser
     #[arg(
         short = 'o',
         long,
@@ -390,25 +312,20 @@ pub struct MrsArgs {
     pub no_open: bool,
 }
 
-/// Arguments for `lore ingest [ENTITY]`
 #[derive(Parser)]
 pub struct IngestArgs {
-    /// Entity to ingest (issues, mrs). Omit to ingest everything.
     #[arg(value_parser = ["issues", "mrs"])]
     pub entity: Option<String>,
 
-    /// Filter to single project
     #[arg(short = 'p', long)]
     pub project: Option<String>,
 
-    /// Override stale sync lock
     #[arg(short = 'f', long, overrides_with = "no_force")]
     pub force: bool,
 
     #[arg(long = "no-force", hide = true, overrides_with = "force")]
     pub no_force: bool,
 
-    /// Full re-sync: reset cursors and fetch all data from scratch
     #[arg(long, overrides_with = "no_full")]
     pub full: bool,
 
@@ -416,60 +333,46 @@ pub struct IngestArgs {
     pub no_full: bool,
 }
 
-/// Arguments for `lore stats`
 #[derive(Parser)]
 pub struct StatsArgs {
-    /// Run integrity checks
     #[arg(long, overrides_with = "no_check")]
     pub check: bool,
 
     #[arg(long = "no-check", hide = true, overrides_with = "check")]
     pub no_check: bool,
 
-    /// Repair integrity issues (auto-enables --check)
     #[arg(long)]
     pub repair: bool,
 }
 
-/// Arguments for `lore search <QUERY>`
 #[derive(Parser)]
 pub struct SearchArgs {
-    /// Search query string
     pub query: String,
 
-    /// Search mode (lexical, hybrid, semantic)
     #[arg(long, default_value = "hybrid", value_parser = ["lexical", "hybrid", "semantic"], help_heading = "Output")]
     pub mode: String,
 
-    /// Filter by source type (issue, mr, discussion)
     #[arg(long = "type", value_name = "TYPE", value_parser = ["issue", "mr", "discussion"], help_heading = "Filters")]
     pub source_type: Option<String>,
 
-    /// Filter by author username
     #[arg(long, help_heading = "Filters")]
     pub author: Option<String>,
 
-    /// Filter by project path
     #[arg(short = 'p', long, help_heading = "Filters")]
     pub project: Option<String>,
 
-    /// Filter by label (repeatable, AND logic)
     #[arg(long, action = clap::ArgAction::Append, help_heading = "Filters")]
     pub label: Vec<String>,
 
-    /// Filter by file path (trailing / for prefix match)
     #[arg(long, help_heading = "Filters")]
     pub path: Option<String>,
 
-    /// Filter by created after (7d, 2w, or YYYY-MM-DD)
     #[arg(long, help_heading = "Filters")]
     pub after: Option<String>,
 
-    /// Filter by updated after (7d, 2w, or YYYY-MM-DD)
     #[arg(long = "updated-after", help_heading = "Filters")]
     pub updated_after: Option<String>,
 
-    /// Maximum results (default 20, max 100)
     #[arg(
         short = 'n',
         long = "limit",
@@ -478,71 +381,57 @@ pub struct SearchArgs {
     )]
     pub limit: usize,
 
-    /// Show ranking explanation per result
     #[arg(long, help_heading = "Output", overrides_with = "no_explain")]
     pub explain: bool,
 
     #[arg(long = "no-explain", hide = true, overrides_with = "explain")]
     pub no_explain: bool,
 
-    /// FTS query mode: safe (default) or raw
     #[arg(long = "fts-mode", default_value = "safe", value_parser = ["safe", "raw"], help_heading = "Output")]
     pub fts_mode: String,
 }
 
-/// Arguments for `lore generate-docs`
 #[derive(Parser)]
 pub struct GenerateDocsArgs {
-    /// Full rebuild: seed all entities into dirty queue, then drain
     #[arg(long)]
     pub full: bool,
 
-    /// Filter to single project
     #[arg(short = 'p', long)]
     pub project: Option<String>,
 }
 
-/// Arguments for `lore sync`
 #[derive(Parser)]
 pub struct SyncArgs {
-    /// Reset cursors, fetch everything
     #[arg(long, overrides_with = "no_full")]
     pub full: bool,
 
     #[arg(long = "no-full", hide = true, overrides_with = "full")]
     pub no_full: bool,
 
-    /// Override stale lock
     #[arg(long, overrides_with = "no_force")]
     pub force: bool,
 
     #[arg(long = "no-force", hide = true, overrides_with = "force")]
     pub no_force: bool,
 
-    /// Skip embedding step
     #[arg(long)]
     pub no_embed: bool,
 
-    /// Skip document regeneration
     #[arg(long)]
     pub no_docs: bool,
 
-    /// Skip resource event fetching (overrides config)
     #[arg(long = "no-events")]
     pub no_events: bool,
 }
 
-/// Arguments for `lore embed`
 #[derive(Parser)]
 pub struct EmbedArgs {
-    /// Re-embed all documents (clears existing embeddings first)
     #[arg(long, overrides_with = "no_full")]
     pub full: bool,
 
     #[arg(long = "no-full", hide = true, overrides_with = "full")]
     pub no_full: bool,
 
-    /// Retry previously failed embeddings
     #[arg(long, overrides_with = "no_retry_failed")]
     pub retry_failed: bool,
 
@@ -550,14 +439,11 @@ pub struct EmbedArgs {
     pub no_retry_failed: bool,
 }
 
-/// Arguments for `lore count <ENTITY>`
 #[derive(Parser)]
 pub struct CountArgs {
-    /// Entity type to count (issues, mrs, discussions, notes, events)
     #[arg(value_parser = ["issues", "mrs", "discussions", "notes", "events"])]
     pub entity: String,
 
-    /// Parent type filter: issue or mr (for discussions/notes)
     #[arg(short = 'f', long = "for", value_parser = ["issue", "mr"])]
     pub for_entity: Option<String>,
 }
diff --git a/src/cli/progress.rs b/src/cli/progress.rs
index fadea11..7249ac9 100644
--- a/src/cli/progress.rs
+++ b/src/cli/progress.rs
@@ -1,41 +1,17 @@
-//! Shared progress bar infrastructure.
-//!
-//! All progress bars must be created via [`multi()`] to ensure coordinated
-//! rendering. The [`SuspendingWriter`] suspends the multi-progress before
-//! writing tracing output, preventing log lines from interleaving with
-//! progress bar animations.
-
 use indicatif::MultiProgress;
 use std::io::Write;
 use std::sync::LazyLock;
 use tracing_subscriber::fmt::MakeWriter;
 
-/// Global multi-progress that coordinates all progress bar rendering.
-///
-/// Every `ProgressBar` displayed to the user **must** be registered via
-/// `multi().add(bar)`. Standalone bars bypass the coordination and will
-/// fight with other bars for the terminal line, causing rapid flashing.
 static MULTI: LazyLock<MultiProgress> = LazyLock::new(MultiProgress::new);
 
-/// Returns the shared [`MultiProgress`] instance.
 pub fn multi() -> &'static MultiProgress {
     &MULTI
 }
 
-/// A tracing `MakeWriter` that suspends the shared [`MultiProgress`] while
-/// writing, so log output doesn't interleave with progress bar animations.
-///
-/// # How it works
-///
-/// `MultiProgress::suspend` temporarily clears all active progress bars from
-/// the terminal, executes the closure (which writes the log line), then
-/// redraws the bars. This ensures a clean, flicker-free display even when
-/// logging happens concurrently with progress updates.
 #[derive(Clone)]
 pub struct SuspendingWriter;
 
-/// Writer returned by [`SuspendingWriter`] that buffers a single log line
-/// and flushes it inside a `MultiProgress::suspend` call.
 pub struct SuspendingWriterInner {
     buf: Vec<u8>,
 }
@@ -47,7 +23,6 @@ impl Write for SuspendingWriterInner {
     }
 
     fn flush(&mut self) -> std::io::Result<()> {
-        // Nothing to do — actual flush happens on drop.
         Ok(())
     }
 }
@@ -102,10 +77,8 @@ mod tests {
     fn suspending_writer_buffers_and_flushes() {
         let writer = SuspendingWriter;
         let mut w = MakeWriter::make_writer(&writer);
-        // Write should succeed and buffer data
         let n = w.write(b"test log line\n").unwrap();
         assert_eq!(n, 14);
-        // Drop flushes via suspend — no panic means it works
         drop(w);
     }
 
@@ -113,7 +86,6 @@ mod tests {
     fn suspending_writer_empty_does_not_flush() {
         let writer = SuspendingWriter;
         let w = MakeWriter::make_writer(&writer);
-        // Drop with empty buffer — should be a no-op
         drop(w);
     }
 }
diff --git a/src/core/backoff.rs b/src/core/backoff.rs
index d1f0bd3..ffd3981 100644
--- a/src/core/backoff.rs
+++ b/src/core/backoff.rs
@@ -1,24 +1,10 @@
 use rand::Rng;
 
-/// Compute next_attempt_at with exponential backoff and jitter.
-///
-/// Formula: now + min(3600000, 1000 * 2^attempt_count) * (0.9 to 1.1)
-/// - Capped at 1 hour to prevent runaway delays
-/// - ±10% jitter prevents synchronized retries after outages
-///
-/// Used by:
-/// - `dirty_sources` retry scheduling (document regeneration failures)
-/// - `pending_discussion_fetches` retry scheduling (API fetch failures)
-///
-/// Having one implementation prevents subtle divergence between queues
-/// (e.g., different caps or jitter ranges).
 pub fn compute_next_attempt_at(now: i64, attempt_count: i64) -> i64 {
-    // Cap attempt_count to prevent overflow (2^30 > 1 hour anyway)
     let capped_attempts = attempt_count.min(30) as u32;
     let base_delay_ms = 1000_i64.saturating_mul(1 << capped_attempts);
-    let capped_delay_ms = base_delay_ms.min(3_600_000); // 1 hour cap
+    let capped_delay_ms = base_delay_ms.min(3_600_000);
 
-    // Add ±10% jitter
     let jitter_factor = rand::thread_rng().gen_range(0.9..=1.1);
     let delay_with_jitter = (capped_delay_ms as f64 * jitter_factor) as i64;
 
@@ -34,7 +20,6 @@ mod tests {
     #[test]
     fn test_exponential_curve() {
         let now = 1_000_000_000_i64;
-        // Each attempt should roughly double the delay (within jitter)
         for attempt in 1..=10 {
             let result = compute_next_attempt_at(now, attempt);
             let delay = result - now;
@@ -65,7 +50,7 @@ mod tests {
     #[test]
     fn test_jitter_range() {
         let now = 1_000_000_000_i64;
-        let attempt = 5; // base = 32000
+        let attempt = 5;
         let base = 1000_i64 * (1 << attempt);
         let min_delay = (base as f64 * 0.89) as i64;
         let max_delay = (base as f64 * 1.11) as i64;
@@ -85,7 +70,6 @@ mod tests {
         let now = 1_000_000_000_i64;
         let result = compute_next_attempt_at(now, 1);
         let delay = result - now;
-        // attempt 1: base = 2000ms, with jitter: 1800-2200ms
         assert!(
             (1800..=2200).contains(&delay),
             "first retry delay: {delay}ms"
@@ -95,7 +79,6 @@ mod tests {
     #[test]
     fn test_overflow_safety() {
         let now = i64::MAX / 2;
-        // Should not panic even with very large attempt_count
         let result = compute_next_attempt_at(now, i64::MAX);
         assert!(result > now);
     }
diff --git a/src/core/config.rs b/src/core/config.rs
index 6cae328..547ed77 100644
--- a/src/core/config.rs
+++ b/src/core/config.rs
@@ -1,7 +1,3 @@
-//! Configuration loading and validation.
-//!
-//! Config schema mirrors the TypeScript version with serde for deserialization.
-
 use serde::Deserialize;
 use std::fs;
 use std::path::Path;
@@ -9,7 +5,6 @@ use std::path::Path;
 use super::error::{LoreError, Result};
 use super::paths::get_config_path;
 
-/// GitLab connection settings.
 #[derive(Debug, Clone, Deserialize)]
 pub struct GitLabConfig {
     #[serde(rename = "baseUrl")]
@@ -23,13 +18,11 @@ fn default_token_env_var() -> String {
     "GITLAB_TOKEN".to_string()
 }
 
-/// Project to sync.
 #[derive(Debug, Clone, Deserialize)]
 pub struct ProjectConfig {
     pub path: String,
 }
 
-/// Sync behavior settings.
 #[derive(Debug, Clone, Deserialize)]
 #[serde(default)]
 pub struct SyncConfig {
@@ -77,7 +70,6 @@ impl Default for SyncConfig {
     }
 }
 
-/// Storage settings.
 #[derive(Debug, Clone, Deserialize, Default)]
 #[serde(default)]
 pub struct StorageConfig {
@@ -98,7 +90,6 @@ fn default_compress_raw_payloads() -> bool {
     true
 }
 
-/// Embedding provider settings.
 #[derive(Debug, Clone, Deserialize)]
 #[serde(default)]
 pub struct EmbeddingConfig {
@@ -120,19 +111,15 @@ impl Default for EmbeddingConfig {
     }
 }
 
-/// Logging and observability settings.
 #[derive(Debug, Clone, Deserialize)]
 #[serde(default)]
 pub struct LoggingConfig {
-    /// Directory for log files. Default: ~/.local/share/lore/logs/
     #[serde(rename = "logDir")]
     pub log_dir: Option<String>,
 
-    /// Days to retain log files. Default: 30. Set to 0 to disable file logging.
     #[serde(rename = "retentionDays", default = "default_retention_days")]
     pub retention_days: u32,
 
-    /// Enable JSON log files. Default: true.
     #[serde(rename = "fileLogging", default = "default_file_logging")]
     pub file_logging: bool,
 }
@@ -155,7 +142,6 @@ impl Default for LoggingConfig {
     }
 }
 
-/// Main configuration structure.
 #[derive(Debug, Clone, Deserialize)]
 pub struct Config {
     pub gitlab: GitLabConfig,
@@ -175,7 +161,6 @@ pub struct Config {
 }
 
 impl Config {
-    /// Load and validate configuration from file.
     pub fn load(cli_override: Option<&str>) -> Result<Self> {
         let config_path = get_config_path(cli_override);
 
@@ -188,7 +173,6 @@ impl Config {
         Self::load_from_path(&config_path)
     }
 
-    /// Load configuration from a specific path.
     pub fn load_from_path(path: &Path) -> Result<Self> {
         let content = fs::read_to_string(path).map_err(|e| LoreError::ConfigInvalid {
             details: format!("Failed to read config file: {e}"),
@@ -199,7 +183,6 @@ impl Config {
                 details: format!("Invalid JSON: {e}"),
             })?;
 
-        // Validate required fields
         if config.projects.is_empty() {
             return Err(LoreError::ConfigInvalid {
                 details: "At least one project is required".to_string(),
@@ -214,7 +197,6 @@ impl Config {
             }
         }
 
-        // Validate URL format
         if url::Url::parse(&config.gitlab.base_url).is_err() {
             return Err(LoreError::ConfigInvalid {
                 details: format!("Invalid GitLab URL: {}", config.gitlab.base_url),
@@ -225,7 +207,6 @@ impl Config {
     }
 }
 
-/// Minimal config for writing during init (relies on defaults when loaded).
 #[derive(Debug, serde::Serialize)]
 pub struct MinimalConfig {
     pub gitlab: MinimalGitLabConfig,
diff --git a/src/core/db.rs b/src/core/db.rs
index c2b7079..7ef61f8 100644
--- a/src/core/db.rs
+++ b/src/core/db.rs
@@ -1,7 +1,3 @@
-//! Database connection and migration management.
-//!
-//! Uses rusqlite with WAL mode for crash safety.
-
 use rusqlite::Connection;
 use sqlite_vec::sqlite3_vec_init;
 use std::fs;
@@ -10,11 +6,8 @@ use tracing::{debug, info};
 
 use super::error::{LoreError, Result};
 
-/// Latest schema version, derived from the embedded migrations count.
-/// Used by the health check to verify databases are up-to-date.
 pub const LATEST_SCHEMA_VERSION: i32 = MIGRATIONS.len() as i32;
 
-/// Embedded migrations - compiled into the binary.
 const MIGRATIONS: &[(&str, &str)] = &[
     ("001", include_str!("../../migrations/001_initial.sql")),
     ("002", include_str!("../../migrations/002_issues.sql")),
@@ -53,9 +46,7 @@ const MIGRATIONS: &[(&str, &str)] = &[
     ),
 ];
 
-/// Create a database connection with production-grade pragmas.
 pub fn create_connection(db_path: &Path) -> Result<Connection> {
-    // Register sqlite-vec extension globally (safe to call multiple times)
     #[allow(clippy::missing_transmute_annotations)]
     unsafe {
         rusqlite::ffi::sqlite3_auto_extension(Some(std::mem::transmute(
@@ -63,30 +54,26 @@ pub fn create_connection(db_path: &Path) -> Result<Connection> {
         )));
     }
 
-    // Ensure parent directory exists
     if let Some(parent) = db_path.parent() {
         fs::create_dir_all(parent)?;
     }
 
     let conn = Connection::open(db_path)?;
 
-    // Production-grade pragmas for single-user CLI
     conn.pragma_update(None, "journal_mode", "WAL")?;
-    conn.pragma_update(None, "synchronous", "NORMAL")?; // Safe for WAL on local disk
+    conn.pragma_update(None, "synchronous", "NORMAL")?;
     conn.pragma_update(None, "foreign_keys", "ON")?;
-    conn.pragma_update(None, "busy_timeout", 5000)?; // 5s wait on lock contention
-    conn.pragma_update(None, "temp_store", "MEMORY")?; // Small speed win
-    conn.pragma_update(None, "cache_size", -64000)?; // 64MB cache (negative = KB)
-    conn.pragma_update(None, "mmap_size", 268_435_456)?; // 256MB memory-mapped I/O
+    conn.pragma_update(None, "busy_timeout", 5000)?;
+    conn.pragma_update(None, "temp_store", "MEMORY")?;
+    conn.pragma_update(None, "cache_size", -64000)?;
+    conn.pragma_update(None, "mmap_size", 268_435_456)?;
 
     debug!(db_path = %db_path.display(), "Database connection created");
 
     Ok(conn)
 }
 
-/// Run all pending migrations using embedded SQL.
 pub fn run_migrations(conn: &Connection) -> Result<()> {
-    // Get current schema version
     let has_version_table: bool = conn
         .query_row(
             "SELECT COUNT(*) > 0 FROM sqlite_master WHERE type='table' AND name='schema_version'",
@@ -114,9 +101,6 @@ pub fn run_migrations(conn: &Connection) -> Result<()> {
             continue;
         }
 
-        // Wrap each migration in a transaction to prevent partial application.
-        // If the migration SQL already contains BEGIN/COMMIT, execute_batch handles
-        // it, but wrapping in a savepoint ensures atomicity for those that don't.
         let savepoint_name = format!("migration_{}", version);
         conn.execute_batch(&format!("SAVEPOINT {}", savepoint_name))
             .map_err(|e| LoreError::MigrationFailed {
@@ -150,7 +134,6 @@ pub fn run_migrations(conn: &Connection) -> Result<()> {
     Ok(())
 }
 
-/// Run migrations from filesystem (for testing or custom migrations).
 #[allow(dead_code)]
 pub fn run_migrations_from_dir(conn: &Connection, migrations_dir: &Path) -> Result<()> {
     let has_version_table: bool = conn
@@ -194,8 +177,6 @@ pub fn run_migrations_from_dir(conn: &Connection, migrations_dir: &Path) -> Resu
 
         let sql = fs::read_to_string(entry.path())?;
 
-        // Wrap each migration in a savepoint to prevent partial application,
-        // matching the safety guarantees of run_migrations().
         let savepoint_name = format!("migration_{}", version);
         conn.execute_batch(&format!("SAVEPOINT {}", savepoint_name))
             .map_err(|e| LoreError::MigrationFailed {
@@ -229,8 +210,6 @@ pub fn run_migrations_from_dir(conn: &Connection, migrations_dir: &Path) -> Resu
     Ok(())
 }
 
-/// Verify database pragmas are set correctly.
-/// Used by lore doctor command.
 pub fn verify_pragmas(conn: &Connection) -> (bool, Vec<String>) {
     let mut issues = Vec::new();
 
@@ -258,7 +237,6 @@ pub fn verify_pragmas(conn: &Connection) -> (bool, Vec<String>) {
     let synchronous: i32 = conn
         .pragma_query_value(None, "synchronous", |row| row.get(0))
         .unwrap_or(0);
-    // NORMAL = 1
     if synchronous != 1 {
         issues.push(format!("synchronous is {synchronous}, expected 1 (NORMAL)"));
     }
@@ -266,7 +244,6 @@ pub fn verify_pragmas(conn: &Connection) -> (bool, Vec<String>) {
     (issues.is_empty(), issues)
 }
 
-/// Get current schema version.
 pub fn get_schema_version(conn: &Connection) -> i32 {
     let has_version_table: bool = conn
         .query_row(
diff --git a/src/core/dependent_queue.rs b/src/core/dependent_queue.rs
index 7fc1263..0652473 100644
--- a/src/core/dependent_queue.rs
+++ b/src/core/dependent_queue.rs
@@ -1,8 +1,3 @@
-//! Generic dependent fetch queue for resource events, MR closes, and MR diffs.
-//!
-//! Provides enqueue, claim, complete, fail (with exponential backoff), and
-//! stale lock reclamation operations against the `pending_dependent_fetches` table.
-
 use std::collections::HashMap;
 
 use rusqlite::Connection;
@@ -10,7 +5,6 @@ use rusqlite::Connection;
 use super::error::Result;
 use super::time::now_ms;
 
-/// A pending job from the dependent fetch queue.
 #[derive(Debug)]
 pub struct PendingJob {
     pub id: i64,
@@ -23,9 +17,6 @@ pub struct PendingJob {
     pub attempts: i32,
 }
 
-/// Enqueue a dependent fetch job. Idempotent via UNIQUE constraint (INSERT OR IGNORE).
-///
-/// Returns `true` if actually inserted (not deduped).
 pub fn enqueue_job(
     conn: &Connection,
     project_id: i64,
@@ -54,10 +45,6 @@ pub fn enqueue_job(
     Ok(changes > 0)
 }
 
-/// Claim a batch of jobs for processing, scoped to a specific project.
-///
-/// Atomically selects and locks jobs within a transaction. Only claims jobs
-/// where `locked_at IS NULL` and `(next_retry_at IS NULL OR next_retry_at <= now)`.
 pub fn claim_jobs(
     conn: &Connection,
     job_type: &str,
@@ -70,8 +57,6 @@ pub fn claim_jobs(
 
     let now = now_ms();
 
-    // Use UPDATE ... RETURNING to atomically select and lock in one statement.
-    // This eliminates the race between SELECT and UPDATE.
     let mut stmt = conn.prepare_cached(
         "UPDATE pending_dependent_fetches
          SET locked_at = ?1
@@ -109,7 +94,6 @@ pub fn claim_jobs(
     Ok(jobs)
 }
 
-/// Mark a job as complete (DELETE the row).
 pub fn complete_job(conn: &Connection, job_id: i64) -> Result<()> {
     conn.execute(
         "DELETE FROM pending_dependent_fetches WHERE id = ?1",
@@ -119,17 +103,9 @@ pub fn complete_job(conn: &Connection, job_id: i64) -> Result<()> {
     Ok(())
 }
 
-/// Mark a job as failed. Increments attempts, sets next_retry_at with exponential
-/// backoff, clears locked_at, and records the error.
-///
-/// Backoff: 30s * 2^(attempts), capped at 480s.  Uses a single atomic UPDATE
-/// to avoid a read-then-write race on the `attempts` counter.
 pub fn fail_job(conn: &Connection, job_id: i64, error: &str) -> Result<()> {
     let now = now_ms();
 
-    // Atomic increment + backoff calculation in one UPDATE.
-    // MIN(attempts, 4) caps the shift to prevent overflow; the overall
-    // backoff is clamped to 480 000 ms via MIN(..., 480000).
     let changes = conn.execute(
         "UPDATE pending_dependent_fetches
          SET attempts = attempts + 1,
@@ -149,9 +125,6 @@ pub fn fail_job(conn: &Connection, job_id: i64, error: &str) -> Result<()> {
     Ok(())
 }
 
-/// Reclaim stale locks (locked_at older than threshold).
-///
-/// Returns count of reclaimed jobs.
 pub fn reclaim_stale_locks(conn: &Connection, stale_threshold_minutes: u32) -> Result<usize> {
     let threshold_ms = now_ms() - (i64::from(stale_threshold_minutes) * 60 * 1000);
 
@@ -163,7 +136,6 @@ pub fn reclaim_stale_locks(conn: &Connection, stale_threshold_minutes: u32) -> R
     Ok(changes)
 }
 
-/// Count pending jobs by job_type, optionally scoped to a project.
 pub fn count_pending_jobs(
     conn: &Connection,
     project_id: Option<i64>,
@@ -205,11 +177,6 @@ pub fn count_pending_jobs(
     Ok(counts)
 }
 
-/// Count jobs that are actually claimable right now, by job_type.
-///
-/// Only counts jobs where `locked_at IS NULL` and `(next_retry_at IS NULL OR next_retry_at <= now)`,
-/// matching the exact WHERE clause used by [`claim_jobs`]. This gives an accurate total
-/// for progress bars — unlike [`count_pending_jobs`] which includes locked and backing-off jobs.
 pub fn count_claimable_jobs(conn: &Connection, project_id: i64) -> Result<HashMap<String, usize>> {
     let now = now_ms();
     let mut counts = HashMap::new();
diff --git a/src/core/error.rs b/src/core/error.rs
index f80d580..7feb524 100644
--- a/src/core/error.rs
+++ b/src/core/error.rs
@@ -1,11 +1,6 @@
-//! Custom error types for gitlore.
-//!
-//! Uses thiserror for ergonomic error definitions with structured error codes.
-
 use serde::Serialize;
 use thiserror::Error;
 
-/// Error codes for programmatic error handling.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ErrorCode {
     ConfigNotFound,
@@ -55,7 +50,6 @@ impl std::fmt::Display for ErrorCode {
 }
 
 impl ErrorCode {
-    /// Get the exit code for this error (for robot mode).
     pub fn exit_code(&self) -> i32 {
         match self {
             Self::InternalError => 1,
@@ -80,7 +74,6 @@ impl ErrorCode {
     }
 }
 
-/// Main error type for gitlore.
 #[derive(Error, Debug)]
 pub enum LoreError {
     #[error("Config file not found at {path}. Run \"lore init\" first.")]
@@ -163,7 +156,6 @@ pub enum LoreError {
 }
 
 impl LoreError {
-    /// Get the error code for programmatic handling.
     pub fn code(&self) -> ErrorCode {
         match self {
             Self::ConfigNotFound { .. } => ErrorCode::ConfigNotFound,
@@ -190,7 +182,6 @@ impl LoreError {
         }
     }
 
-    /// Get a suggestion for how to fix this error, including inline examples.
     pub fn suggestion(&self) -> Option<&'static str> {
         match self {
             Self::ConfigNotFound { .. } => Some(
@@ -240,21 +231,14 @@ impl LoreError {
         }
     }
 
-    /// Whether this error represents a permanent API failure that should not be retried.
-    ///
-    /// Only 404 (not found) is truly permanent: the resource doesn't exist and never will.
-    /// 403 and auth errors are NOT permanent — they may be environmental (VPN down,
-    /// token rotation, temporary restrictions) and should be retried with backoff.
     pub fn is_permanent_api_error(&self) -> bool {
         matches!(self, Self::GitLabNotFound { .. })
     }
 
-    /// Get the exit code for this error.
     pub fn exit_code(&self) -> i32 {
         self.code().exit_code()
     }
 
-    /// Convert to robot-mode JSON error output.
     pub fn to_robot_error(&self) -> RobotError {
         RobotError {
             code: self.code().to_string(),
@@ -264,7 +248,6 @@ impl LoreError {
     }
 }
 
-/// Structured error for robot mode JSON output.
 #[derive(Debug, Serialize)]
 pub struct RobotError {
     pub code: String,
@@ -273,7 +256,6 @@ pub struct RobotError {
     pub suggestion: Option<String>,
 }
 
-/// Wrapper for robot mode error output.
 #[derive(Debug, Serialize)]
 pub struct RobotErrorOutput {
     pub error: RobotError,
diff --git a/src/core/events_db.rs b/src/core/events_db.rs
index 7bf6480..58c0900 100644
--- a/src/core/events_db.rs
+++ b/src/core/events_db.rs
@@ -1,15 +1,9 @@
-//! Database upsert functions for resource events (state, label, milestone).
-
 use rusqlite::Connection;
 
 use super::error::{LoreError, Result};
 use super::time::iso_to_ms_strict;
 use crate::gitlab::types::{GitLabLabelEvent, GitLabMilestoneEvent, GitLabStateEvent};
 
-/// Upsert state events for an entity.
-///
-/// Uses INSERT OR REPLACE keyed on UNIQUE(gitlab_id, project_id).
-/// Caller is responsible for wrapping in a transaction if atomicity is needed.
 pub fn upsert_state_events(
     conn: &Connection,
     project_id: i64,
@@ -52,8 +46,6 @@ pub fn upsert_state_events(
     Ok(count)
 }
 
-/// Upsert label events for an entity.
-/// Caller is responsible for wrapping in a transaction if atomicity is needed.
 pub fn upsert_label_events(
     conn: &Connection,
     project_id: i64,
@@ -93,8 +85,6 @@ pub fn upsert_label_events(
     Ok(count)
 }
 
-/// Upsert milestone events for an entity.
-/// Caller is responsible for wrapping in a transaction if atomicity is needed.
 pub fn upsert_milestone_events(
     conn: &Connection,
     project_id: i64,
@@ -135,8 +125,6 @@ pub fn upsert_milestone_events(
     Ok(count)
 }
 
-/// Resolve entity type string to (issue_id, merge_request_id) pair.
-/// Exactly one is Some, the other is None.
 fn resolve_entity_ids(
     entity_type: &str,
     entity_local_id: i64,
@@ -150,11 +138,9 @@ fn resolve_entity_ids(
     }
 }
 
-/// Count resource events by type for the count command.
 pub fn count_events(conn: &Connection) -> Result<EventCounts> {
     let mut counts = EventCounts::default();
 
-    // State events
     let row: (i64, i64) = conn
         .query_row(
             "SELECT
@@ -168,7 +154,6 @@ pub fn count_events(conn: &Connection) -> Result<EventCounts> {
     counts.state_issue = row.0 as usize;
     counts.state_mr = row.1 as usize;
 
-    // Label events
     let row: (i64, i64) = conn
         .query_row(
             "SELECT
@@ -182,7 +167,6 @@ pub fn count_events(conn: &Connection) -> Result<EventCounts> {
     counts.label_issue = row.0 as usize;
     counts.label_mr = row.1 as usize;
 
-    // Milestone events
     let row: (i64, i64) = conn
         .query_row(
             "SELECT
@@ -199,7 +183,6 @@ pub fn count_events(conn: &Connection) -> Result<EventCounts> {
     Ok(counts)
 }
 
-/// Event counts broken down by type and entity.
 #[derive(Debug, Default)]
 pub struct EventCounts {
     pub state_issue: usize,
diff --git a/src/core/lock.rs b/src/core/lock.rs
index edfc543..8abd886 100644
--- a/src/core/lock.rs
+++ b/src/core/lock.rs
@@ -1,7 +1,3 @@
-//! Crash-safe single-flight lock using heartbeat pattern.
-//!
-//! Prevents concurrent sync operations and allows recovery from crashed processes.
-
 use rusqlite::{Connection, TransactionBehavior};
 use std::path::PathBuf;
 use std::sync::Arc;
@@ -15,17 +11,14 @@ use super::db::create_connection;
 use super::error::{LoreError, Result};
 use super::time::{ms_to_iso, now_ms};
 
-/// Maximum consecutive heartbeat failures before signaling error.
 const MAX_HEARTBEAT_FAILURES: u32 = 3;
 
-/// Lock configuration options.
 pub struct LockOptions {
     pub name: String,
     pub stale_lock_minutes: u32,
     pub heartbeat_interval_seconds: u32,
 }
 
-/// App lock with heartbeat for crash recovery.
 pub struct AppLock {
     conn: Connection,
     db_path: PathBuf,
@@ -40,7 +33,6 @@ pub struct AppLock {
 }
 
 impl AppLock {
-    /// Create a new app lock instance.
     pub fn new(conn: Connection, options: LockOptions) -> Self {
         let db_path = conn.path().map(PathBuf::from).unwrap_or_default();
 
@@ -58,23 +50,17 @@ impl AppLock {
         }
     }
 
-    /// Check if heartbeat has failed (indicates lock may be compromised).
     pub fn is_heartbeat_healthy(&self) -> bool {
         !self.heartbeat_failed.load(Ordering::SeqCst)
     }
 
-    /// Attempt to acquire the lock atomically.
-    ///
-    /// Returns Ok(true) if lock acquired, Err if lock is held by another active process.
     pub fn acquire(&mut self, force: bool) -> Result<bool> {
         let now = now_ms();
 
-        // Use IMMEDIATE transaction to prevent race conditions
         let tx = self
             .conn
             .transaction_with_behavior(TransactionBehavior::Immediate)?;
 
-        // Check for existing lock within the transaction
         let existing: Option<(String, i64, i64)> = tx
             .query_row(
                 "SELECT owner, acquired_at, heartbeat_at FROM app_locks WHERE name = ?",
@@ -85,7 +71,6 @@ impl AppLock {
 
         match existing {
             None => {
-                // No lock exists, acquire it
                 tx.execute(
                     "INSERT INTO app_locks (name, owner, acquired_at, heartbeat_at) VALUES (?, ?, ?, ?)",
                     (&self.name, &self.owner, now, now),
@@ -96,7 +81,6 @@ impl AppLock {
                 let is_stale = now - heartbeat_at > self.stale_lock_ms;
 
                 if is_stale || force {
-                    // Lock is stale or force override, take it
                     tx.execute(
                         "UPDATE app_locks SET owner = ?, acquired_at = ?, heartbeat_at = ? WHERE name = ?",
                         (&self.owner, now, now, &self.name),
@@ -108,13 +92,11 @@ impl AppLock {
                         "Lock acquired (override)"
                     );
                 } else if existing_owner == self.owner {
-                    // Re-entrant, update heartbeat
                     tx.execute(
                         "UPDATE app_locks SET heartbeat_at = ? WHERE name = ?",
                         (now, &self.name),
                     )?;
                 } else {
-                    // Lock held by another active process - rollback and return error
                     drop(tx);
                     return Err(LoreError::DatabaseLocked {
                         owner: existing_owner,
@@ -124,20 +106,17 @@ impl AppLock {
             }
         }
 
-        // Commit the transaction atomically
         tx.commit()?;
 
         self.start_heartbeat();
         Ok(true)
     }
 
-    /// Release the lock.
     pub fn release(&mut self) {
         if self.released.swap(true, Ordering::SeqCst) {
-            return; // Already released
+            return;
         }
 
-        // Stop heartbeat thread
         if let Some(handle) = self.heartbeat_handle.take() {
             let _ = handle.join();
         }
@@ -150,7 +129,6 @@ impl AppLock {
         info!(owner = %self.owner, "Lock released");
     }
 
-    /// Start the heartbeat thread to keep the lock alive.
     fn start_heartbeat(&mut self) {
         let name = self.name.clone();
         let owner = self.owner.clone();
@@ -161,11 +139,10 @@ impl AppLock {
         let db_path = self.db_path.clone();
 
         if db_path.as_os_str().is_empty() {
-            return; // In-memory database, skip heartbeat
+            return;
         }
 
         self.heartbeat_handle = Some(thread::spawn(move || {
-            // Open a new connection with proper pragmas
             let conn = match create_connection(&db_path) {
                 Ok(c) => c,
                 Err(e) => {
@@ -175,11 +152,9 @@ impl AppLock {
                 }
             };
 
-            // Poll frequently for early exit, but only update heartbeat at full interval
             const POLL_INTERVAL: Duration = Duration::from_millis(100);
 
             loop {
-                // Sleep in small increments, checking released flag frequently
                 let mut elapsed = Duration::ZERO;
                 while elapsed < interval {
                     thread::sleep(POLL_INTERVAL);
@@ -189,7 +164,6 @@ impl AppLock {
                     }
                 }
 
-                // Check once more after full interval elapsed
                 if released.load(Ordering::SeqCst) {
                     break;
                 }
@@ -203,12 +177,10 @@ impl AppLock {
                 match result {
                     Ok(rows_affected) => {
                         if rows_affected == 0 {
-                            // Lock was stolen or deleted
                             warn!(owner = %owner, "Heartbeat failed: lock no longer held");
                             heartbeat_failed.store(true, Ordering::SeqCst);
                             break;
                         }
-                        // Reset failure count on success
                         failure_count.store(0, Ordering::SeqCst);
                         debug!(owner = %owner, "Heartbeat updated");
                     }
diff --git a/src/core/logging.rs b/src/core/logging.rs
index a34d724..0759430 100644
--- a/src/core/logging.rs
+++ b/src/core/logging.rs
@@ -1,29 +1,13 @@
-//! Logging infrastructure: dual-layer subscriber setup and log file retention.
-//!
-//! Provides a layered tracing subscriber with:
-//! - **stderr layer**: Human-readable or JSON format, controlled by `-v` flags
-//! - **file layer**: Always-on JSON output to daily-rotated log files
-
 use std::fs;
 use std::path::Path;
 
 use tracing_subscriber::EnvFilter;
 
-/// Build an `EnvFilter` from the verbosity count.
-///
-/// | Count | App Level | Dep Level |
-/// |-------|-----------|-----------|
-/// |   0   |   INFO    |   WARN    |
-/// |   1   |   DEBUG   |   WARN    |
-/// |   2   |   DEBUG   |   INFO    |
-/// |   3+  |   TRACE   |   DEBUG   |
 pub fn build_stderr_filter(verbose: u8, quiet: bool) -> EnvFilter {
-    // RUST_LOG always wins if set
     if std::env::var("RUST_LOG").is_ok() {
         return EnvFilter::from_default_env();
     }
 
-    // -q overrides -v for stderr
     if quiet {
         return EnvFilter::new("lore=warn,error");
     }
@@ -38,10 +22,6 @@ pub fn build_stderr_filter(verbose: u8, quiet: bool) -> EnvFilter {
     EnvFilter::new(directives)
 }
 
-/// Build an `EnvFilter` for the file layer.
-///
-/// Always captures DEBUG+ for `lore::*` and WARN+ for dependencies,
-/// unless `RUST_LOG` is set (which overrides everything).
 pub fn build_file_filter() -> EnvFilter {
     if std::env::var("RUST_LOG").is_ok() {
         return EnvFilter::from_default_env();
@@ -50,10 +30,6 @@ pub fn build_file_filter() -> EnvFilter {
     EnvFilter::new("lore=debug,warn")
 }
 
-/// Delete log files older than `retention_days` from the given directory.
-///
-/// Only deletes files matching the `lore.YYYY-MM-DD.log` pattern.
-/// Returns the number of files deleted.
 pub fn cleanup_old_logs(log_dir: &Path, retention_days: u32) -> usize {
     if retention_days == 0 || !log_dir.exists() {
         return 0;
@@ -72,7 +48,6 @@ pub fn cleanup_old_logs(log_dir: &Path, retention_days: u32) -> usize {
         let file_name = entry.file_name();
         let name = file_name.to_string_lossy();
 
-        // Match pattern: lore.YYYY-MM-DD.log or lore.YYYY-MM-DD (tracing-appender format)
         if let Some(date_str) = extract_log_date(&name)
             && date_str < cutoff_date
             && fs::remove_file(entry.path()).is_ok()
@@ -84,28 +59,20 @@ pub fn cleanup_old_logs(log_dir: &Path, retention_days: u32) -> usize {
     deleted
 }
 
-/// Extract the date portion from a log filename.
-///
-/// Matches: `lore.YYYY-MM-DD.log` or `lore.YYYY-MM-DD`
 fn extract_log_date(filename: &str) -> Option<String> {
     let rest = filename.strip_prefix("lore.")?;
 
-    // Must have at least YYYY-MM-DD (10 ASCII chars).
-    // Use get() to avoid panicking on non-ASCII filenames.
     let date_part = rest.get(..10)?;
 
-    // Validate it looks like a date
     let parts: Vec<&str> = date_part.split('-').collect();
     if parts.len() != 3 || parts[0].len() != 4 || parts[1].len() != 2 || parts[2].len() != 2 {
         return None;
     }
 
-    // Check all parts are numeric (also ensures ASCII)
     if !parts.iter().all(|p| p.chars().all(|c| c.is_ascii_digit())) {
         return None;
     }
 
-    // After the date, must be end-of-string or ".log"
     let suffix = rest.get(10..)?;
     if suffix.is_empty() || suffix == ".log" {
         Some(date_part.to_string())
@@ -153,16 +120,13 @@ mod tests {
     fn test_cleanup_old_logs_deletes_old_files() {
         let dir = TempDir::new().unwrap();
 
-        // Create old log files (well before any reasonable retention)
         File::create(dir.path().join("lore.2020-01-01.log")).unwrap();
         File::create(dir.path().join("lore.2020-01-15.log")).unwrap();
 
-        // Create a recent log file (today)
         let today = chrono::Utc::now().format("%Y-%m-%d").to_string();
         let recent_name = format!("lore.{today}.log");
         File::create(dir.path().join(&recent_name)).unwrap();
 
-        // Create a non-log file that should NOT be deleted
         File::create(dir.path().join("other.txt")).unwrap();
 
         let deleted = cleanup_old_logs(dir.path(), 7);
@@ -192,7 +156,6 @@ mod tests {
 
     #[test]
     fn test_build_stderr_filter_default() {
-        // Can't easily assert filter contents, but verify it doesn't panic
         let _filter = build_stderr_filter(0, false);
     }
 
@@ -206,7 +169,6 @@ mod tests {
 
     #[test]
     fn test_build_stderr_filter_quiet_overrides_verbose() {
-        // Quiet should win over verbose
         let _filter = build_stderr_filter(3, true);
     }
 
diff --git a/src/core/metrics.rs b/src/core/metrics.rs
index 3430596..b3eb2fb 100644
--- a/src/core/metrics.rs
+++ b/src/core/metrics.rs
@@ -1,9 +1,3 @@
-//! Performance metrics types and tracing layer for sync pipeline observability.
-//!
-//! Provides:
-//! - [`StageTiming`]: Serializable timing/counter data for pipeline stages
-//! - [`MetricsLayer`]: Custom tracing subscriber layer that captures span timing
-
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
 use std::time::Instant;
@@ -14,16 +8,10 @@ use tracing::span::{Attributes, Id, Record};
 use tracing_subscriber::layer::{Context, Layer};
 use tracing_subscriber::registry::LookupSpan;
 
-/// Returns true when value is zero (for serde `skip_serializing_if`).
 fn is_zero(v: &usize) -> bool {
     *v == 0
 }
 
-/// Timing and counter data for a single pipeline stage.
-///
-/// Supports nested sub-stages for hierarchical timing breakdowns.
-/// Fields with zero/empty values are omitted from JSON output to
-/// keep robot-mode payloads compact.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct StageTiming {
     pub name: String,
@@ -43,11 +31,6 @@ pub struct StageTiming {
     pub sub_stages: Vec<StageTiming>,
 }
 
-// ============================================================================
-// MetricsLayer: custom tracing subscriber layer
-// ============================================================================
-
-/// Internal data tracked per open span.
 struct SpanData {
     name: String,
     parent_id: Option<u64>,
@@ -57,19 +40,12 @@ struct SpanData {
     retries: usize,
 }
 
-/// Completed span data with its original ID and parent ID.
 struct CompletedSpan {
     id: u64,
     parent_id: Option<u64>,
     timing: StageTiming,
 }
 
-/// Custom tracing layer that captures span timing and structured fields.
-///
-/// Collects data from `#[instrument]` spans and materializes it into
-/// a `Vec<StageTiming>` tree via [`extract_timings`].
-///
-/// Thread-safe via `Arc<Mutex<>>` — suitable for concurrent span operations.
 #[derive(Debug, Clone)]
 pub struct MetricsLayer {
     spans: Arc<Mutex<HashMap<u64, SpanData>>>,
@@ -90,45 +66,34 @@ impl MetricsLayer {
         }
     }
 
-    /// Extract timing tree for a completed run.
-    ///
-    /// Returns the top-level stages with sub-stages nested.
-    /// Call after the root span closes.
     pub fn extract_timings(&self) -> Vec<StageTiming> {
         let completed = self.completed.lock().unwrap_or_else(|e| e.into_inner());
         if completed.is_empty() {
             return Vec::new();
         }
 
-        // Build children map: parent_id -> Vec<StageTiming>
         let mut children_map: HashMap<u64, Vec<StageTiming>> = HashMap::new();
         let mut roots = Vec::new();
         let mut id_to_timing: HashMap<u64, StageTiming> = HashMap::new();
 
-        // First pass: collect all timings by ID
         for entry in completed.iter() {
             id_to_timing.insert(entry.id, entry.timing.clone());
         }
 
-        // Second pass: process in reverse order (children close before parents)
-        // to build the tree bottom-up
         for entry in completed.iter() {
-            // Attach any children that were collected for this span
             if let Some(timing) = id_to_timing.get_mut(&entry.id)
                 && let Some(children) = children_map.remove(&entry.id)
             {
                 timing.sub_stages = children;
             }
 
-            if let Some(parent_id) = entry.parent_id {
-                // This is a child span — attach to parent's children
-                if let Some(timing) = id_to_timing.remove(&entry.id) {
-                    children_map.entry(parent_id).or_default().push(timing);
-                }
+            if let Some(parent_id) = entry.parent_id
+                && let Some(timing) = id_to_timing.remove(&entry.id)
+            {
+                children_map.entry(parent_id).or_default().push(timing);
             }
         }
 
-        // Remaining entries in id_to_timing are roots
         for entry in completed.iter() {
             if entry.parent_id.is_none()
                 && let Some(mut timing) = id_to_timing.remove(&entry.id)
@@ -144,7 +109,6 @@ impl MetricsLayer {
     }
 }
 
-/// Visitor that extracts field values from span attributes.
 struct FieldVisitor<'a>(&'a mut HashMap<String, serde_json::Value>);
 
 impl tracing::field::Visit for FieldVisitor<'_> {
@@ -182,7 +146,6 @@ impl tracing::field::Visit for FieldVisitor<'_> {
     }
 }
 
-/// Visitor that extracts event fields for rate-limit/retry detection.
 #[derive(Default)]
 struct EventVisitor {
     status_code: Option<u64>,
@@ -248,7 +211,6 @@ where
     }
 
     fn on_event(&self, event: &tracing::Event<'_>, ctx: Context<'_, S>) {
-        // Count rate-limit and retry events on the current span
         if let Some(span_ref) = ctx.event_span(event) {
             let id = span_ref.id();
             if let Some(data) = self
@@ -317,7 +279,6 @@ where
     }
 }
 
-// Manual Debug impl since SpanData and CompletedSpan don't derive Debug
 impl std::fmt::Debug for SpanData {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("SpanData")
@@ -376,7 +337,6 @@ mod tests {
         assert_eq!(json["rate_limit_hits"], 2);
         assert_eq!(json["retries"], 5);
 
-        // Sub-stage present
         let sub = &json["sub_stages"][0];
         assert_eq!(sub["name"], "ingest_issues");
         assert_eq!(sub["project"], "group/repo");
@@ -400,7 +360,6 @@ mod tests {
         let json = serde_json::to_value(&timing).unwrap();
         let obj = json.as_object().unwrap();
 
-        // Zero fields must be absent
         assert!(!obj.contains_key("items_skipped"));
         assert!(!obj.contains_key("errors"));
         assert!(!obj.contains_key("rate_limit_hits"));
@@ -408,7 +367,6 @@ mod tests {
         assert!(!obj.contains_key("sub_stages"));
         assert!(!obj.contains_key("project"));
 
-        // Required fields always present
         assert!(obj.contains_key("name"));
         assert!(obj.contains_key("elapsed_ms"));
         assert!(obj.contains_key("items_processed"));
@@ -539,13 +497,12 @@ mod tests {
         tracing::subscriber::with_default(subscriber, || {
             let span = tracing::info_span!("test_stage");
             let _guard = span.enter();
-            // Simulate work
         });
 
         let timings = metrics.extract_timings();
         assert_eq!(timings.len(), 1);
         assert_eq!(timings[0].name, "test_stage");
-        assert!(timings[0].elapsed_ms < 100); // Should be near-instant
+        assert!(timings[0].elapsed_ms < 100);
     }
 
     #[test]
diff --git a/src/core/paths.rs b/src/core/paths.rs
index a3a3a04..7c25591 100644
--- a/src/core/paths.rs
+++ b/src/core/paths.rs
@@ -1,50 +1,31 @@
-//! XDG-compliant path resolution for config and data directories.
-
 use std::path::PathBuf;
 
-/// Get the path to the config file.
-///
-/// Resolution order:
-/// 1. CLI flag override (if provided)
-/// 2. LORE_CONFIG_PATH environment variable
-/// 3. XDG default (~/.config/lore/config.json)
-/// 4. Local fallback (./lore.config.json) if exists
-/// 5. Returns XDG default even if not exists
 pub fn get_config_path(cli_override: Option<&str>) -> PathBuf {
-    // 1. CLI flag override
     if let Some(path) = cli_override {
         return PathBuf::from(path);
     }
 
-    // 2. Environment variable
     if let Ok(path) = std::env::var("LORE_CONFIG_PATH") {
         return PathBuf::from(path);
     }
 
-    // 3. XDG default
     let xdg_path = get_xdg_config_dir().join("lore").join("config.json");
     if xdg_path.exists() {
         return xdg_path;
     }
 
-    // 4. Local fallback (for development)
     let local_path = PathBuf::from("lore.config.json");
     if local_path.exists() {
         return local_path;
     }
 
-    // 5. Return XDG path (will trigger not-found error if missing)
     xdg_path
 }
 
-/// Get the data directory path.
-/// Uses XDG_DATA_HOME or defaults to ~/.local/share/lore
 pub fn get_data_dir() -> PathBuf {
     get_xdg_data_dir().join("lore")
 }
 
-/// Get the database file path.
-/// Uses config override if provided, otherwise uses default in data dir.
 pub fn get_db_path(config_override: Option<&str>) -> PathBuf {
     if let Some(path) = config_override {
         return PathBuf::from(path);
@@ -52,8 +33,6 @@ pub fn get_db_path(config_override: Option<&str>) -> PathBuf {
     get_data_dir().join("lore.db")
 }
 
-/// Get the log directory path.
-/// Uses config override if provided, otherwise uses default in data dir.
 pub fn get_log_dir(config_override: Option<&str>) -> PathBuf {
     if let Some(path) = config_override {
         return PathBuf::from(path);
@@ -61,8 +40,6 @@ pub fn get_log_dir(config_override: Option<&str>) -> PathBuf {
     get_data_dir().join("logs")
 }
 
-/// Get the backup directory path.
-/// Uses config override if provided, otherwise uses default in data dir.
 pub fn get_backup_dir(config_override: Option<&str>) -> PathBuf {
     if let Some(path) = config_override {
         return PathBuf::from(path);
@@ -70,7 +47,6 @@ pub fn get_backup_dir(config_override: Option<&str>) -> PathBuf {
     get_data_dir().join("backups")
 }
 
-/// Get XDG config directory, falling back to ~/.config
 fn get_xdg_config_dir() -> PathBuf {
     std::env::var("XDG_CONFIG_HOME")
         .map(PathBuf::from)
@@ -81,7 +57,6 @@ fn get_xdg_config_dir() -> PathBuf {
         })
 }
 
-/// Get XDG data directory, falling back to ~/.local/share
 fn get_xdg_data_dir() -> PathBuf {
     std::env::var("XDG_DATA_HOME")
         .map(PathBuf::from)
@@ -102,8 +77,4 @@ mod tests {
         let path = get_config_path(Some("/custom/path.json"));
         assert_eq!(path, PathBuf::from("/custom/path.json"));
     }
-
-    // Note: env var tests removed - mutating process-global env vars
-    // in parallel tests is unsafe in Rust 2024. The env var code path
-    // is trivial (std::env::var) and doesn't warrant the complexity.
 }
diff --git a/src/core/payloads.rs b/src/core/payloads.rs
index bc0e1cd..5012360 100644
--- a/src/core/payloads.rs
+++ b/src/core/payloads.rs
@@ -1,5 +1,3 @@
-//! Raw payload storage with optional compression and deduplication.
-
 use flate2::Compression;
 use flate2::read::GzDecoder;
 use flate2::write::GzEncoder;
@@ -10,26 +8,21 @@ use std::io::{Read, Write};
 use super::error::Result;
 use super::time::now_ms;
 
-/// Options for storing a payload.
 pub struct StorePayloadOptions<'a> {
     pub project_id: Option<i64>,
-    pub resource_type: &'a str, // 'project' | 'issue' | 'mr' | 'note' | 'discussion'
-    pub gitlab_id: &'a str,     // TEXT because discussion IDs are strings
+    pub resource_type: &'a str,
+    pub gitlab_id: &'a str,
     pub json_bytes: &'a [u8],
     pub compress: bool,
 }
 
-/// Store a raw API payload with optional compression and deduplication.
-/// Returns the row ID (either new or existing if duplicate).
 pub fn store_payload(conn: &Connection, options: StorePayloadOptions) -> Result<i64> {
     let json_bytes = options.json_bytes;
 
-    // 2. SHA-256 hash the JSON bytes (pre-compression)
     let mut hasher = Sha256::new();
     hasher.update(json_bytes);
     let payload_hash = format!("{:x}", hasher.finalize());
 
-    // 3. Check for duplicate by (project_id, resource_type, gitlab_id, payload_hash)
     let existing: Option<i64> = conn
         .query_row(
             "SELECT id FROM raw_payloads
@@ -44,12 +37,10 @@ pub fn store_payload(conn: &Connection, options: StorePayloadOptions) -> Result<
         )
         .ok();
 
-    // 4. If duplicate, return existing ID
     if let Some(id) = existing {
         return Ok(id);
     }
 
-    // 5. Compress if requested
     let (encoding, payload_bytes): (&str, std::borrow::Cow<'_, [u8]>) = if options.compress {
         let mut encoder = GzEncoder::new(Vec::new(), Compression::default());
         encoder.write_all(json_bytes)?;
@@ -58,7 +49,6 @@ pub fn store_payload(conn: &Connection, options: StorePayloadOptions) -> Result<
         ("identity", std::borrow::Cow::Borrowed(json_bytes))
     };
 
-    // 6. INSERT with content_encoding
     conn.execute(
         "INSERT INTO raw_payloads
          (source, project_id, resource_type, gitlab_id, fetched_at, content_encoding, payload_hash, payload)
@@ -77,8 +67,6 @@ pub fn store_payload(conn: &Connection, options: StorePayloadOptions) -> Result<
     Ok(conn.last_insert_rowid())
 }
 
-/// Read a raw payload by ID, decompressing if necessary.
-/// Returns None if not found.
 pub fn read_payload(conn: &Connection, id: i64) -> Result<Option<serde_json::Value>> {
     let row: Option<(String, Vec<u8>)> = conn
         .query_row(
@@ -92,7 +80,6 @@ pub fn read_payload(conn: &Connection, id: i64) -> Result<Option<serde_json::Val
         return Ok(None);
     };
 
-    // Decompress if needed
     let json_bytes = if encoding == "gzip" {
         let mut decoder = GzDecoder::new(&payload_bytes[..]);
         let mut decompressed = Vec::new();
@@ -117,7 +104,6 @@ mod tests {
         let db_path = dir.path().join("test.db");
         let conn = create_connection(&db_path).unwrap();
 
-        // Create minimal schema for testing
         conn.execute_batch(
             "CREATE TABLE raw_payloads (
                 id INTEGER PRIMARY KEY,
@@ -212,6 +198,6 @@ mod tests {
         )
         .unwrap();
 
-        assert_eq!(id1, id2); // Same payload returns same ID
+        assert_eq!(id1, id2);
     }
 }
diff --git a/src/core/project.rs b/src/core/project.rs
index 828693f..c6f2722 100644
--- a/src/core/project.rs
+++ b/src/core/project.rs
@@ -2,14 +2,7 @@ use rusqlite::Connection;
 
 use super::error::{LoreError, Result};
 
-/// Resolve a project string to a project_id using cascading match:
-/// 1. Exact match on path_with_namespace
-/// 2. Case-insensitive exact match
-/// 3. Suffix match (e.g., "auth-service" matches "group/auth-service") — only if unambiguous
-/// 4. Substring match (e.g., "typescript" matches "vs/typescript-code") — only if unambiguous
-/// 5. Error with available projects list
 pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
-    // Step 1: Exact match
     let exact = conn.query_row(
         "SELECT id FROM projects WHERE path_with_namespace = ?1",
         rusqlite::params![project_str],
@@ -19,7 +12,6 @@ pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
         return Ok(id);
     }
 
-    // Step 2: Case-insensitive exact match
     let ci = conn.query_row(
         "SELECT id FROM projects WHERE LOWER(path_with_namespace) = LOWER(?1)",
         rusqlite::params![project_str],
@@ -29,7 +21,6 @@ pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
         return Ok(id);
     }
 
-    // Step 3: Suffix match (unambiguous)
     let mut suffix_stmt = conn.prepare(
         "SELECT id, path_with_namespace FROM projects
          WHERE path_with_namespace LIKE '%/' || ?1
@@ -59,7 +50,6 @@ pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
         _ => {}
     }
 
-    // Step 4: Case-insensitive substring match (unambiguous)
     let mut substr_stmt = conn.prepare(
         "SELECT id, path_with_namespace FROM projects
          WHERE LOWER(path_with_namespace) LIKE '%' || LOWER(?1) || '%'",
@@ -88,7 +78,6 @@ pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
         _ => {}
     }
 
-    // Step 5: No match — list available projects
     let mut all_stmt =
         conn.prepare("SELECT path_with_namespace FROM projects ORDER BY path_with_namespace")?;
     let all_projects: Vec<String> = all_stmt
@@ -211,7 +200,6 @@ mod tests {
         let conn = setup_db();
         insert_project(&conn, 1, "vs/python-code");
         insert_project(&conn, 2, "vs/typescript-code");
-        // "code" matches both projects
         let err = resolve_project(&conn, "code").unwrap_err();
         let msg = err.to_string();
         assert!(
@@ -225,11 +213,9 @@ mod tests {
 
     #[test]
     fn test_suffix_preferred_over_substring() {
-        // Suffix match (step 3) should resolve before substring (step 4)
         let conn = setup_db();
         insert_project(&conn, 1, "backend/auth-service");
         insert_project(&conn, 2, "backend/auth-service-v2");
-        // "auth-service" is an exact suffix of project 1
         let id = resolve_project(&conn, "auth-service").unwrap();
         assert_eq!(id, 1);
     }
diff --git a/src/core/sync_run.rs b/src/core/sync_run.rs
index 53442dd..326fb4d 100644
--- a/src/core/sync_run.rs
+++ b/src/core/sync_run.rs
@@ -1,25 +1,14 @@
-//! Sync run lifecycle recorder.
-//!
-//! Encapsulates the INSERT-on-start, UPDATE-on-finish lifecycle for the
-//! `sync_runs` table, enabling sync history tracking and observability.
-
 use rusqlite::Connection;
 
 use super::error::Result;
 use super::metrics::StageTiming;
 use super::time::now_ms;
 
-/// Records a single sync run's lifecycle in the `sync_runs` table.
-///
-/// Created via [`start`](Self::start), then finalized with either
-/// [`succeed`](Self::succeed) or [`fail`](Self::fail). Both finalizers
-/// consume `self` to enforce single-use at compile time.
 pub struct SyncRunRecorder {
     row_id: i64,
 }
 
 impl SyncRunRecorder {
-    /// Insert a new `sync_runs` row with `status='running'`.
     pub fn start(conn: &Connection, command: &str, run_id: &str) -> Result<Self> {
         let now = now_ms();
         conn.execute(
@@ -31,7 +20,6 @@ impl SyncRunRecorder {
         Ok(Self { row_id })
     }
 
-    /// Mark run as succeeded with full metrics.
     pub fn succeed(
         self,
         conn: &Connection,
@@ -57,7 +45,6 @@ impl SyncRunRecorder {
         Ok(())
     }
 
-    /// Mark run as failed with error message and optional partial metrics.
     pub fn fail(
         self,
         conn: &Connection,
@@ -158,7 +145,6 @@ mod tests {
         assert_eq!(total_items, 50);
         assert_eq!(total_errors, 2);
 
-        // Verify metrics_json is parseable
         let parsed: Vec<StageTiming> = serde_json::from_str(&metrics_json.unwrap()).unwrap();
         assert_eq!(parsed.len(), 1);
         assert_eq!(parsed[0].name, "ingest");
diff --git a/src/core/time.rs b/src/core/time.rs
index 9f59601..bb37d2f 100644
--- a/src/core/time.rs
+++ b/src/core/time.rs
@@ -1,39 +1,24 @@
-//! Time utilities for consistent timestamp handling.
-//!
-//! All database *_at columns use milliseconds since epoch for consistency.
-
 use chrono::{DateTime, Utc};
 
-/// Convert GitLab API ISO 8601 timestamp to milliseconds since epoch.
 pub fn iso_to_ms(iso_string: &str) -> Option<i64> {
     DateTime::parse_from_rfc3339(iso_string)
         .ok()
         .map(|dt| dt.timestamp_millis())
 }
 
-/// Convert milliseconds since epoch to ISO 8601 string.
 pub fn ms_to_iso(ms: i64) -> String {
     DateTime::from_timestamp_millis(ms)
         .map(|dt| dt.to_rfc3339())
         .unwrap_or_else(|| "Invalid timestamp".to_string())
 }
 
-/// Get current time in milliseconds since epoch.
 pub fn now_ms() -> i64 {
     Utc::now().timestamp_millis()
 }
 
-/// Parse a relative time string (7d, 2w, 1m) or ISO date into ms epoch.
-///
-/// Returns the timestamp as of which to filter (cutoff point).
-/// - `7d` = 7 days ago
-/// - `2w` = 2 weeks ago
-/// - `1m` = 1 month ago (30 days)
-/// - `2024-01-15` = midnight UTC on that date
 pub fn parse_since(input: &str) -> Option<i64> {
     let input = input.trim();
 
-    // Try relative format: Nd, Nw, Nm
     if let Some(num_str) = input.strip_suffix('d') {
         let days: i64 = num_str.parse().ok()?;
         return Some(now_ms() - (days * 24 * 60 * 60 * 1000));
@@ -49,25 +34,20 @@ pub fn parse_since(input: &str) -> Option<i64> {
         return Some(now_ms() - (months * 30 * 24 * 60 * 60 * 1000));
     }
 
-    // Try ISO date: YYYY-MM-DD
     if input.len() == 10 && input.chars().filter(|&c| c == '-').count() == 2 {
         let iso_full = format!("{input}T00:00:00Z");
         return iso_to_ms(&iso_full);
     }
 
-    // Try full ISO 8601
     iso_to_ms(input)
 }
 
-/// Convert ISO 8601 timestamp to milliseconds with strict error handling.
-/// Returns Err with a descriptive message if the timestamp is invalid.
 pub fn iso_to_ms_strict(iso_string: &str) -> Result<i64, String> {
     DateTime::parse_from_rfc3339(iso_string)
         .map(|dt| dt.timestamp_millis())
         .map_err(|_| format!("Invalid timestamp: {}", iso_string))
 }
 
-/// Convert optional ISO 8601 timestamp to optional milliseconds (strict).
 pub fn iso_to_ms_opt_strict(iso_string: &Option<String>) -> Result<Option<i64>, String> {
     match iso_string {
         Some(s) => iso_to_ms_strict(s).map(Some),
@@ -75,7 +55,6 @@ pub fn iso_to_ms_opt_strict(iso_string: &Option<String>) -> Result<Option<i64>,
     }
 }
 
-/// Format milliseconds epoch to human-readable full datetime.
 pub fn format_full_datetime(ms: i64) -> String {
     DateTime::from_timestamp_millis(ms)
         .map(|dt| dt.format("%Y-%m-%d %H:%M UTC").to_string())
@@ -101,7 +80,7 @@ mod tests {
     #[test]
     fn test_now_ms() {
         let now = now_ms();
-        assert!(now > 1700000000000); // After 2023
+        assert!(now > 1700000000000);
     }
 
     #[test]
@@ -109,7 +88,7 @@ mod tests {
         let now = now_ms();
         let seven_days = parse_since("7d").unwrap();
         let expected = now - (7 * 24 * 60 * 60 * 1000);
-        assert!((seven_days - expected).abs() < 1000); // Within 1 second
+        assert!((seven_days - expected).abs() < 1000);
     }
 
     #[test]
@@ -132,7 +111,6 @@ mod tests {
     fn test_parse_since_iso_date() {
         let ms = parse_since("2024-01-15").unwrap();
         assert!(ms > 0);
-        // Should be midnight UTC on that date
         let expected = iso_to_ms("2024-01-15T00:00:00Z").unwrap();
         assert_eq!(ms, expected);
     }
diff --git a/src/documents/extractor.rs b/src/documents/extractor.rs
index bbeb03c..552db58 100644
--- a/src/documents/extractor.rs
+++ b/src/documents/extractor.rs
@@ -9,7 +9,6 @@ use super::truncation::{
 };
 use crate::core::error::Result;
 
-/// Source type for documents.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum SourceType {
@@ -27,10 +26,6 @@ impl SourceType {
         }
     }
 
-    /// Parse from CLI input, accepting common aliases.
-    ///
-    /// Accepts: "issue", "issues", "mr", "mrs", "merge_request", "merge_requests",
-    /// "discussion", "discussions"
     pub fn parse(s: &str) -> Option<Self> {
         match s.to_lowercase().as_str() {
             "issue" | "issues" => Some(Self::Issue),
@@ -47,7 +42,6 @@ impl std::fmt::Display for SourceType {
     }
 }
 
-/// Generated document ready for storage.
 #[derive(Debug, Clone)]
 pub struct DocumentData {
     pub source_type: SourceType,
@@ -68,16 +62,12 @@ pub struct DocumentData {
     pub truncated_reason: Option<String>,
 }
 
-/// Compute SHA-256 hash of content.
 pub fn compute_content_hash(content: &str) -> String {
     let mut hasher = Sha256::new();
     hasher.update(content.as_bytes());
     format!("{:x}", hasher.finalize())
 }
 
-/// Compute SHA-256 hash over a sorted list of strings.
-/// Used for labels_hash and paths_hash to detect changes efficiently.
-/// Sorts by index reference to avoid cloning, hashes incrementally to avoid join allocation.
 pub fn compute_list_hash(items: &[String]) -> String {
     let mut indices: Vec<usize> = (0..items.len()).collect();
     indices.sort_by(|a, b| items[*a].cmp(&items[*b]));
@@ -91,10 +81,7 @@ pub fn compute_list_hash(items: &[String]) -> String {
     format!("{:x}", hasher.finalize())
 }
 
-/// Extract a searchable document from an issue.
-/// Returns None if the issue has been deleted from the DB.
 pub fn extract_issue_document(conn: &Connection, issue_id: i64) -> Result<Option<DocumentData>> {
-    // Query main issue entity with project info
     let row = conn.query_row(
         "SELECT i.id, i.iid, i.title, i.description, i.state, i.author_username,
                 i.created_at, i.updated_at, i.web_url,
@@ -105,17 +92,17 @@ pub fn extract_issue_document(conn: &Connection, issue_id: i64) -> Result<Option
         rusqlite::params![issue_id],
         |row| {
             Ok((
-                row.get::<_, i64>(0)?,            // id
-                row.get::<_, i64>(1)?,            // iid
-                row.get::<_, Option<String>>(2)?, // title
-                row.get::<_, Option<String>>(3)?, // description
-                row.get::<_, String>(4)?,         // state
-                row.get::<_, Option<String>>(5)?, // author_username
-                row.get::<_, i64>(6)?,            // created_at
-                row.get::<_, i64>(7)?,            // updated_at
-                row.get::<_, Option<String>>(8)?, // web_url
-                row.get::<_, String>(9)?,         // path_with_namespace
-                row.get::<_, i64>(10)?,           // project_id
+                row.get::<_, i64>(0)?,
+                row.get::<_, i64>(1)?,
+                row.get::<_, Option<String>>(2)?,
+                row.get::<_, Option<String>>(3)?,
+                row.get::<_, String>(4)?,
+                row.get::<_, Option<String>>(5)?,
+                row.get::<_, i64>(6)?,
+                row.get::<_, i64>(7)?,
+                row.get::<_, Option<String>>(8)?,
+                row.get::<_, String>(9)?,
+                row.get::<_, i64>(10)?,
             ))
         },
     );
@@ -138,7 +125,6 @@ pub fn extract_issue_document(conn: &Connection, issue_id: i64) -> Result<Option
         Err(e) => return Err(e.into()),
     };
 
-    // Query labels via junction table
     let mut label_stmt = conn.prepare_cached(
         "SELECT l.name FROM issue_labels il
          JOIN labels l ON l.id = il.label_id
@@ -149,10 +135,8 @@ pub fn extract_issue_document(conn: &Connection, issue_id: i64) -> Result<Option
         .query_map(rusqlite::params![id], |row| row.get(0))?
         .collect::<std::result::Result<Vec<_>, _>>()?;
 
-    // Build labels JSON array string
     let labels_json = serde_json::to_string(&labels).unwrap_or_else(|_| "[]".to_string());
 
-    // Format content_text per PRD template
     let display_title = title.as_deref().unwrap_or("(untitled)");
     let mut content = format!(
         "[[Issue]] #{}: {}\nProject: {}\n",
@@ -167,16 +151,14 @@ pub fn extract_issue_document(conn: &Connection, issue_id: i64) -> Result<Option
         content.push_str(&format!("Author: @{}\n", author));
     }
 
-    // Add description section only if description is Some
     if let Some(ref desc) = description {
         content.push_str("\n--- Description ---\n\n");
         content.push_str(desc);
     }
 
     let labels_hash = compute_list_hash(&labels);
-    let paths_hash = compute_list_hash(&[]); // Issues have no paths
+    let paths_hash = compute_list_hash(&[]);
 
-    // Apply hard cap truncation for safety, then hash the final stored content
     let hard_cap = truncate_hard_cap(&content);
     let content_hash = compute_content_hash(&hard_cap.content);
 
@@ -200,8 +182,6 @@ pub fn extract_issue_document(conn: &Connection, issue_id: i64) -> Result<Option
     }))
 }
 
-/// Extract a searchable document from a merge request.
-/// Returns None if the MR has been deleted from the DB.
 pub fn extract_mr_document(conn: &Connection, mr_id: i64) -> Result<Option<DocumentData>> {
     let row = conn.query_row(
         "SELECT m.id, m.iid, m.title, m.description, m.state, m.author_username,
@@ -214,19 +194,19 @@ pub fn extract_mr_document(conn: &Connection, mr_id: i64) -> Result<Option<Docum
         rusqlite::params![mr_id],
         |row| {
             Ok((
-                row.get::<_, i64>(0)?,             // id
-                row.get::<_, i64>(1)?,             // iid
-                row.get::<_, Option<String>>(2)?,  // title
-                row.get::<_, Option<String>>(3)?,  // description
-                row.get::<_, Option<String>>(4)?,  // state
-                row.get::<_, Option<String>>(5)?,  // author_username
-                row.get::<_, Option<String>>(6)?,  // source_branch
-                row.get::<_, Option<String>>(7)?,  // target_branch
-                row.get::<_, Option<i64>>(8)?,     // created_at (nullable in schema)
-                row.get::<_, Option<i64>>(9)?,     // updated_at (nullable in schema)
-                row.get::<_, Option<String>>(10)?, // web_url
-                row.get::<_, String>(11)?,         // path_with_namespace
-                row.get::<_, i64>(12)?,            // project_id
+                row.get::<_, i64>(0)?,
+                row.get::<_, i64>(1)?,
+                row.get::<_, Option<String>>(2)?,
+                row.get::<_, Option<String>>(3)?,
+                row.get::<_, Option<String>>(4)?,
+                row.get::<_, Option<String>>(5)?,
+                row.get::<_, Option<String>>(6)?,
+                row.get::<_, Option<String>>(7)?,
+                row.get::<_, Option<i64>>(8)?,
+                row.get::<_, Option<i64>>(9)?,
+                row.get::<_, Option<String>>(10)?,
+                row.get::<_, String>(11)?,
+                row.get::<_, i64>(12)?,
             ))
         },
     );
@@ -251,7 +231,6 @@ pub fn extract_mr_document(conn: &Connection, mr_id: i64) -> Result<Option<Docum
         Err(e) => return Err(e.into()),
     };
 
-    // Query labels via junction table
     let mut label_stmt = conn.prepare_cached(
         "SELECT l.name FROM mr_labels ml
          JOIN labels l ON l.id = ml.label_id
@@ -278,7 +257,6 @@ pub fn extract_mr_document(conn: &Connection, mr_id: i64) -> Result<Option<Docum
     if let Some(ref author) = author_username {
         content.push_str(&format!("Author: @{}\n", author));
     }
-    // Source line: source_branch -> target_branch
     if let (Some(src), Some(tgt)) = (&source_branch, &target_branch) {
         content.push_str(&format!("Source: {} -> {}\n", src, tgt));
     }
@@ -291,7 +269,6 @@ pub fn extract_mr_document(conn: &Connection, mr_id: i64) -> Result<Option<Docum
     let labels_hash = compute_list_hash(&labels);
     let paths_hash = compute_list_hash(&[]);
 
-    // Apply hard cap truncation for safety, then hash the final stored content
     let hard_cap = truncate_hard_cap(&content);
     let content_hash = compute_content_hash(&hard_cap.content);
 
@@ -315,20 +292,16 @@ pub fn extract_mr_document(conn: &Connection, mr_id: i64) -> Result<Option<Docum
     }))
 }
 
-/// Format ms epoch as YYYY-MM-DD date string.
 fn format_date(ms: i64) -> String {
     DateTime::from_timestamp_millis(ms)
         .map(|dt| dt.format("%Y-%m-%d").to_string())
         .unwrap_or_else(|| "unknown".to_string())
 }
 
-/// Extract a searchable document from a discussion thread.
-/// Returns None if the discussion or its parent has been deleted.
 pub fn extract_discussion_document(
     conn: &Connection,
     discussion_id: i64,
 ) -> Result<Option<DocumentData>> {
-    // Query discussion metadata
     let disc_row = conn.query_row(
         "SELECT d.id, d.noteable_type, d.issue_id, d.merge_request_id,
                 p.path_with_namespace, p.id AS project_id
@@ -338,12 +311,12 @@ pub fn extract_discussion_document(
         rusqlite::params![discussion_id],
         |row| {
             Ok((
-                row.get::<_, i64>(0)?,         // id
-                row.get::<_, String>(1)?,      // noteable_type
-                row.get::<_, Option<i64>>(2)?, // issue_id
-                row.get::<_, Option<i64>>(3)?, // merge_request_id
-                row.get::<_, String>(4)?,      // path_with_namespace
-                row.get::<_, i64>(5)?,         // project_id
+                row.get::<_, i64>(0)?,
+                row.get::<_, String>(1)?,
+                row.get::<_, Option<i64>>(2)?,
+                row.get::<_, Option<i64>>(3)?,
+                row.get::<_, String>(4)?,
+                row.get::<_, i64>(5)?,
             ))
         },
     );
@@ -355,7 +328,6 @@ pub fn extract_discussion_document(
             Err(e) => return Err(e.into()),
         };
 
-    // Query parent entity
     let (_parent_iid, parent_title, parent_web_url, parent_type_prefix, labels) =
         match noteable_type.as_str() {
             "Issue" => {
@@ -379,7 +351,6 @@ pub fn extract_discussion_document(
                     Err(rusqlite::Error::QueryReturnedNoRows) => return Ok(None),
                     Err(e) => return Err(e.into()),
                 };
-                // Query parent labels
                 let mut label_stmt = conn.prepare_cached(
                     "SELECT l.name FROM issue_labels il
                      JOIN labels l ON l.id = il.label_id
@@ -413,7 +384,6 @@ pub fn extract_discussion_document(
                     Err(rusqlite::Error::QueryReturnedNoRows) => return Ok(None),
                     Err(e) => return Err(e.into()),
                 };
-                // Query parent labels
                 let mut label_stmt = conn.prepare_cached(
                     "SELECT l.name FROM mr_labels ml
                      JOIN labels l ON l.id = ml.label_id
@@ -429,7 +399,6 @@ pub fn extract_discussion_document(
             _ => return Ok(None),
         };
 
-    // Query non-system notes in thread order
     let mut note_stmt = conn.prepare_cached(
         "SELECT n.author_username, n.body, n.created_at, n.gitlab_id,
                 n.note_type, n.position_old_path, n.position_new_path
@@ -454,7 +423,6 @@ pub fn extract_discussion_document(
                 body: row.get(1)?,
                 created_at: row.get(2)?,
                 gitlab_id: row.get(3)?,
-                // index 4 is note_type (unused here)
                 old_path: row.get(5)?,
                 new_path: row.get(6)?,
             })
@@ -465,7 +433,6 @@ pub fn extract_discussion_document(
         return Ok(None);
     }
 
-    // Extract DiffNote paths (deduplicated, sorted)
     let mut path_set = BTreeSet::new();
     for note in &notes {
         if let Some(ref p) = note.old_path
@@ -481,16 +448,13 @@ pub fn extract_discussion_document(
     }
     let paths: Vec<String> = path_set.into_iter().collect();
 
-    // Construct URL: parent_web_url#note_{first_note_gitlab_id}
     let first_note_gitlab_id = notes[0].gitlab_id;
     let url = parent_web_url
         .as_ref()
         .map(|wu| format!("{}#note_{}", wu, first_note_gitlab_id));
 
-    // First non-system note author
     let author_username = notes[0].author.clone();
 
-    // Build content
     let display_title = parent_title.as_deref().unwrap_or("(untitled)");
     let labels_json = serde_json::to_string(&labels).unwrap_or_else(|_| "[]".to_string());
     let paths_json = serde_json::to_string(&paths).unwrap_or_else(|_| "[]".to_string());
@@ -507,7 +471,6 @@ pub fn extract_discussion_document(
         content.push_str(&format!("Files: {}\n", paths_json));
     }
 
-    // Build NoteContent list for truncation-aware thread rendering
     let note_contents: Vec<NoteContent> = notes
         .iter()
         .map(|note| NoteContent {
@@ -517,7 +480,6 @@ pub fn extract_discussion_document(
         })
         .collect();
 
-    // Estimate header size to reserve budget for thread content
     let header_len = content.len() + "\n--- Thread ---\n\n".len();
     let thread_budget = MAX_DISCUSSION_BYTES.saturating_sub(header_len);
 
@@ -525,7 +487,6 @@ pub fn extract_discussion_document(
     content.push_str("\n--- Thread ---\n\n");
     content.push_str(&thread_result.content);
 
-    // Use first note's created_at and last note's created_at for timestamps
     let created_at = notes[0].created_at;
     let updated_at = notes.last().map(|n| n.created_at).unwrap_or(created_at);
 
@@ -545,7 +506,7 @@ pub fn extract_discussion_document(
         created_at,
         updated_at,
         url,
-        title: None, // Discussions don't have their own title
+        title: None,
         content_text: content,
         content_hash,
         is_truncated: thread_result.is_truncated,
@@ -580,7 +541,7 @@ mod tests {
             Some(SourceType::Discussion)
         );
         assert_eq!(SourceType::parse("invalid"), None);
-        assert_eq!(SourceType::parse("ISSUE"), Some(SourceType::Issue)); // case insensitive
+        assert_eq!(SourceType::parse("ISSUE"), Some(SourceType::Issue));
     }
 
     #[test]
@@ -603,8 +564,7 @@ mod tests {
         let hash2 = compute_content_hash("hello");
         assert_eq!(hash1, hash2);
         assert!(!hash1.is_empty());
-        // SHA-256 of "hello" is known
-        assert_eq!(hash1.len(), 64); // 256 bits = 64 hex chars
+        assert_eq!(hash1.len(), 64);
     }
 
     #[test]
@@ -631,12 +591,10 @@ mod tests {
     fn test_list_hash_empty() {
         let hash = compute_list_hash(&[]);
         assert_eq!(hash.len(), 64);
-        // Empty list hashes consistently
         let hash2 = compute_list_hash(&[]);
         assert_eq!(hash, hash2);
     }
 
-    // Helper to create an in-memory DB with the required tables for extraction tests
     fn setup_test_db() -> Connection {
         let conn = Connection::open_in_memory().unwrap();
         conn.execute_batch(
@@ -685,7 +643,6 @@ mod tests {
         )
         .unwrap();
 
-        // Insert a test project
         conn.execute(
             "INSERT INTO projects (id, gitlab_project_id, path_with_namespace, web_url) VALUES (1, 100, 'group/project-one', 'https://gitlab.example.com/group/project-one')",
             [],
@@ -871,12 +828,9 @@ mod tests {
         insert_issue(&conn, 1, 10, Some("Test"), Some(""), "opened", None, None);
 
         let doc = extract_issue_document(&conn, 1).unwrap().unwrap();
-        // Empty string description still includes the section header
         assert!(doc.content_text.contains("--- Description ---\n\n"));
     }
 
-    // --- MR extraction tests ---
-
     fn setup_mr_test_db() -> Connection {
         let conn = setup_test_db();
         conn.execute_batch(
@@ -1067,10 +1021,8 @@ mod tests {
         assert!(!doc.content_text.contains("Source:"));
     }
 
-    // --- Discussion extraction tests ---
-
     fn setup_discussion_test_db() -> Connection {
-        let conn = setup_mr_test_db(); // includes projects, issues schema, labels, mr tables
+        let conn = setup_mr_test_db();
         conn.execute_batch(
             "
             CREATE TABLE discussions (
@@ -1166,7 +1118,6 @@ mod tests {
         link_issue_label(&conn, 1, 1);
         link_issue_label(&conn, 1, 2);
         insert_discussion(&conn, 1, "Issue", Some(1), None);
-        // 1710460800000 = 2024-03-15T00:00:00Z
         insert_note(
             &conn,
             1,
@@ -1213,7 +1164,7 @@ mod tests {
                 .contains("@janedoe (2024-03-15):\nAgreed. What about refresh token strategy?")
         );
         assert_eq!(doc.author_username, Some("johndoe".to_string()));
-        assert!(doc.title.is_none()); // Discussions don't have their own title
+        assert!(doc.title.is_none());
     }
 
     #[test]
@@ -1226,7 +1177,6 @@ mod tests {
     #[test]
     fn test_discussion_parent_deleted() {
         let conn = setup_discussion_test_db();
-        // Insert issue, create discussion, then delete the issue
         insert_issue(
             &conn,
             99,
@@ -1250,8 +1200,6 @@ mod tests {
             None,
             None,
         );
-        // Delete the parent issue — FK cascade won't delete discussion in test since
-        // we used REFERENCES without ON DELETE CASCADE in test schema, so just delete from issues
         conn.execute("PRAGMA foreign_keys = OFF", []).unwrap();
         conn.execute("DELETE FROM issues WHERE id = 99", [])
             .unwrap();
@@ -1358,7 +1306,6 @@ mod tests {
         );
 
         let doc = extract_discussion_document(&conn, 1).unwrap().unwrap();
-        // Paths should be deduplicated and sorted
         assert_eq!(doc.paths, vec!["src/new.rs", "src/old.rs"]);
         assert!(
             doc.content_text
@@ -1498,7 +1445,6 @@ mod tests {
             None,
         );
 
-        // All notes are system notes -> no content -> returns None
         let result = extract_discussion_document(&conn, 1).unwrap();
         assert!(result.is_none());
     }
diff --git a/src/documents/mod.rs b/src/documents/mod.rs
index 6a86386..c2c57f5 100644
--- a/src/documents/mod.rs
+++ b/src/documents/mod.rs
@@ -1,7 +1,3 @@
-//! Document generation and management.
-//!
-//! Extracts searchable documents from issues, MRs, and discussions.
-
 mod extractor;
 mod regenerator;
 mod truncation;
diff --git a/src/documents/regenerator.rs b/src/documents/regenerator.rs
index ff2f965..48898a0 100644
--- a/src/documents/regenerator.rs
+++ b/src/documents/regenerator.rs
@@ -9,7 +9,6 @@ use crate::documents::{
 };
 use crate::ingestion::dirty_tracker::{clear_dirty, get_dirty_sources, record_dirty_error};
 
-/// Result of a document regeneration run.
 #[derive(Debug, Default)]
 pub struct RegenerateResult {
     pub regenerated: usize,
@@ -17,12 +16,6 @@ pub struct RegenerateResult {
     pub errored: usize,
 }
 
-/// Drain the dirty_sources queue, regenerating documents for each entry.
-///
-/// Uses per-item error handling (fail-soft) and drains the queue completely
-/// via a bounded batch loop. Each dirty item is processed independently.
-///
-/// `progress_callback` reports `(processed, estimated_total)` after each item.
 #[instrument(
     skip(conn, progress_callback),
     fields(items_processed, items_skipped, errors)
@@ -33,10 +26,6 @@ pub fn regenerate_dirty_documents(
 ) -> Result<RegenerateResult> {
     let mut result = RegenerateResult::default();
 
-    // Estimated total for progress reporting.  Recount each loop iteration
-    // so the denominator grows if new items are enqueued during processing
-    // (the queue can grow while we drain it).  We use max() so the value
-    // never shrinks — preventing the progress fraction from going backwards.
     let mut estimated_total: usize = 0;
 
     loop {
@@ -45,7 +34,6 @@ pub fn regenerate_dirty_documents(
             break;
         }
 
-        // Recount remaining + already-processed to get the true total.
         let remaining: usize = conn
             .query_row("SELECT COUNT(*) FROM dirty_sources", [], |row| row.get(0))
             .unwrap_or(0_i64) as usize;
@@ -95,7 +83,6 @@ pub fn regenerate_dirty_documents(
     Ok(result)
 }
 
-/// Regenerate a single document. Returns true if content_hash changed.
 fn regenerate_one(conn: &Connection, source_type: SourceType, source_id: i64) -> Result<bool> {
     let doc = match source_type {
         SourceType::Issue => extract_issue_document(conn, source_id)?,
@@ -104,7 +91,6 @@ fn regenerate_one(conn: &Connection, source_type: SourceType, source_id: i64) ->
     };
 
     let Some(doc) = doc else {
-        // Source was deleted — remove the document (cascade handles FTS/embeddings)
         delete_document(conn, source_type, source_id)?;
         return Ok(true);
     };
@@ -112,13 +98,11 @@ fn regenerate_one(conn: &Connection, source_type: SourceType, source_id: i64) ->
     let existing_hash = get_existing_hash(conn, source_type, source_id)?;
     let changed = existing_hash.as_ref() != Some(&doc.content_hash);
 
-    // Always upsert: labels/paths can change independently of content_hash
     upsert_document(conn, &doc)?;
 
     Ok(changed)
 }
 
-/// Get existing content hash for a document, if it exists.
 fn get_existing_hash(
     conn: &Connection,
     source_type: SourceType,
@@ -136,11 +120,6 @@ fn get_existing_hash(
     Ok(hash)
 }
 
-/// Upsert a document with triple-hash write optimization.
-///
-/// Wrapped in a SAVEPOINT to ensure atomicity of the multi-statement write
-/// (document row + labels + paths). Without this, a crash between statements
-/// could leave the document with a stale labels_hash but missing label rows.
 fn upsert_document(conn: &Connection, doc: &DocumentData) -> Result<()> {
     conn.execute_batch("SAVEPOINT upsert_doc")?;
     match upsert_document_inner(conn, doc) {
@@ -149,8 +128,6 @@ fn upsert_document(conn: &Connection, doc: &DocumentData) -> Result<()> {
             Ok(())
         }
         Err(e) => {
-            // ROLLBACK TO restores the savepoint but leaves it active.
-            // RELEASE removes it so the connection is clean for the next call.
             let _ = conn.execute_batch("ROLLBACK TO upsert_doc; RELEASE upsert_doc");
             Err(e)
         }
@@ -158,7 +135,6 @@ fn upsert_document(conn: &Connection, doc: &DocumentData) -> Result<()> {
 }
 
 fn upsert_document_inner(conn: &Connection, doc: &DocumentData) -> Result<()> {
-    // Check existing hashes before writing
     let existing: Option<(i64, String, String, String)> = conn
         .query_row(
             "SELECT id, content_hash, labels_hash, paths_hash FROM documents
@@ -168,7 +144,6 @@ fn upsert_document_inner(conn: &Connection, doc: &DocumentData) -> Result<()> {
         )
         .optional()?;
 
-    // Fast path: skip ALL writes when nothing changed (prevents WAL churn)
     if let Some((_, ref old_content_hash, ref old_labels_hash, ref old_paths_hash)) = existing
         && old_content_hash == &doc.content_hash
         && old_labels_hash == &doc.labels_hash
@@ -179,7 +154,6 @@ fn upsert_document_inner(conn: &Connection, doc: &DocumentData) -> Result<()> {
 
     let labels_json = serde_json::to_string(&doc.labels).unwrap_or_else(|_| "[]".to_string());
 
-    // Upsert document row
     conn.execute(
         "INSERT INTO documents
          (source_type, source_id, project_id, author_username, label_names,
@@ -218,13 +192,11 @@ fn upsert_document_inner(conn: &Connection, doc: &DocumentData) -> Result<()> {
         ],
     )?;
 
-    // Get document ID
     let doc_id = match existing {
         Some((id, _, _, _)) => id,
         None => get_document_id(conn, doc.source_type, doc.source_id)?,
     };
 
-    // Only update labels if hash changed
     let labels_changed = match &existing {
         Some((_, _, old_hash, _)) => old_hash != &doc.labels_hash,
         None => true,
@@ -242,7 +214,6 @@ fn upsert_document_inner(conn: &Connection, doc: &DocumentData) -> Result<()> {
         }
     }
 
-    // Only update paths if hash changed
     let paths_changed = match &existing {
         Some((_, _, _, old_hash)) => old_hash != &doc.paths_hash,
         None => true,
@@ -263,7 +234,6 @@ fn upsert_document_inner(conn: &Connection, doc: &DocumentData) -> Result<()> {
     Ok(())
 }
 
-/// Delete a document by source identity.
 fn delete_document(conn: &Connection, source_type: SourceType, source_id: i64) -> Result<()> {
     conn.execute(
         "DELETE FROM documents WHERE source_type = ?1 AND source_id = ?2",
@@ -272,7 +242,6 @@ fn delete_document(conn: &Connection, source_type: SourceType, source_id: i64) -
     Ok(())
 }
 
-/// Get document ID by source type and source ID.
 fn get_document_id(conn: &Connection, source_type: SourceType, source_id: i64) -> Result<i64> {
     let id: i64 = conn.query_row(
         "SELECT id FROM documents WHERE source_type = ?1 AND source_id = ?2",
@@ -391,7 +360,6 @@ mod tests {
         assert_eq!(result.unchanged, 0);
         assert_eq!(result.errored, 0);
 
-        // Verify document was created
         let count: i64 = conn
             .query_row("SELECT COUNT(*) FROM documents", [], |r| r.get(0))
             .unwrap();
@@ -411,12 +379,10 @@ mod tests {
             [],
         ).unwrap();
 
-        // First regeneration creates the document
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
         let r1 = regenerate_dirty_documents(&conn, None).unwrap();
         assert_eq!(r1.regenerated, 1);
 
-        // Second regeneration — same data, should be unchanged
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
         let r2 = regenerate_dirty_documents(&conn, None).unwrap();
         assert_eq!(r2.unchanged, 1);
@@ -433,14 +399,13 @@ mod tests {
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
         regenerate_dirty_documents(&conn, None).unwrap();
 
-        // Delete the issue and re-mark dirty
         conn.execute("PRAGMA foreign_keys = OFF", []).unwrap();
         conn.execute("DELETE FROM issues WHERE id = 1", []).unwrap();
         conn.execute("PRAGMA foreign_keys = ON", []).unwrap();
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
 
         let result = regenerate_dirty_documents(&conn, None).unwrap();
-        assert_eq!(result.regenerated, 1); // Deletion counts as "changed"
+        assert_eq!(result.regenerated, 1);
 
         let count: i64 = conn
             .query_row("SELECT COUNT(*) FROM documents", [], |r| r.get(0))
@@ -462,7 +427,6 @@ mod tests {
         let result = regenerate_dirty_documents(&conn, None).unwrap();
         assert_eq!(result.regenerated, 10);
 
-        // Queue should be empty
         let dirty = get_dirty_sources(&conn).unwrap();
         assert!(dirty.is_empty());
     }
@@ -485,16 +449,13 @@ mod tests {
         )
         .unwrap();
 
-        // First run creates document
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
         regenerate_dirty_documents(&conn, None).unwrap();
 
-        // Second run — triple hash match, should skip ALL writes
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
         let result = regenerate_dirty_documents(&conn, None).unwrap();
         assert_eq!(result.unchanged, 1);
 
-        // Labels should still be present (not deleted and re-inserted)
         let label_count: i64 = conn
             .query_row("SELECT COUNT(*) FROM document_labels", [], |r| r.get(0))
             .unwrap();
diff --git a/src/documents/truncation.rs b/src/documents/truncation.rs
index 9511a1d..425e73b 100644
--- a/src/documents/truncation.rs
+++ b/src/documents/truncation.rs
@@ -1,25 +1,19 @@
-/// Maximum byte limit for discussion documents (suitable for embedding chunking).
-/// Note: uses `.len()` (byte count), not char count — consistent with `CHUNK_MAX_BYTES`.
 pub const MAX_DISCUSSION_BYTES: usize = 32_000;
 
-/// Hard safety cap (bytes) for any document type (pathological content: pasted logs, base64).
 pub const MAX_DOCUMENT_BYTES_HARD: usize = 2_000_000;
 
-/// A single note's content for truncation processing.
 pub struct NoteContent {
     pub author: String,
     pub date: String,
     pub body: String,
 }
 
-/// Result of truncation processing.
 pub struct TruncationResult {
     pub content: String,
     pub is_truncated: bool,
     pub reason: Option<TruncationReason>,
 }
 
-/// Why a document was truncated (matches DB CHECK constraint values).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TruncationReason {
     TokenLimitMiddleDrop,
@@ -29,7 +23,6 @@ pub enum TruncationReason {
 }
 
 impl TruncationReason {
-    /// Returns the DB-compatible string matching the CHECK constraint.
     pub fn as_str(&self) -> &'static str {
         match self {
             Self::TokenLimitMiddleDrop => "token_limit_middle_drop",
@@ -40,19 +33,14 @@ impl TruncationReason {
     }
 }
 
-/// Format a single note as `@author (date):\nbody\n\n`.
 fn format_note(note: &NoteContent) -> String {
     format!("@{} ({}):\n{}\n\n", note.author, note.date, note.body)
 }
 
-/// Truncate a string at a UTF-8-safe byte boundary.
-/// Returns a slice no longer than `max_bytes` bytes, walking backward
-/// to find the nearest char boundary if needed.
 pub fn truncate_utf8(s: &str, max_bytes: usize) -> &str {
     if s.len() <= max_bytes {
         return s;
     }
-    // Walk backward from max_bytes to find a char boundary
     let mut end = max_bytes;
     while end > 0 && !s.is_char_boundary(end) {
         end -= 1;
@@ -60,14 +48,6 @@ pub fn truncate_utf8(s: &str, max_bytes: usize) -> &str {
     &s[..end]
 }
 
-/// Truncate discussion notes to fit within `max_bytes`.
-///
-/// Algorithm:
-/// 1. Format all notes
-/// 2. If total fits, return as-is
-/// 3. Single note: truncate at UTF-8 boundary, append [truncated]
-/// 4. Try to keep first N notes + last note + marker within limit
-/// 5. If first + last > limit: keep only first (truncated)
 pub fn truncate_discussion(notes: &[NoteContent], max_bytes: usize) -> TruncationResult {
     if notes.is_empty() {
         return TruncationResult {
@@ -80,7 +60,6 @@ pub fn truncate_discussion(notes: &[NoteContent], max_bytes: usize) -> Truncatio
     let formatted: Vec<String> = notes.iter().map(format_note).collect();
     let total: String = formatted.concat();
 
-    // Case 1: fits within limit
     if total.len() <= max_bytes {
         return TruncationResult {
             content: total,
@@ -89,9 +68,8 @@ pub fn truncate_discussion(notes: &[NoteContent], max_bytes: usize) -> Truncatio
         };
     }
 
-    // Case 2: single note — truncate it
     if notes.len() == 1 {
-        let truncated = truncate_utf8(&total, max_bytes.saturating_sub(11)); // room for [truncated]
+        let truncated = truncate_utf8(&total, max_bytes.saturating_sub(11));
         let content = format!("{}[truncated]", truncated);
         return TruncationResult {
             content,
@@ -100,10 +78,8 @@ pub fn truncate_discussion(notes: &[NoteContent], max_bytes: usize) -> Truncatio
         };
     }
 
-    // Case 3: multiple notes — try first N + marker + last
     let last_note = &formatted[formatted.len() - 1];
 
-    // Binary search for max N where first N notes + marker + last note fit
     let mut best_n = 0;
     for n in 1..formatted.len() - 1 {
         let first_n: usize = formatted[..n].iter().map(|s| s.len()).sum();
@@ -118,7 +94,6 @@ pub fn truncate_discussion(notes: &[NoteContent], max_bytes: usize) -> Truncatio
     }
 
     if best_n > 0 {
-        // We can keep first best_n notes + marker + last note
         let first_part: String = formatted[..best_n].concat();
         let omitted = formatted.len() - best_n - 1;
         let marker = format!("\n\n[... {} notes omitted for length ...]\n\n", omitted);
@@ -130,7 +105,6 @@ pub fn truncate_discussion(notes: &[NoteContent], max_bytes: usize) -> Truncatio
         };
     }
 
-    // Case 4: even first + last don't fit — keep only first (truncated)
     let first_note = &formatted[0];
     if first_note.len() + last_note.len() > max_bytes {
         let truncated = truncate_utf8(first_note, max_bytes.saturating_sub(11));
@@ -142,7 +116,6 @@ pub fn truncate_discussion(notes: &[NoteContent], max_bytes: usize) -> Truncatio
         };
     }
 
-    // Fallback: first + marker + last (0 middle notes kept)
     let omitted = formatted.len() - 2;
     let marker = format!("\n\n[... {} notes omitted for length ...]\n\n", omitted);
     let content = format!("{}{}{}", formatted[0], marker, last_note);
@@ -153,8 +126,6 @@ pub fn truncate_discussion(notes: &[NoteContent], max_bytes: usize) -> Truncatio
     }
 }
 
-/// Apply hard cap truncation to any document type.
-/// Truncates at UTF-8-safe boundary if content exceeds 2MB.
 pub fn truncate_hard_cap(content: &str) -> TruncationResult {
     if content.len() <= MAX_DOCUMENT_BYTES_HARD {
         return TruncationResult {
@@ -201,7 +172,6 @@ mod tests {
 
     #[test]
     fn test_middle_notes_dropped() {
-        // Create 10 notes where total exceeds limit
         let big_body = "x".repeat(4000);
         let notes: Vec<NoteContent> = (0..10)
             .map(|i| make_note(&format!("user{}", i), &big_body))
@@ -209,11 +179,8 @@ mod tests {
         let result = truncate_discussion(&notes, 10_000);
         assert!(result.is_truncated);
         assert_eq!(result.reason, Some(TruncationReason::TokenLimitMiddleDrop));
-        // First note preserved
         assert!(result.content.contains("@user0"));
-        // Last note preserved
         assert!(result.content.contains("@user9"));
-        // Marker present
         assert!(result.content.contains("notes omitted for length"));
     }
 
@@ -256,20 +223,16 @@ mod tests {
 
     #[test]
     fn test_utf8_boundary_safety() {
-        // Emoji are 4 bytes each
         let emoji_content = "🎉".repeat(10);
         let truncated = truncate_utf8(&emoji_content, 10);
-        // 10 bytes should hold 2 emoji (8 bytes) with 2 bytes left over (not enough for another)
         assert_eq!(truncated.len(), 8);
         assert_eq!(truncated, "🎉🎉");
     }
 
     #[test]
     fn test_utf8_boundary_cjk() {
-        // CJK characters are 3 bytes each
         let cjk = "中文字符测试";
         let truncated = truncate_utf8(cjk, 7);
-        // 7 bytes: 2 full chars (6 bytes), 1 byte left (not enough for another)
         assert_eq!(truncated, "中文");
         assert_eq!(truncated.len(), 6);
     }
@@ -294,7 +257,6 @@ mod tests {
 
     #[test]
     fn test_marker_count_correct() {
-        // 7 notes, keep first 1 + last 1, drop middle 5
         let big_body = "x".repeat(5000);
         let notes: Vec<NoteContent> = (0..7)
             .map(|i| make_note(&format!("user{}", i), &big_body))
diff --git a/src/embedding/change_detector.rs b/src/embedding/change_detector.rs
index 1445c99..7926b50 100644
--- a/src/embedding/change_detector.rs
+++ b/src/embedding/change_detector.rs
@@ -1,11 +1,8 @@
-//! Detect documents needing (re-)embedding based on content hash changes.
-
 use rusqlite::Connection;
 
 use crate::core::error::Result;
 use crate::embedding::chunking::{CHUNK_MAX_BYTES, EXPECTED_DIMS};
 
-/// A document that needs embedding or re-embedding.
 #[derive(Debug)]
 pub struct PendingDocument {
     pub document_id: i64,
@@ -13,20 +10,12 @@ pub struct PendingDocument {
     pub content_hash: String,
 }
 
-/// Find documents that need embedding: new (no metadata), changed (hash mismatch),
-/// or config-drifted (chunk_max_bytes/model/dims mismatch).
-///
-/// Uses keyset pagination (WHERE d.id > last_id) and returns up to `page_size` results.
 pub fn find_pending_documents(
     conn: &Connection,
     page_size: usize,
     last_id: i64,
     model_name: &str,
 ) -> Result<Vec<PendingDocument>> {
-    // Documents that either:
-    // 1. Have no embedding_metadata at all (new)
-    // 2. Have metadata where document_hash != content_hash (changed)
-    // 3. Config drift: chunk_max_bytes, model, or dims mismatch (or pre-migration NULL)
     let sql = r#"
         SELECT d.id, d.content_text, d.content_hash
         FROM documents d
@@ -79,7 +68,6 @@ pub fn find_pending_documents(
     Ok(rows)
 }
 
-/// Count total documents that need embedding.
 pub fn count_pending_documents(conn: &Connection, model_name: &str) -> Result<i64> {
     let count: i64 = conn.query_row(
         r#"
diff --git a/src/embedding/chunk_ids.rs b/src/embedding/chunk_ids.rs
index a678764..ea406e5 100644
--- a/src/embedding/chunk_ids.rs
+++ b/src/embedding/chunk_ids.rs
@@ -1,17 +1,9 @@
-/// Multiplier for encoding (document_id, chunk_index) into a single rowid.
-/// Supports up to 1000 chunks per document. At CHUNK_MAX_BYTES=6000,
-/// a 2MB document (MAX_DOCUMENT_BYTES_HARD) produces ~333 chunks.
-/// The pipeline enforces chunk_count <= CHUNK_ROWID_MULTIPLIER at runtime.
 pub const CHUNK_ROWID_MULTIPLIER: i64 = 1000;
 
-/// Encode (document_id, chunk_index) into a sqlite-vec rowid.
-///
-/// rowid = document_id * CHUNK_ROWID_MULTIPLIER + chunk_index
 pub fn encode_rowid(document_id: i64, chunk_index: i64) -> i64 {
     document_id * CHUNK_ROWID_MULTIPLIER + chunk_index
 }
 
-/// Decode a sqlite-vec rowid back into (document_id, chunk_index).
 pub fn decode_rowid(rowid: i64) -> (i64, i64) {
     let document_id = rowid / CHUNK_ROWID_MULTIPLIER;
     let chunk_index = rowid % CHUNK_ROWID_MULTIPLIER;
diff --git a/src/embedding/chunking.rs b/src/embedding/chunking.rs
index 50f2c86..36be003 100644
--- a/src/embedding/chunking.rs
+++ b/src/embedding/chunking.rs
@@ -1,29 +1,9 @@
-//! Text chunking for embedding: split documents at paragraph boundaries with overlap.
-
-/// Maximum bytes per chunk.
-/// Named `_BYTES` because `str::len()` returns byte count; multi-byte UTF-8
-/// sequences mean byte length >= char count.
-///
-/// nomic-embed-text has an 8,192-token context window. English prose averages
-/// ~4 chars/token, but technical content (code, URLs, JSON) can be 1-2
-/// chars/token. We use 6,000 bytes as a conservative limit that stays safe
-/// even for code-heavy chunks (~6,000 tokens worst-case).
 pub const CHUNK_MAX_BYTES: usize = 6_000;
 
-/// Expected embedding dimensions for nomic-embed-text.
 pub const EXPECTED_DIMS: usize = 768;
 
-/// Character overlap between adjacent chunks.
 pub const CHUNK_OVERLAP_CHARS: usize = 200;
 
-/// Split document content into chunks suitable for embedding.
-///
-/// Documents <= CHUNK_MAX_BYTES produce a single chunk.
-/// Longer documents are split at paragraph boundaries (`\n\n`), falling back
-/// to sentence boundaries, then word boundaries, then hard character cut.
-/// Adjacent chunks share CHUNK_OVERLAP_CHARS of overlap.
-///
-/// Returns Vec<(chunk_index, chunk_text)>.
 pub fn split_into_chunks(content: &str) -> Vec<(usize, String)> {
     if content.is_empty() {
         return Vec::new();
@@ -44,11 +24,9 @@ pub fn split_into_chunks(content: &str) -> Vec<(usize, String)> {
             break;
         }
 
-        // Find a split point within CHUNK_MAX_BYTES (char-boundary-safe)
         let end = floor_char_boundary(content, start + CHUNK_MAX_BYTES);
         let window = &content[start..end];
 
-        // Try paragraph boundary (\n\n) — search backward from end
         let split_at = find_paragraph_break(window)
             .or_else(|| find_sentence_break(window))
             .or_else(|| find_word_break(window))
@@ -57,9 +35,6 @@ pub fn split_into_chunks(content: &str) -> Vec<(usize, String)> {
         let chunk_text = &content[start..start + split_at];
         chunks.push((chunk_index, chunk_text.to_string()));
 
-        // Advance with overlap, guaranteeing forward progress to prevent infinite loops.
-        // If split_at <= CHUNK_OVERLAP_CHARS we skip overlap to avoid stalling.
-        // The .max(1) ensures we always advance at least 1 byte.
         let advance = if split_at > CHUNK_OVERLAP_CHARS {
             split_at - CHUNK_OVERLAP_CHARS
         } else {
@@ -73,10 +48,7 @@ pub fn split_into_chunks(content: &str) -> Vec<(usize, String)> {
     chunks
 }
 
-/// Find the last paragraph break (`\n\n`) in the window, preferring the
-/// last third for balanced chunks.
 fn find_paragraph_break(window: &str) -> Option<usize> {
-    // Search backward from 2/3 of the way through to find a good split
     let search_start = window.len() * 2 / 3;
     window[search_start..]
         .rfind("\n\n")
@@ -84,7 +56,6 @@ fn find_paragraph_break(window: &str) -> Option<usize> {
         .or_else(|| window[..search_start].rfind("\n\n").map(|pos| pos + 2))
 }
 
-/// Find the last sentence boundary (`. `, `? `, `! `) in the window.
 fn find_sentence_break(window: &str) -> Option<usize> {
     let search_start = window.len() / 2;
     for pat in &[". ", "? ", "! "] {
@@ -92,7 +63,6 @@ fn find_sentence_break(window: &str) -> Option<usize> {
             return Some(search_start + pos + pat.len());
         }
     }
-    // Try first half
     for pat in &[". ", "? ", "! "] {
         if let Some(pos) = window[..search_start].rfind(pat) {
             return Some(pos + pat.len());
@@ -101,7 +71,6 @@ fn find_sentence_break(window: &str) -> Option<usize> {
     None
 }
 
-/// Find the last word boundary (space) in the window.
 fn find_word_break(window: &str) -> Option<usize> {
     let search_start = window.len() / 2;
     window[search_start..]
@@ -110,8 +79,6 @@ fn find_word_break(window: &str) -> Option<usize> {
         .or_else(|| window[..search_start].rfind(' ').map(|pos| pos + 1))
 }
 
-/// Find the largest byte index <= `idx` that is a valid char boundary in `s`.
-/// Equivalent to `str::floor_char_boundary` (stabilized in Rust 1.82).
 fn floor_char_boundary(s: &str, idx: usize) -> usize {
     if idx >= s.len() {
         return s.len();
@@ -151,7 +118,6 @@ mod tests {
 
     #[test]
     fn test_long_document_multiple_chunks() {
-        // Create content > CHUNK_MAX_BYTES with paragraph boundaries
         let paragraph = "This is a paragraph of text.\n\n";
         let mut content = String::new();
         while content.len() < CHUNK_MAX_BYTES * 2 {
@@ -165,18 +131,15 @@ mod tests {
             chunks.len()
         );
 
-        // Verify indices are sequential
         for (i, (idx, _)) in chunks.iter().enumerate() {
             assert_eq!(*idx, i);
         }
 
-        // Verify all content is covered (no gaps)
         assert!(!chunks.last().unwrap().1.is_empty());
     }
 
     #[test]
     fn test_chunk_overlap() {
-        // Create content that will produce 2+ chunks
         let paragraph = "This is paragraph content for testing chunk overlap behavior.\n\n";
         let mut content = String::new();
         while content.len() < CHUNK_MAX_BYTES + CHUNK_OVERLAP_CHARS + 1000 {
@@ -186,11 +149,9 @@ mod tests {
         let chunks = split_into_chunks(&content);
         assert!(chunks.len() >= 2);
 
-        // Check that adjacent chunks share some content (overlap)
         if chunks.len() >= 2 {
             let end_of_first = &chunks[0].1;
             let start_of_second = &chunks[1].1;
-            // The end of first chunk should overlap with start of second
             let overlap_region =
                 &end_of_first[end_of_first.len().saturating_sub(CHUNK_OVERLAP_CHARS)..];
             assert!(
@@ -203,11 +164,9 @@ mod tests {
 
     #[test]
     fn test_no_paragraph_boundary() {
-        // Create content without paragraph breaks
         let content = "word ".repeat(CHUNK_MAX_BYTES / 5 * 3);
         let chunks = split_into_chunks(&content);
         assert!(chunks.len() >= 2);
-        // Should still split (at word boundaries)
         for (_, chunk) in &chunks {
             assert!(!chunk.is_empty());
         }
diff --git a/src/embedding/ollama.rs b/src/embedding/ollama.rs
index 13c9136..7076626 100644
--- a/src/embedding/ollama.rs
+++ b/src/embedding/ollama.rs
@@ -4,7 +4,6 @@ use std::time::Duration;
 
 use crate::core::error::{LoreError, Result};
 
-/// Configuration for Ollama embedding service.
 pub struct OllamaConfig {
     pub base_url: String,
     pub model: String,
@@ -21,7 +20,6 @@ impl Default for OllamaConfig {
     }
 }
 
-/// Async client for Ollama embedding API.
 pub struct OllamaClient {
     client: Client,
     config: OllamaConfig,
@@ -60,10 +58,6 @@ impl OllamaClient {
         Self { client, config }
     }
 
-    /// Health check: verifies Ollama is reachable and the configured model exists.
-    ///
-    /// Model matching uses `starts_with` so "nomic-embed-text" matches
-    /// "nomic-embed-text:latest".
     pub async fn health_check(&self) -> Result<()> {
         let url = format!("{}/api/tags", self.config.base_url);
 
@@ -100,9 +94,6 @@ impl OllamaClient {
         Ok(())
     }
 
-    /// Embed a batch of texts using the configured model.
-    ///
-    /// Returns one embedding vector per input text.
     pub async fn embed_batch(&self, texts: Vec<String>) -> Result<Vec<Vec<f32>>> {
         let url = format!("{}/api/embed", self.config.base_url);
 
@@ -144,7 +135,6 @@ impl OllamaClient {
     }
 }
 
-/// Quick health check without creating a full client.
 pub async fn check_ollama_health(base_url: &str) -> bool {
     let client = Client::builder()
         .timeout(Duration::from_secs(5))
@@ -173,12 +163,10 @@ mod tests {
 
     #[test]
     fn test_health_check_model_starts_with() {
-        // Verify the matching logic: "nomic-embed-text" should match "nomic-embed-text:latest"
         let model = "nomic-embed-text";
         let tag_name = "nomic-embed-text:latest";
         assert!(tag_name.starts_with(model));
 
-        // Non-matching model
         let wrong_model = "llama2";
         assert!(!tag_name.starts_with(wrong_model));
     }
diff --git a/src/embedding/pipeline.rs b/src/embedding/pipeline.rs
index 74de771..876ebd6 100644
--- a/src/embedding/pipeline.rs
+++ b/src/embedding/pipeline.rs
@@ -1,5 +1,3 @@
-//! Async embedding pipeline: chunk documents, embed via Ollama, store in sqlite-vec.
-
 use std::collections::HashSet;
 
 use rusqlite::Connection;
@@ -15,7 +13,6 @@ use crate::embedding::ollama::OllamaClient;
 const BATCH_SIZE: usize = 32;
 const DB_PAGE_SIZE: usize = 500;
 
-/// Result of an embedding run.
 #[derive(Debug, Default)]
 pub struct EmbedResult {
     pub embedded: usize,
@@ -23,7 +20,6 @@ pub struct EmbedResult {
     pub skipped: usize,
 }
 
-/// Work item: a single chunk to embed.
 struct ChunkWork {
     doc_id: i64,
     chunk_index: usize,
@@ -33,10 +29,6 @@ struct ChunkWork {
     text: String,
 }
 
-/// Run the embedding pipeline: find pending documents, chunk, embed, store.
-///
-/// Processes batches of BATCH_SIZE texts per Ollama API call.
-/// Uses keyset pagination over documents (DB_PAGE_SIZE per page).
 #[instrument(skip(conn, client, progress_callback), fields(%model_name, items_processed, items_skipped, errors))]
 pub async fn embed_documents(
     conn: &Connection,
@@ -61,16 +53,6 @@ pub async fn embed_documents(
             break;
         }
 
-        // Wrap all DB writes for this page in a savepoint so that
-        // clear_document_embeddings + store_embedding are atomic.  If the
-        // process crashes mid-page, the savepoint is never released and
-        // SQLite rolls back — preventing partial document states where old
-        // embeddings are cleared but new ones haven't been written yet.
-        //
-        // We use a closure + match to ensure the savepoint is always
-        // rolled back on error — bare `execute_batch("SAVEPOINT")` with `?`
-        // propagation would leak the savepoint and leave the connection in
-        // a broken transactional state.
         conn.execute_batch("SAVEPOINT embed_page")?;
         let page_result = embed_page(
             conn,
@@ -109,10 +91,6 @@ pub async fn embed_documents(
     Ok(result)
 }
 
-/// Process a single page of pending documents within an active savepoint.
-///
-/// All `?` propagation from this function is caught by the caller, which
-/// rolls back the savepoint on error.
 #[allow(clippy::too_many_arguments)]
 async fn embed_page(
     conn: &Connection,
@@ -125,12 +103,10 @@ async fn embed_page(
     total: usize,
     progress_callback: &Option<Box<dyn Fn(usize, usize)>>,
 ) -> Result<()> {
-    // Build chunk work items for this page
     let mut all_chunks: Vec<ChunkWork> = Vec::new();
     let mut page_normal_docs: usize = 0;
 
     for doc in pending {
-        // Always advance the cursor, even for skipped docs, to avoid re-fetching
         *last_id = doc.document_id;
 
         if doc.content_text.is_empty() {
@@ -142,9 +118,6 @@ async fn embed_page(
         let chunks = split_into_chunks(&doc.content_text);
         let total_chunks = chunks.len();
 
-        // Overflow guard: skip documents that produce too many chunks.
-        // Must run BEFORE clear_document_embeddings so existing embeddings
-        // are preserved when we skip.
         if total_chunks as i64 > CHUNK_ROWID_MULTIPLIER {
             warn!(
                 doc_id = doc.document_id,
@@ -152,12 +125,10 @@ async fn embed_page(
                 max = CHUNK_ROWID_MULTIPLIER,
                 "Document produces too many chunks, skipping to prevent rowid collision"
             );
-            // Record a sentinel error so the document is not re-detected as
-            // pending on subsequent runs (prevents infinite re-processing).
             record_embedding_error(
                 conn,
                 doc.document_id,
-                0, // sentinel chunk_index
+                0,
                 &doc.content_hash,
                 "overflow-sentinel",
                 model_name,
@@ -174,10 +145,6 @@ async fn embed_page(
             continue;
         }
 
-        // Don't clear existing embeddings here — defer until the first
-        // successful chunk embedding so that if ALL chunks for a document
-        // fail, old embeddings survive instead of leaving zero data.
-
         for (chunk_index, text) in chunks {
             all_chunks.push(ChunkWork {
                 doc_id: doc.document_id,
@@ -190,15 +157,10 @@ async fn embed_page(
         }
 
         page_normal_docs += 1;
-        // Don't fire progress here — wait until embedding completes below.
     }
 
-    // Track documents whose old embeddings have been cleared.
-    // We defer clearing until the first successful chunk embedding so
-    // that if ALL chunks for a document fail, old embeddings survive.
     let mut cleared_docs: HashSet<i64> = HashSet::new();
 
-    // Process chunks in batches of BATCH_SIZE
     for batch in all_chunks.chunks(BATCH_SIZE) {
         let texts: Vec<String> = batch.iter().map(|c| c.text.clone()).collect();
 
@@ -235,7 +197,6 @@ async fn embed_page(
                         continue;
                     }
 
-                    // Clear old embeddings on first successful chunk for this document
                     if !cleared_docs.contains(&chunk.doc_id) {
                         clear_document_embeddings(conn, chunk.doc_id)?;
                         cleared_docs.insert(chunk.doc_id);
@@ -255,12 +216,8 @@ async fn embed_page(
                 }
             }
             Err(e) => {
-                // Batch failed — retry each chunk individually so one
-                // oversized chunk doesn't poison the entire batch.
                 let err_str = e.to_string();
                 let err_lower = err_str.to_lowercase();
-                // Ollama error messages vary across versions. Match broadly
-                // against known patterns to detect context-window overflow.
                 let is_context_error = err_lower.contains("context length")
                     || err_lower.contains("too long")
                     || err_lower.contains("maximum context")
@@ -276,7 +233,6 @@ async fn embed_page(
                                 if !embeddings.is_empty()
                                     && embeddings[0].len() == EXPECTED_DIMS =>
                             {
-                                // Clear old embeddings on first successful chunk
                                 if !cleared_docs.contains(&chunk.doc_id) {
                                     clear_document_embeddings(conn, chunk.doc_id)?;
                                     cleared_docs.insert(chunk.doc_id);
@@ -333,8 +289,6 @@ async fn embed_page(
         }
     }
 
-    // Fire progress for all normal documents after embedding completes.
-    // This ensures progress reflects actual embedding work, not just chunking.
     *processed += page_normal_docs;
     if let Some(cb) = progress_callback {
         cb(*processed, total);
@@ -343,7 +297,6 @@ async fn embed_page(
     Ok(())
 }
 
-/// Clear all embeddings and metadata for a document.
 fn clear_document_embeddings(conn: &Connection, document_id: i64) -> Result<()> {
     conn.execute(
         "DELETE FROM embedding_metadata WHERE document_id = ?1",
@@ -360,7 +313,6 @@ fn clear_document_embeddings(conn: &Connection, document_id: i64) -> Result<()>
     Ok(())
 }
 
-/// Store an embedding vector and its metadata.
 #[allow(clippy::too_many_arguments)]
 fn store_embedding(
     conn: &Connection,
@@ -384,7 +336,6 @@ fn store_embedding(
         rusqlite::params![rowid, embedding_bytes],
     )?;
 
-    // Only store chunk_count on the sentinel row (chunk_index=0)
     let chunk_count: Option<i64> = if chunk_index == 0 {
         Some(total_chunks as i64)
     } else {
@@ -413,7 +364,6 @@ fn store_embedding(
     Ok(())
 }
 
-/// Record an embedding error in metadata for later retry.
 fn record_embedding_error(
     conn: &Connection,
     doc_id: i64,
diff --git a/src/gitlab/transformers/discussion.rs b/src/gitlab/transformers/discussion.rs
index 32d352a..aa40798 100644
--- a/src/gitlab/transformers/discussion.rs
+++ b/src/gitlab/transformers/discussion.rs
@@ -1,66 +1,57 @@
-//! Discussion and note transformers: convert GitLab discussions to local schema.
-
 use tracing::warn;
 
 use crate::core::time::{iso_to_ms, iso_to_ms_strict, now_ms};
 use crate::gitlab::types::{GitLabDiscussion, GitLabNote};
 
-/// Reference to the parent noteable (Issue or MergeRequest).
-/// Uses an enum to prevent accidentally mixing up issue vs MR IDs at compile time.
 #[derive(Debug, Clone, Copy)]
 pub enum NoteableRef {
     Issue(i64),
     MergeRequest(i64),
 }
 
-/// Normalized discussion for local storage.
 #[derive(Debug, Clone)]
 pub struct NormalizedDiscussion {
     pub gitlab_discussion_id: String,
     pub project_id: i64,
     pub issue_id: Option<i64>,
     pub merge_request_id: Option<i64>,
-    pub noteable_type: String, // "Issue" or "MergeRequest"
+    pub noteable_type: String,
     pub individual_note: bool,
-    pub first_note_at: Option<i64>, // min(note.created_at) in ms epoch
-    pub last_note_at: Option<i64>,  // max(note.created_at) in ms epoch
+    pub first_note_at: Option<i64>,
+    pub last_note_at: Option<i64>,
     pub last_seen_at: i64,
-    pub resolvable: bool, // any note is resolvable
-    pub resolved: bool,   // all resolvable notes are resolved
+    pub resolvable: bool,
+    pub resolved: bool,
 }
 
-/// Normalized note for local storage.
 #[derive(Debug, Clone)]
 pub struct NormalizedNote {
     pub gitlab_id: i64,
     pub project_id: i64,
-    pub note_type: Option<String>, // "DiscussionNote" | "DiffNote" | null
+    pub note_type: Option<String>,
     pub is_system: bool,
     pub author_username: String,
     pub body: String,
-    pub created_at: i64, // ms epoch
-    pub updated_at: i64, // ms epoch
+    pub created_at: i64,
+    pub updated_at: i64,
     pub last_seen_at: i64,
-    pub position: i32, // 0-indexed array position
+    pub position: i32,
     pub resolvable: bool,
     pub resolved: bool,
     pub resolved_by: Option<String>,
     pub resolved_at: Option<i64>,
-    // DiffNote position fields (CP1 - basic path/line)
     pub position_old_path: Option<String>,
     pub position_new_path: Option<String>,
     pub position_old_line: Option<i32>,
     pub position_new_line: Option<i32>,
-    // DiffNote extended position fields (CP2)
-    pub position_type: Option<String>, // "text" | "image" | "file"
-    pub position_line_range_start: Option<i32>, // multi-line comment start
-    pub position_line_range_end: Option<i32>, // multi-line comment end
-    pub position_base_sha: Option<String>, // Base commit SHA for diff
-    pub position_start_sha: Option<String>, // Start commit SHA for diff
-    pub position_head_sha: Option<String>, // Head commit SHA for diff
+    pub position_type: Option<String>,
+    pub position_line_range_start: Option<i32>,
+    pub position_line_range_end: Option<i32>,
+    pub position_base_sha: Option<String>,
+    pub position_start_sha: Option<String>,
+    pub position_head_sha: Option<String>,
 }
 
-/// Parse ISO 8601 timestamp to milliseconds, defaulting to 0 on failure.
 fn parse_timestamp(ts: &str) -> i64 {
     match iso_to_ms(ts) {
         Some(ms) => ms,
@@ -71,7 +62,6 @@ fn parse_timestamp(ts: &str) -> i64 {
     }
 }
 
-/// Transform a GitLab discussion into normalized schema.
 pub fn transform_discussion(
     gitlab_discussion: &GitLabDiscussion,
     local_project_id: i64,
@@ -79,13 +69,11 @@ pub fn transform_discussion(
 ) -> NormalizedDiscussion {
     let now = now_ms();
 
-    // Derive issue_id, merge_request_id, and noteable_type from the enum
     let (issue_id, merge_request_id, noteable_type) = match noteable {
         NoteableRef::Issue(id) => (Some(id), None, "Issue"),
         NoteableRef::MergeRequest(id) => (None, Some(id), "MergeRequest"),
     };
 
-    // Compute first_note_at and last_note_at from notes
     let note_timestamps: Vec<i64> = gitlab_discussion
         .notes
         .iter()
@@ -95,10 +83,8 @@ pub fn transform_discussion(
     let first_note_at = note_timestamps.iter().min().copied();
     let last_note_at = note_timestamps.iter().max().copied();
 
-    // Compute resolvable: any note is resolvable
     let resolvable = gitlab_discussion.notes.iter().any(|n| n.resolvable);
 
-    // Compute resolved: all resolvable notes are resolved
     let resolved = if resolvable {
         gitlab_discussion
             .notes
@@ -124,8 +110,6 @@ pub fn transform_discussion(
     }
 }
 
-/// Transform a GitLab discussion for MR context.
-/// Convenience wrapper that uses NoteableRef::MergeRequest internally.
 pub fn transform_mr_discussion(
     gitlab_discussion: &GitLabDiscussion,
     local_project_id: i64,
@@ -138,7 +122,6 @@ pub fn transform_mr_discussion(
     )
 }
 
-/// Transform notes from a GitLab discussion into normalized schema.
 pub fn transform_notes(
     gitlab_discussion: &GitLabDiscussion,
     local_project_id: i64,
@@ -159,7 +142,6 @@ fn transform_single_note(
     position: i32,
     now: i64,
 ) -> NormalizedNote {
-    // Extract DiffNote position fields if present
     let (
         position_old_path,
         position_new_path,
@@ -201,8 +183,6 @@ fn transform_single_note(
     }
 }
 
-/// Extract DiffNote position fields from GitLabNotePosition.
-/// Returns tuple of all position fields (all None if position is None).
 #[allow(clippy::type_complexity)]
 fn extract_position_fields(
     position: &Option<crate::gitlab::types::GitLabNotePosition>,
@@ -240,8 +220,6 @@ fn extract_position_fields(
     }
 }
 
-/// Transform notes from a GitLab discussion with strict timestamp parsing.
-/// Returns Err if any timestamp is invalid - no silent fallback to 0.
 pub fn transform_notes_with_diff_position(
     gitlab_discussion: &GitLabDiscussion,
     local_project_id: i64,
@@ -262,7 +240,6 @@ fn transform_single_note_strict(
     position: i32,
     now: i64,
 ) -> Result<NormalizedNote, String> {
-    // Parse timestamps with strict error handling
     let created_at = iso_to_ms_strict(&note.created_at)?;
     let updated_at = iso_to_ms_strict(&note.updated_at)?;
     let resolved_at = match &note.resolved_at {
@@ -270,7 +247,6 @@ fn transform_single_note_strict(
         None => None,
     };
 
-    // Extract DiffNote position fields if present
     let (
         position_old_path,
         position_new_path,
@@ -448,7 +424,7 @@ mod tests {
             false,
             vec![
                 make_test_note(1, "2024-01-16T09:00:00.000Z", false, false, false),
-                make_test_note(2, "2024-01-16T09:00:00.000Z", true, false, false), // system note
+                make_test_note(2, "2024-01-16T09:00:00.000Z", true, false, false),
             ],
         );
 
@@ -482,16 +458,14 @@ mod tests {
             false,
             vec![
                 make_test_note(1, "2024-01-16T09:00:00.000Z", false, false, false),
-                make_test_note(2, "2024-01-16T11:00:00.000Z", false, false, false), // latest
+                make_test_note(2, "2024-01-16T11:00:00.000Z", false, false, false),
                 make_test_note(3, "2024-01-16T10:00:00.000Z", false, false, false),
             ],
         );
 
         let result = transform_discussion(&discussion, 100, NoteableRef::Issue(42));
 
-        // first_note_at should be 09:00 (note 1)
         assert_eq!(result.first_note_at, Some(1705395600000));
-        // last_note_at should be 11:00 (note 2)
         assert_eq!(result.last_note_at, Some(1705402800000));
     }
 
@@ -527,7 +501,7 @@ mod tests {
         let resolvable = make_test_discussion(
             false,
             vec![
-                make_test_note(1, "2024-01-16T09:00:00.000Z", false, true, false), // resolvable
+                make_test_note(1, "2024-01-16T09:00:00.000Z", false, true, false),
                 make_test_note(2, "2024-01-16T10:00:00.000Z", false, false, false),
             ],
         );
@@ -538,16 +512,14 @@ mod tests {
 
     #[test]
     fn computes_resolved_only_when_all_resolvable_notes_resolved() {
-        // Mix of resolved/unresolved - not resolved
         let partial = make_test_discussion(
             false,
             vec![
-                make_test_note(1, "2024-01-16T09:00:00.000Z", false, true, true), // resolved
-                make_test_note(2, "2024-01-16T10:00:00.000Z", false, true, false), // not resolved
+                make_test_note(1, "2024-01-16T09:00:00.000Z", false, true, true),
+                make_test_note(2, "2024-01-16T10:00:00.000Z", false, true, false),
             ],
         );
 
-        // All resolvable notes resolved
         let fully_resolved = make_test_discussion(
             false,
             vec![
@@ -556,7 +528,6 @@ mod tests {
             ],
         );
 
-        // No resolvable notes - resolved should be false
         let no_resolvable = make_test_discussion(
             false,
             vec![make_test_note(
diff --git a/src/gitlab/transformers/issue.rs b/src/gitlab/transformers/issue.rs
index c18de78..fc6d28d 100644
--- a/src/gitlab/transformers/issue.rs
+++ b/src/gitlab/transformers/issue.rs
@@ -1,5 +1,3 @@
-//! Issue transformer: converts GitLabIssue to local schema.
-
 use chrono::DateTime;
 use thiserror::Error;
 
@@ -11,7 +9,6 @@ pub enum TransformError {
     TimestampParse(String, String),
 }
 
-/// Local schema representation of an issue row.
 #[derive(Debug, Clone)]
 pub struct IssueRow {
     pub gitlab_id: i64,
@@ -21,14 +18,13 @@ pub struct IssueRow {
     pub description: Option<String>,
     pub state: String,
     pub author_username: String,
-    pub created_at: i64, // ms epoch UTC
-    pub updated_at: i64, // ms epoch UTC
+    pub created_at: i64,
+    pub updated_at: i64,
     pub web_url: String,
-    pub due_date: Option<String>,        // YYYY-MM-DD
-    pub milestone_title: Option<String>, // Denormalized for quick display
+    pub due_date: Option<String>,
+    pub milestone_title: Option<String>,
 }
 
-/// Local schema representation of a milestone row.
 #[derive(Debug, Clone)]
 pub struct MilestoneRow {
     pub gitlab_id: i64,
@@ -41,7 +37,6 @@ pub struct MilestoneRow {
     pub web_url: Option<String>,
 }
 
-/// Issue bundled with extracted metadata.
 #[derive(Debug, Clone)]
 pub struct IssueWithMetadata {
     pub issue: IssueRow,
@@ -50,14 +45,12 @@ pub struct IssueWithMetadata {
     pub milestone: Option<MilestoneRow>,
 }
 
-/// Parse ISO 8601 timestamp to milliseconds since Unix epoch.
 fn parse_timestamp(ts: &str) -> Result<i64, TransformError> {
     DateTime::parse_from_rfc3339(ts)
         .map(|dt| dt.timestamp_millis())
         .map_err(|e| TransformError::TimestampParse(ts.to_string(), e.to_string()))
 }
 
-/// Transform a GitLab issue into local schema format.
 pub fn transform_issue(issue: &GitLabIssue) -> Result<IssueWithMetadata, TransformError> {
     let created_at = parse_timestamp(&issue.created_at)?;
     let updated_at = parse_timestamp(&issue.updated_at)?;
@@ -182,20 +175,16 @@ mod tests {
         let issue = make_test_issue();
         let result = transform_issue(&issue).unwrap();
 
-        // 2024-01-15T10:00:00.000Z = 1705312800000 ms
         assert_eq!(result.issue.created_at, 1705312800000);
-        // 2024-01-20T15:30:00.000Z = 1705764600000 ms
         assert_eq!(result.issue.updated_at, 1705764600000);
     }
 
     #[test]
     fn handles_timezone_offset_timestamps() {
         let mut issue = make_test_issue();
-        // GitLab can return timestamps with timezone offset
         issue.created_at = "2024-01-15T05:00:00-05:00".to_string();
 
         let result = transform_issue(&issue).unwrap();
-        // 05:00 EST = 10:00 UTC = same as original test
         assert_eq!(result.issue.created_at, 1705312800000);
     }
 
@@ -237,10 +226,8 @@ mod tests {
 
         let result = transform_issue(&issue).unwrap();
 
-        // Denormalized title on issue for quick display
         assert_eq!(result.issue.milestone_title, Some("v1.0".to_string()));
 
-        // Full milestone row for normalized storage
         let milestone = result.milestone.expect("should have milestone");
         assert_eq!(milestone.gitlab_id, 500);
         assert_eq!(milestone.iid, 5);
diff --git a/src/gitlab/transformers/merge_request.rs b/src/gitlab/transformers/merge_request.rs
index 3654c02..0cb0470 100644
--- a/src/gitlab/transformers/merge_request.rs
+++ b/src/gitlab/transformers/merge_request.rs
@@ -1,9 +1,6 @@
-//! Merge request transformer: converts GitLabMergeRequest to local schema.
-
 use crate::core::time::{iso_to_ms_opt_strict, iso_to_ms_strict, now_ms};
 use crate::gitlab::types::GitLabMergeRequest;
 
-/// Local schema representation of a merge request row.
 #[derive(Debug, Clone)]
 pub struct NormalizedMergeRequest {
     pub gitlab_id: i64,
@@ -21,15 +18,14 @@ pub struct NormalizedMergeRequest {
     pub references_full: Option<String>,
     pub detailed_merge_status: Option<String>,
     pub merge_user_username: Option<String>,
-    pub created_at: i64,        // ms epoch UTC
-    pub updated_at: i64,        // ms epoch UTC
-    pub merged_at: Option<i64>, // ms epoch UTC
-    pub closed_at: Option<i64>, // ms epoch UTC
-    pub last_seen_at: i64,      // ms epoch UTC
+    pub created_at: i64,
+    pub updated_at: i64,
+    pub merged_at: Option<i64>,
+    pub closed_at: Option<i64>,
+    pub last_seen_at: i64,
     pub web_url: String,
 }
 
-/// Merge request bundled with extracted metadata.
 #[derive(Debug, Clone)]
 pub struct MergeRequestWithMetadata {
     pub merge_request: NormalizedMergeRequest,
@@ -38,61 +34,43 @@ pub struct MergeRequestWithMetadata {
     pub reviewer_usernames: Vec<String>,
 }
 
-/// Transform a GitLab merge request into local schema format.
-///
-/// # Arguments
-/// * `gitlab_mr` - The GitLab MR API response
-/// * `local_project_id` - The local database project ID (not GitLab's project_id)
-///
-/// # Returns
-/// * `Ok(MergeRequestWithMetadata)` - Transformed MR with extracted metadata
-/// * `Err(String)` - Error message if transformation fails (e.g., invalid timestamps)
 pub fn transform_merge_request(
     gitlab_mr: &GitLabMergeRequest,
     local_project_id: i64,
 ) -> Result<MergeRequestWithMetadata, String> {
-    // Parse required timestamps
     let created_at = iso_to_ms_strict(&gitlab_mr.created_at)?;
     let updated_at = iso_to_ms_strict(&gitlab_mr.updated_at)?;
 
-    // Parse optional timestamps
     let merged_at = iso_to_ms_opt_strict(&gitlab_mr.merged_at)?;
     let closed_at = iso_to_ms_opt_strict(&gitlab_mr.closed_at)?;
 
-    // Draft: prefer draft, fallback to work_in_progress
     let is_draft = gitlab_mr.draft || gitlab_mr.work_in_progress;
 
-    // Merge status: prefer detailed_merge_status over legacy
     let detailed_merge_status = gitlab_mr
         .detailed_merge_status
         .clone()
         .or_else(|| gitlab_mr.merge_status_legacy.clone());
 
-    // Merge user: prefer merge_user over merged_by
     let merge_user_username = gitlab_mr
         .merge_user
         .as_ref()
         .map(|u| u.username.clone())
         .or_else(|| gitlab_mr.merged_by.as_ref().map(|u| u.username.clone()));
 
-    // References extraction
     let (references_short, references_full) = gitlab_mr
         .references
         .as_ref()
         .map(|r| (Some(r.short.clone()), Some(r.full.clone())))
         .unwrap_or((None, None));
 
-    // Head SHA
     let head_sha = gitlab_mr.sha.clone();
 
-    // Extract assignee usernames
     let assignee_usernames: Vec<String> = gitlab_mr
         .assignees
         .iter()
         .map(|a| a.username.clone())
         .collect();
 
-    // Extract reviewer usernames
     let reviewer_usernames: Vec<String> = gitlab_mr
         .reviewers
         .iter()
diff --git a/src/gitlab/transformers/mod.rs b/src/gitlab/transformers/mod.rs
index 55f0925..8c64edb 100644
--- a/src/gitlab/transformers/mod.rs
+++ b/src/gitlab/transformers/mod.rs
@@ -1,5 +1,3 @@
-//! Transformers for converting GitLab API responses to local schema.
-
 pub mod discussion;
 pub mod issue;
 pub mod merge_request;
diff --git a/src/ingestion/dirty_tracker.rs b/src/ingestion/dirty_tracker.rs
index 635d052..9809021 100644
--- a/src/ingestion/dirty_tracker.rs
+++ b/src/ingestion/dirty_tracker.rs
@@ -7,8 +7,6 @@ use crate::documents::SourceType;
 
 const DIRTY_SOURCES_BATCH_SIZE: usize = 500;
 
-/// Mark a source entity as dirty INSIDE an existing transaction.
-/// ON CONFLICT resets ALL backoff/error state so fresh updates are immediately eligible.
 pub fn mark_dirty_tx(
     tx: &rusqlite::Transaction<'_>,
     source_type: SourceType,
@@ -28,7 +26,6 @@ pub fn mark_dirty_tx(
     Ok(())
 }
 
-/// Convenience wrapper for non-transactional contexts.
 pub fn mark_dirty(conn: &Connection, source_type: SourceType, source_id: i64) -> Result<()> {
     conn.execute(
         "INSERT INTO dirty_sources (source_type, source_id, queued_at)
@@ -44,9 +41,6 @@ pub fn mark_dirty(conn: &Connection, source_type: SourceType, source_id: i64) ->
     Ok(())
 }
 
-/// Get dirty sources ready for processing.
-/// Returns entries where next_attempt_at is NULL or <= now.
-/// Orders by attempt_count ASC (fresh before failed), then queued_at ASC.
 pub fn get_dirty_sources(conn: &Connection) -> Result<Vec<(SourceType, i64)>> {
     let now = now_ms();
     let mut stmt = conn.prepare(
@@ -79,7 +73,6 @@ pub fn get_dirty_sources(conn: &Connection) -> Result<Vec<(SourceType, i64)>> {
     Ok(results)
 }
 
-/// Clear dirty entry after successful processing.
 pub fn clear_dirty(conn: &Connection, source_type: SourceType, source_id: i64) -> Result<()> {
     conn.execute(
         "DELETE FROM dirty_sources WHERE source_type = ?1 AND source_id = ?2",
@@ -88,7 +81,6 @@ pub fn clear_dirty(conn: &Connection, source_type: SourceType, source_id: i64) -
     Ok(())
 }
 
-/// Record an error for a dirty source, incrementing attempt_count and setting backoff.
 pub fn record_dirty_error(
     conn: &Connection,
     source_type: SourceType,
@@ -96,7 +88,6 @@ pub fn record_dirty_error(
     error: &str,
 ) -> Result<()> {
     let now = now_ms();
-    // Get current attempt_count first
     let attempt_count: i64 = conn.query_row(
         "SELECT attempt_count FROM dirty_sources WHERE source_type = ?1 AND source_id = ?2",
         rusqlite::params![source_type.as_str(), source_id],
@@ -176,7 +167,6 @@ mod tests {
     fn test_requeue_resets_backoff() {
         let conn = setup_db();
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
-        // Simulate error state
         record_dirty_error(&conn, SourceType::Issue, 1, "test error").unwrap();
 
         let attempt: i64 = conn
@@ -188,7 +178,6 @@ mod tests {
             .unwrap();
         assert_eq!(attempt, 1);
 
-        // Re-mark should reset
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
         let attempt: i64 = conn
             .query_row(
@@ -213,7 +202,6 @@ mod tests {
     fn test_get_respects_backoff() {
         let conn = setup_db();
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
-        // Set next_attempt_at far in the future
         conn.execute(
             "UPDATE dirty_sources SET next_attempt_at = 9999999999999 WHERE source_id = 1",
             [],
@@ -227,20 +215,18 @@ mod tests {
     #[test]
     fn test_get_orders_by_attempt_count() {
         let conn = setup_db();
-        // Insert issue 1 (failed, attempt_count=2)
         mark_dirty(&conn, SourceType::Issue, 1).unwrap();
         conn.execute(
             "UPDATE dirty_sources SET attempt_count = 2 WHERE source_id = 1",
             [],
         )
         .unwrap();
-        // Insert issue 2 (fresh, attempt_count=0)
         mark_dirty(&conn, SourceType::Issue, 2).unwrap();
 
         let results = get_dirty_sources(&conn).unwrap();
         assert_eq!(results.len(), 2);
-        assert_eq!(results[0].1, 2); // Fresh first
-        assert_eq!(results[1].1, 1); // Failed second
+        assert_eq!(results[0].1, 2);
+        assert_eq!(results[1].1, 1);
     }
 
     #[test]
diff --git a/src/ingestion/discussion_queue.rs b/src/ingestion/discussion_queue.rs
index 7b4f5fa..c31e023 100644
--- a/src/ingestion/discussion_queue.rs
+++ b/src/ingestion/discussion_queue.rs
@@ -4,7 +4,6 @@ use crate::core::backoff::compute_next_attempt_at;
 use crate::core::error::Result;
 use crate::core::time::now_ms;
 
-/// Noteable type for discussion queue.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum NoteableType {
     Issue,
@@ -28,7 +27,6 @@ impl NoteableType {
     }
 }
 
-/// A pending discussion fetch entry.
 pub struct PendingFetch {
     pub project_id: i64,
     pub noteable_type: NoteableType,
@@ -36,7 +34,6 @@ pub struct PendingFetch {
     pub attempt_count: i32,
 }
 
-/// Queue a discussion fetch. ON CONFLICT resets backoff (consistent with dirty_sources).
 pub fn queue_discussion_fetch(
     conn: &Connection,
     project_id: i64,
@@ -57,7 +54,6 @@ pub fn queue_discussion_fetch(
     Ok(())
 }
 
-/// Get next batch of pending fetches (WHERE next_attempt_at IS NULL OR <= now).
 pub fn get_pending_fetches(conn: &Connection, limit: usize) -> Result<Vec<PendingFetch>> {
     let now = now_ms();
     let mut stmt = conn.prepare(
@@ -96,7 +92,6 @@ pub fn get_pending_fetches(conn: &Connection, limit: usize) -> Result<Vec<Pendin
     Ok(results)
 }
 
-/// Mark fetch complete (remove from queue).
 pub fn complete_fetch(
     conn: &Connection,
     project_id: i64,
@@ -111,7 +106,6 @@ pub fn complete_fetch(
     Ok(())
 }
 
-/// Record fetch error with backoff.
 pub fn record_fetch_error(
     conn: &Connection,
     project_id: i64,
@@ -213,7 +207,6 @@ mod tests {
             .unwrap();
         assert_eq!(attempt, 1);
 
-        // Re-queue should reset
         queue_discussion_fetch(&conn, 1, NoteableType::Issue, 42).unwrap();
         let attempt: i32 = conn
             .query_row(
diff --git a/src/ingestion/discussions.rs b/src/ingestion/discussions.rs
index 4f08546..f406c10 100644
--- a/src/ingestion/discussions.rs
+++ b/src/ingestion/discussions.rs
@@ -1,11 +1,3 @@
-//! Discussion ingestion with full-refresh strategy.
-//!
-//! Fetches discussions for an issue and stores them locally with:
-//! - Raw payload storage with deduplication
-//! - Full discussion and note replacement per issue
-//! - Sync timestamp tracking per issue
-//! - Safe stale removal only after successful pagination
-
 use futures::StreamExt;
 use rusqlite::Connection;
 use tracing::{debug, warn};
@@ -20,7 +12,6 @@ use crate::ingestion::dirty_tracker;
 
 use super::issues::IssueForDiscussionSync;
 
-/// Result of discussion ingestion for a single issue.
 #[derive(Debug, Default)]
 pub struct IngestDiscussionsResult {
     pub discussions_fetched: usize,
@@ -29,7 +20,6 @@ pub struct IngestDiscussionsResult {
     pub stale_discussions_removed: usize,
 }
 
-/// Ingest discussions for a list of issues that need sync.
 pub async fn ingest_issue_discussions(
     conn: &Connection,
     client: &GitLabClient,
@@ -69,7 +59,6 @@ pub async fn ingest_issue_discussions(
     Ok(total_result)
 }
 
-/// Ingest discussions for a single issue.
 async fn ingest_discussions_for_issue(
     conn: &Connection,
     client: &GitLabClient,
@@ -86,16 +75,12 @@ async fn ingest_discussions_for_issue(
         "Fetching discussions for issue"
     );
 
-    // Stream discussions from GitLab
     let mut discussions_stream = client.paginate_issue_discussions(gitlab_project_id, issue.iid);
 
-    // Track discussions we've seen for stale removal
     let mut seen_discussion_ids: Vec<String> = Vec::new();
-    // Track if any error occurred during pagination
     let mut pagination_error: Option<crate::core::error::LoreError> = None;
 
     while let Some(disc_result) = discussions_stream.next().await {
-        // Handle errors - record but don't delete stale data
         let gitlab_discussion = match disc_result {
             Ok(d) => d,
             Err(e) => {
@@ -110,7 +95,6 @@ async fn ingest_discussions_for_issue(
         };
         result.discussions_fetched += 1;
 
-        // Store raw payload
         let payload_bytes = serde_json::to_vec(&gitlab_discussion)?;
         let payload_id = store_payload(
             conn,
@@ -123,55 +107,43 @@ async fn ingest_discussions_for_issue(
             },
         )?;
 
-        // Transform and store discussion
         let normalized = transform_discussion(
             &gitlab_discussion,
             local_project_id,
             NoteableRef::Issue(issue.local_issue_id),
         );
 
-        // Wrap all discussion+notes operations in a transaction for atomicity
         let tx = conn.unchecked_transaction()?;
 
         upsert_discussion(&tx, &normalized, payload_id)?;
 
-        // Get local discussion ID
         let local_discussion_id: i64 = tx.query_row(
             "SELECT id FROM discussions WHERE project_id = ? AND gitlab_discussion_id = ?",
             (local_project_id, &normalized.gitlab_discussion_id),
             |row| row.get(0),
         )?;
 
-        // Mark dirty for document regeneration (inside transaction)
         dirty_tracker::mark_dirty_tx(&tx, SourceType::Discussion, local_discussion_id)?;
 
-        // Transform and store notes
         let notes = transform_notes(&gitlab_discussion, local_project_id);
         let notes_count = notes.len();
 
-        // Delete existing notes for this discussion (full refresh)
         tx.execute(
             "DELETE FROM notes WHERE discussion_id = ?",
             [local_discussion_id],
         )?;
 
         for note in notes {
-            // Note: per-note raw payload storage is skipped because the discussion
-            // payload (already stored above) contains all notes. The full note
-            // content is also stored in the notes table itself.
             insert_note(&tx, local_discussion_id, &note, None)?;
         }
 
         tx.commit()?;
 
-        // Increment counters AFTER successful commit to keep metrics honest
         result.discussions_upserted += 1;
         result.notes_upserted += notes_count;
         seen_discussion_ids.push(normalized.gitlab_discussion_id.clone());
     }
 
-    // Only remove stale discussions and advance watermark if pagination completed
-    // without errors. Safe for both empty results and populated results.
     if pagination_error.is_none() {
         let removed = remove_stale_discussions(conn, issue.local_issue_id, &seen_discussion_ids)?;
         result.stale_discussions_removed = removed;
@@ -189,7 +161,6 @@ async fn ingest_discussions_for_issue(
     Ok(result)
 }
 
-/// Upsert a discussion.
 fn upsert_discussion(
     conn: &Connection,
     discussion: &crate::gitlab::transformers::NormalizedDiscussion,
@@ -226,7 +197,6 @@ fn upsert_discussion(
     Ok(())
 }
 
-/// Insert a note.
 fn insert_note(
     conn: &Connection,
     discussion_id: i64,
@@ -261,35 +231,26 @@ fn insert_note(
     Ok(())
 }
 
-/// Remove discussions that were not seen in this fetch (stale removal).
-/// Chunks large sets to avoid SQL query size limits.
 fn remove_stale_discussions(
     conn: &Connection,
     issue_id: i64,
     seen_ids: &[String],
 ) -> Result<usize> {
     if seen_ids.is_empty() {
-        // No discussions seen - remove all for this issue
         let deleted = conn.execute("DELETE FROM discussions WHERE issue_id = ?", [issue_id])?;
         return Ok(deleted);
     }
 
-    // SQLite has a limit of 999 variables per query by default
-    // Chunk the seen_ids to stay well under this limit
     const CHUNK_SIZE: usize = 500;
 
-    // For safety, use a temp table approach for large sets
     let total_deleted = if seen_ids.len() > CHUNK_SIZE {
-        // Create temp table for seen IDs
         conn.execute(
             "CREATE TEMP TABLE IF NOT EXISTS _temp_seen_discussions (id TEXT PRIMARY KEY)",
             [],
         )?;
 
-        // Clear any previous data
         conn.execute("DELETE FROM _temp_seen_discussions", [])?;
 
-        // Insert seen IDs in chunks
         for chunk in seen_ids.chunks(CHUNK_SIZE) {
             let placeholders: Vec<&str> = chunk.iter().map(|_| "(?)").collect();
             let sql = format!(
@@ -302,7 +263,6 @@ fn remove_stale_discussions(
             conn.execute(&sql, params.as_slice())?;
         }
 
-        // Delete discussions not in temp table
         let deleted = conn.execute(
             "DELETE FROM discussions
              WHERE issue_id = ?1
@@ -310,11 +270,9 @@ fn remove_stale_discussions(
             [issue_id],
         )?;
 
-        // Clean up temp table
         conn.execute("DROP TABLE IF EXISTS _temp_seen_discussions", [])?;
         deleted
     } else {
-        // Small set - use simple IN clause
         let placeholders: Vec<&str> = seen_ids.iter().map(|_| "?").collect();
         let sql = format!(
             "DELETE FROM discussions WHERE issue_id = ?1 AND gitlab_discussion_id NOT IN ({})",
@@ -333,7 +291,6 @@ fn remove_stale_discussions(
     Ok(total_deleted)
 }
 
-/// Update the discussions_synced_for_updated_at timestamp on an issue.
 fn update_issue_sync_timestamp(conn: &Connection, issue_id: i64, updated_at: i64) -> Result<()> {
     conn.execute(
         "UPDATE issues SET discussions_synced_for_updated_at = ? WHERE id = ?",
diff --git a/src/ingestion/issues.rs b/src/ingestion/issues.rs
index 0903cc9..374f51c 100644
--- a/src/ingestion/issues.rs
+++ b/src/ingestion/issues.rs
@@ -1,12 +1,3 @@
-//! Issue ingestion with cursor-based incremental sync.
-//!
-//! Fetches issues from GitLab and stores them locally with:
-//! - Cursor-based pagination for incremental sync
-//! - Raw payload storage with deduplication
-//! - Label extraction and stale-link removal
-//! - Milestone normalization with dedicated table
-//! - Tracking of issues needing discussion sync
-
 use std::ops::Deref;
 
 use futures::StreamExt;
@@ -23,7 +14,6 @@ use crate::gitlab::transformers::{MilestoneRow, transform_issue};
 use crate::gitlab::types::GitLabIssue;
 use crate::ingestion::dirty_tracker;
 
-/// Result of issue ingestion.
 #[derive(Debug, Default)]
 pub struct IngestIssuesResult {
     pub fetched: usize,
@@ -32,36 +22,31 @@ pub struct IngestIssuesResult {
     pub issues_needing_discussion_sync: Vec<IssueForDiscussionSync>,
 }
 
-/// Issue that needs discussion sync.
 #[derive(Debug, Clone)]
 pub struct IssueForDiscussionSync {
     pub local_issue_id: i64,
     pub iid: i64,
-    pub updated_at: i64, // ms epoch
+    pub updated_at: i64,
 }
 
-/// Cursor state for incremental sync.
 #[derive(Debug, Default)]
 struct SyncCursor {
     updated_at_cursor: Option<i64>,
     tie_breaker_id: Option<i64>,
 }
 
-/// Ingest issues for a project.
 pub async fn ingest_issues(
     conn: &Connection,
     client: &GitLabClient,
     config: &Config,
-    project_id: i64,        // Local DB project ID
-    gitlab_project_id: i64, // GitLab project ID
+    project_id: i64,
+    gitlab_project_id: i64,
 ) -> Result<IngestIssuesResult> {
     let mut result = IngestIssuesResult::default();
 
-    // 1. Get current cursor
     let cursor = get_sync_cursor(conn, project_id)?;
     debug!(?cursor, "Starting issue ingestion with cursor");
 
-    // 2. Stream issues with cursor rewind
     let mut issues_stream = client.paginate_issues(
         gitlab_project_id,
         cursor.updated_at_cursor,
@@ -72,12 +57,10 @@ pub async fn ingest_issues(
     let mut last_updated_at: Option<i64> = None;
     let mut last_gitlab_id: Option<i64> = None;
 
-    // 3. Process each issue
     while let Some(issue_result) = issues_stream.next().await {
         let issue = issue_result?;
         result.fetched += 1;
 
-        // Parse timestamp early - skip issues with invalid timestamps
         let issue_updated_at = match parse_timestamp(&issue.updated_at) {
             Ok(ts) => ts,
             Err(e) => {
@@ -90,23 +73,19 @@ pub async fn ingest_issues(
             }
         };
 
-        // Apply local cursor filter (skip already-processed due to rewind overlap)
         if !passes_cursor_filter_with_ts(issue.id, issue_updated_at, &cursor) {
             debug!(gitlab_id = issue.id, "Skipping already-processed issue");
             continue;
         }
 
-        // Transform and store
         let labels_created = process_single_issue(conn, config, project_id, &issue)?;
         result.upserted += 1;
         result.labels_created += labels_created;
 
-        // Track cursor position (use already-parsed timestamp)
         last_updated_at = Some(issue_updated_at);
         last_gitlab_id = Some(issue.id);
         batch_count += 1;
 
-        // Incremental cursor update every 100 issues
         if batch_count % 100 == 0
             && let (Some(ts), Some(id)) = (last_updated_at, last_gitlab_id)
         {
@@ -115,17 +94,12 @@ pub async fn ingest_issues(
         }
     }
 
-    // 4. Final cursor update
     if let (Some(ts), Some(id)) = (last_updated_at, last_gitlab_id) {
         update_sync_cursor(conn, project_id, ts, id)?;
     } else if result.fetched == 0 && cursor.updated_at_cursor.is_some() {
-        // No new issues returned, but we have an existing cursor.
-        // Update sync_attempted_at to track that we checked (useful for monitoring)
-        // The cursor itself stays the same since there's nothing newer to advance to.
         debug!("No new issues found, cursor unchanged");
     }
 
-    // 5. Find issues needing discussion sync
     result.issues_needing_discussion_sync = get_issues_needing_discussion_sync(conn, project_id)?;
 
     info!(
@@ -139,11 +113,9 @@ pub async fn ingest_issues(
     Ok(result)
 }
 
-/// Check if an issue passes the cursor filter (not already processed).
-/// Takes pre-parsed timestamp to avoid redundant parsing.
 fn passes_cursor_filter_with_ts(gitlab_id: i64, issue_ts: i64, cursor: &SyncCursor) -> bool {
     let Some(cursor_ts) = cursor.updated_at_cursor else {
-        return true; // No cursor = fetch all
+        return true;
     };
 
     if issue_ts < cursor_ts {
@@ -160,12 +132,10 @@ fn passes_cursor_filter_with_ts(gitlab_id: i64, issue_ts: i64, cursor: &SyncCurs
     true
 }
 
-// Keep the original function for backward compatibility with tests
-/// Check if an issue passes the cursor filter (not already processed).
 #[cfg(test)]
 fn passes_cursor_filter(issue: &GitLabIssue, cursor: &SyncCursor) -> Result<bool> {
     let Some(cursor_ts) = cursor.updated_at_cursor else {
-        return Ok(true); // No cursor = fetch all
+        return Ok(true);
     };
 
     let issue_ts = parse_timestamp(&issue.updated_at)?;
@@ -185,8 +155,6 @@ fn passes_cursor_filter(issue: &GitLabIssue, cursor: &SyncCursor) -> Result<bool
     Ok(true)
 }
 
-/// Process a single issue: store payload, upsert issue, handle labels.
-/// All operations are wrapped in a transaction for atomicity.
 fn process_single_issue(
     conn: &Connection,
     config: &Config,
@@ -195,12 +163,10 @@ fn process_single_issue(
 ) -> Result<usize> {
     let now = now_ms();
 
-    // Transform issue first (outside transaction - no DB access)
     let payload_bytes = serde_json::to_vec(issue)?;
     let transformed = transform_issue(issue)?;
     let issue_row = &transformed.issue;
 
-    // Wrap all DB operations in a transaction for atomicity
     let tx = conn.unchecked_transaction()?;
     let labels_created = process_issue_in_transaction(
         &tx,
@@ -219,7 +185,6 @@ fn process_single_issue(
     Ok(labels_created)
 }
 
-/// Inner function that performs all DB operations within a transaction.
 #[allow(clippy::too_many_arguments)]
 fn process_issue_in_transaction(
     tx: &Transaction<'_>,
@@ -235,7 +200,6 @@ fn process_issue_in_transaction(
 ) -> Result<usize> {
     let mut labels_created = 0;
 
-    // Store raw payload (deref Transaction to Connection for store_payload)
     let payload_id = store_payload(
         tx.deref(),
         StorePayloadOptions {
@@ -247,14 +211,12 @@ fn process_issue_in_transaction(
         },
     )?;
 
-    // Upsert milestone if present, get local ID
     let milestone_id: Option<i64> = if let Some(m) = milestone {
         Some(upsert_milestone_tx(tx, project_id, m)?)
     } else {
         None
     };
 
-    // Upsert issue (including new fields: due_date, milestone_id, milestone_title)
     tx.execute(
         "INSERT INTO issues (
             gitlab_id, project_id, iid, title, description, state,
@@ -292,35 +254,29 @@ fn process_issue_in_transaction(
         ),
     )?;
 
-    // Get local issue ID
     let local_issue_id: i64 = tx.query_row(
         "SELECT id FROM issues WHERE project_id = ? AND iid = ?",
         (project_id, issue_row.iid),
         |row| row.get(0),
     )?;
 
-    // Mark dirty for document regeneration (inside transaction)
     dirty_tracker::mark_dirty_tx(tx, SourceType::Issue, local_issue_id)?;
 
-    // Clear existing label links (stale removal)
     tx.execute(
         "DELETE FROM issue_labels WHERE issue_id = ?",
         [local_issue_id],
     )?;
 
-    // Upsert labels and create links
     for label_name in label_names {
         let label_id = upsert_label_tx(tx, project_id, label_name, &mut labels_created)?;
         link_issue_label_tx(tx, local_issue_id, label_id)?;
     }
 
-    // Clear existing assignee links (stale removal)
     tx.execute(
         "DELETE FROM issue_assignees WHERE issue_id = ?",
         [local_issue_id],
     )?;
 
-    // Insert assignees
     for username in assignee_usernames {
         tx.execute(
             "INSERT OR IGNORE INTO issue_assignees (issue_id, username) VALUES (?, ?)",
@@ -331,8 +287,6 @@ fn process_issue_in_transaction(
     Ok(labels_created)
 }
 
-/// Upsert a label within a transaction, returning its ID.
-/// Uses INSERT...ON CONFLICT...RETURNING for a single round-trip.
 fn upsert_label_tx(
     tx: &Transaction<'_>,
     project_id: i64,
@@ -347,7 +301,6 @@ fn upsert_label_tx(
         |row| row.get(0),
     )?;
 
-    // If the rowid matches last_insert_rowid, this was a new insert
     if tx.last_insert_rowid() == id {
         *created_count += 1;
     }
@@ -355,7 +308,6 @@ fn upsert_label_tx(
     Ok(id)
 }
 
-/// Link an issue to a label within a transaction.
 fn link_issue_label_tx(tx: &Transaction<'_>, issue_id: i64, label_id: i64) -> Result<()> {
     tx.execute(
         "INSERT OR IGNORE INTO issue_labels (issue_id, label_id) VALUES (?, ?)",
@@ -364,8 +316,6 @@ fn link_issue_label_tx(tx: &Transaction<'_>, issue_id: i64, label_id: i64) -> Re
     Ok(())
 }
 
-/// Upsert a milestone within a transaction, returning its local ID.
-/// Uses RETURNING to avoid a separate SELECT round-trip.
 fn upsert_milestone_tx(
     tx: &Transaction<'_>,
     project_id: i64,
@@ -398,7 +348,6 @@ fn upsert_milestone_tx(
     Ok(local_id)
 }
 
-/// Get the current sync cursor for issues.
 fn get_sync_cursor(conn: &Connection, project_id: i64) -> Result<SyncCursor> {
     let row: Option<(Option<i64>, Option<i64>)> = conn
         .query_row(
@@ -418,7 +367,6 @@ fn get_sync_cursor(conn: &Connection, project_id: i64) -> Result<SyncCursor> {
     })
 }
 
-/// Update the sync cursor.
 fn update_sync_cursor(
     conn: &Connection,
     project_id: i64,
@@ -436,7 +384,6 @@ fn update_sync_cursor(
     Ok(())
 }
 
-/// Get issues that need discussion sync (updated_at > discussions_synced_for_updated_at).
 fn get_issues_needing_discussion_sync(
     conn: &Connection,
     project_id: i64,
@@ -460,8 +407,6 @@ fn get_issues_needing_discussion_sync(
     Ok(issues?)
 }
 
-/// Parse ISO 8601 timestamp to milliseconds.
-/// Returns an error if parsing fails instead of silently returning 0.
 fn parse_timestamp(ts: &str) -> Result<i64> {
     chrono::DateTime::parse_from_rfc3339(ts)
         .map(|dt| dt.timestamp_millis())
@@ -500,11 +445,10 @@ mod tests {
     #[test]
     fn cursor_filter_allows_newer_issues() {
         let cursor = SyncCursor {
-            updated_at_cursor: Some(1705312800000), // 2024-01-15T10:00:00Z
+            updated_at_cursor: Some(1705312800000),
             tie_breaker_id: Some(100),
         };
 
-        // Issue with later timestamp passes
         let issue = make_test_issue(101, "2024-01-16T10:00:00.000Z");
         assert!(passes_cursor_filter(&issue, &cursor).unwrap_or(false));
     }
@@ -516,7 +460,6 @@ mod tests {
             tie_breaker_id: Some(100),
         };
 
-        // Issue with earlier timestamp blocked
         let issue = make_test_issue(99, "2024-01-14T10:00:00.000Z");
         assert!(!passes_cursor_filter(&issue, &cursor).unwrap_or(true));
     }
@@ -528,15 +471,12 @@ mod tests {
             tie_breaker_id: Some(100),
         };
 
-        // Same timestamp, higher ID passes
         let issue1 = make_test_issue(101, "2024-01-15T10:00:00.000Z");
         assert!(passes_cursor_filter(&issue1, &cursor).unwrap_or(false));
 
-        // Same timestamp, same ID blocked
         let issue2 = make_test_issue(100, "2024-01-15T10:00:00.000Z");
         assert!(!passes_cursor_filter(&issue2, &cursor).unwrap_or(true));
 
-        // Same timestamp, lower ID blocked
         let issue3 = make_test_issue(99, "2024-01-15T10:00:00.000Z");
         assert!(!passes_cursor_filter(&issue3, &cursor).unwrap_or(true));
     }
diff --git a/src/ingestion/merge_requests.rs b/src/ingestion/merge_requests.rs
index 29de75b..2dff3bd 100644
--- a/src/ingestion/merge_requests.rs
+++ b/src/ingestion/merge_requests.rs
@@ -1,12 +1,3 @@
-//! Merge request ingestion with cursor-based incremental sync.
-//!
-//! Fetches merge requests from GitLab and stores them locally with:
-//! - Cursor-based pagination for incremental sync
-//! - Page-boundary cursor updates for crash recovery
-//! - Raw payload storage with deduplication
-//! - Label/assignee/reviewer extraction with clear-and-relink pattern
-//! - Tracking of MRs needing discussion sync
-
 use std::ops::Deref;
 
 use rusqlite::{Connection, Transaction, params};
@@ -22,7 +13,6 @@ use crate::gitlab::transformers::merge_request::transform_merge_request;
 use crate::gitlab::types::GitLabMergeRequest;
 use crate::ingestion::dirty_tracker;
 
-/// Result of merge request ingestion.
 #[derive(Debug, Default)]
 pub struct IngestMergeRequestsResult {
     pub fetched: usize,
@@ -32,44 +22,38 @@ pub struct IngestMergeRequestsResult {
     pub reviewers_linked: usize,
 }
 
-/// MR that needs discussion sync.
 #[derive(Debug, Clone)]
 pub struct MrForDiscussionSync {
     pub local_mr_id: i64,
     pub iid: i64,
-    pub updated_at: i64, // ms epoch
+    pub updated_at: i64,
 }
 
-/// Cursor state for incremental sync.
 #[derive(Debug, Default)]
 struct SyncCursor {
     updated_at_cursor: Option<i64>,
     tie_breaker_id: Option<i64>,
 }
 
-/// Ingest merge requests for a project.
 pub async fn ingest_merge_requests(
     conn: &Connection,
     client: &GitLabClient,
     config: &Config,
-    project_id: i64,        // Local DB project ID
-    gitlab_project_id: i64, // GitLab project ID
-    full_sync: bool,        // Reset cursor if true
+    project_id: i64,
+    gitlab_project_id: i64,
+    full_sync: bool,
 ) -> Result<IngestMergeRequestsResult> {
     let mut result = IngestMergeRequestsResult::default();
 
-    // Handle full sync - reset cursor and discussion watermarks
     if full_sync {
         reset_sync_cursor(conn, project_id)?;
         reset_discussion_watermarks(conn, project_id)?;
         info!("Full sync: cursor and discussion watermarks reset");
     }
 
-    // 1. Get current cursor
     let cursor = get_sync_cursor(conn, project_id)?;
     debug!(?cursor, "Starting MR ingestion with cursor");
 
-    // 2. Fetch MRs page by page with cursor rewind
     let mut page = 1u32;
     let per_page = 100u32;
 
@@ -87,11 +71,9 @@ pub async fn ingest_merge_requests(
         let mut last_updated_at: Option<i64> = None;
         let mut last_gitlab_id: Option<i64> = None;
 
-        // 3. Process each MR
         for mr in &page_result.items {
             result.fetched += 1;
 
-            // Parse timestamp early
             let mr_updated_at = match parse_timestamp(&mr.updated_at) {
                 Ok(ts) => ts,
                 Err(e) => {
@@ -104,31 +86,26 @@ pub async fn ingest_merge_requests(
                 }
             };
 
-            // Apply local cursor filter (skip already-processed due to rewind overlap)
             if !passes_cursor_filter_with_ts(mr.id, mr_updated_at, &cursor) {
                 debug!(gitlab_id = mr.id, "Skipping already-processed MR");
                 continue;
             }
 
-            // Transform and store
             let mr_result = process_single_mr(conn, config, project_id, mr)?;
             result.upserted += 1;
             result.labels_created += mr_result.labels_created;
             result.assignees_linked += mr_result.assignees_linked;
             result.reviewers_linked += mr_result.reviewers_linked;
 
-            // Track cursor position
             last_updated_at = Some(mr_updated_at);
             last_gitlab_id = Some(mr.id);
         }
 
-        // 4. Page-boundary cursor update
         if let (Some(ts), Some(id)) = (last_updated_at, last_gitlab_id) {
             update_sync_cursor(conn, project_id, ts, id)?;
             debug!(page, "Page-boundary cursor update");
         }
 
-        // 5. Check for more pages
         if page_result.is_last_page {
             break;
         }
@@ -150,27 +127,22 @@ pub async fn ingest_merge_requests(
     Ok(result)
 }
 
-/// Result of processing a single MR.
 struct ProcessMrResult {
     labels_created: usize,
     assignees_linked: usize,
     reviewers_linked: usize,
 }
 
-/// Process a single MR: store payload, upsert MR, handle labels/assignees/reviewers.
-/// All operations are wrapped in a transaction for atomicity.
 fn process_single_mr(
     conn: &Connection,
     config: &Config,
     project_id: i64,
     mr: &GitLabMergeRequest,
 ) -> Result<ProcessMrResult> {
-    // Transform MR first (outside transaction - no DB access)
     let payload_bytes = serde_json::to_vec(mr)?;
     let transformed = transform_merge_request(mr, project_id)
         .map_err(|e| LoreError::Other(format!("MR transform failed: {}", e)))?;
 
-    // Wrap all DB operations in a transaction for atomicity
     let tx = conn.unchecked_transaction()?;
     let result =
         process_mr_in_transaction(&tx, config, project_id, mr, &payload_bytes, &transformed)?;
@@ -179,7 +151,6 @@ fn process_single_mr(
     Ok(result)
 }
 
-/// Inner function that performs all DB operations within a transaction.
 fn process_mr_in_transaction(
     tx: &Transaction<'_>,
     config: &Config,
@@ -192,7 +163,6 @@ fn process_mr_in_transaction(
     let mr_row = &transformed.merge_request;
     let now = now_ms();
 
-    // Store raw payload
     let payload_id = store_payload(
         tx.deref(),
         StorePayloadOptions {
@@ -204,7 +174,6 @@ fn process_mr_in_transaction(
         },
     )?;
 
-    // Upsert merge request
     tx.execute(
         "INSERT INTO merge_requests (
             gitlab_id, project_id, iid, title, description, state, draft,
@@ -258,17 +227,14 @@ fn process_mr_in_transaction(
         ],
     )?;
 
-    // Get local MR ID
     let local_mr_id: i64 = tx.query_row(
         "SELECT id FROM merge_requests WHERE project_id = ? AND iid = ?",
         (project_id, mr_row.iid),
         |row| row.get(0),
     )?;
 
-    // Mark dirty for document regeneration (inside transaction)
     dirty_tracker::mark_dirty_tx(tx, SourceType::MergeRequest, local_mr_id)?;
 
-    // Clear-and-relink labels
     tx.execute(
         "DELETE FROM mr_labels WHERE merge_request_id = ?",
         [local_mr_id],
@@ -281,7 +247,6 @@ fn process_mr_in_transaction(
         )?;
     }
 
-    // Clear-and-relink assignees
     tx.execute(
         "DELETE FROM mr_assignees WHERE merge_request_id = ?",
         [local_mr_id],
@@ -294,7 +259,6 @@ fn process_mr_in_transaction(
         )?;
     }
 
-    // Clear-and-relink reviewers
     tx.execute(
         "DELETE FROM mr_reviewers WHERE merge_request_id = ?",
         [local_mr_id],
@@ -314,8 +278,6 @@ fn process_mr_in_transaction(
     })
 }
 
-/// Upsert a label within a transaction, returning its ID.
-/// Uses INSERT...ON CONFLICT...RETURNING for a single round-trip.
 fn upsert_label_tx(
     tx: &Transaction<'_>,
     project_id: i64,
@@ -330,7 +292,6 @@ fn upsert_label_tx(
         |row| row.get(0),
     )?;
 
-    // If the rowid matches last_insert_rowid, this was a new insert
     if tx.last_insert_rowid() == id {
         *created_count += 1;
     }
@@ -338,11 +299,9 @@ fn upsert_label_tx(
     Ok(id)
 }
 
-/// Check if an MR passes the cursor filter (not already processed).
-/// Takes pre-parsed timestamp to avoid redundant parsing.
 fn passes_cursor_filter_with_ts(gitlab_id: i64, mr_ts: i64, cursor: &SyncCursor) -> bool {
     let Some(cursor_ts) = cursor.updated_at_cursor else {
-        return true; // No cursor = fetch all
+        return true;
     };
 
     if mr_ts < cursor_ts {
@@ -359,7 +318,6 @@ fn passes_cursor_filter_with_ts(gitlab_id: i64, mr_ts: i64, cursor: &SyncCursor)
     true
 }
 
-/// Get the current sync cursor for merge requests.
 fn get_sync_cursor(conn: &Connection, project_id: i64) -> Result<SyncCursor> {
     let row: Option<(Option<i64>, Option<i64>)> = conn
         .query_row(
@@ -379,7 +337,6 @@ fn get_sync_cursor(conn: &Connection, project_id: i64) -> Result<SyncCursor> {
     })
 }
 
-/// Update the sync cursor.
 fn update_sync_cursor(
     conn: &Connection,
     project_id: i64,
@@ -397,7 +354,6 @@ fn update_sync_cursor(
     Ok(())
 }
 
-/// Reset the sync cursor (for full sync).
 fn reset_sync_cursor(conn: &Connection, project_id: i64) -> Result<()> {
     conn.execute(
         "DELETE FROM sync_cursors WHERE project_id = ? AND resource_type = 'merge_requests'",
@@ -406,7 +362,6 @@ fn reset_sync_cursor(conn: &Connection, project_id: i64) -> Result<()> {
     Ok(())
 }
 
-/// Reset discussion and resource event watermarks for all MRs in project (for full sync).
 fn reset_discussion_watermarks(conn: &Connection, project_id: i64) -> Result<()> {
     conn.execute(
         "UPDATE merge_requests
@@ -420,7 +375,6 @@ fn reset_discussion_watermarks(conn: &Connection, project_id: i64) -> Result<()>
     Ok(())
 }
 
-/// Get MRs that need discussion sync (updated_at > discussions_synced_for_updated_at).
 pub fn get_mrs_needing_discussion_sync(
     conn: &Connection,
     project_id: i64,
@@ -444,7 +398,6 @@ pub fn get_mrs_needing_discussion_sync(
     Ok(mrs?)
 }
 
-/// Parse ISO 8601 timestamp to milliseconds.
 fn parse_timestamp(ts: &str) -> Result<i64> {
     chrono::DateTime::parse_from_rfc3339(ts)
         .map(|dt| dt.timestamp_millis())
@@ -468,12 +421,11 @@ mod tests {
     #[test]
     fn cursor_filter_allows_newer_mrs() {
         let cursor = SyncCursor {
-            updated_at_cursor: Some(1705312800000), // 2024-01-15T10:00:00Z
+            updated_at_cursor: Some(1705312800000),
             tie_breaker_id: Some(100),
         };
 
-        // MR with later timestamp passes
-        let later_ts = 1705399200000; // 2024-01-16T10:00:00Z
+        let later_ts = 1705399200000;
         assert!(passes_cursor_filter_with_ts(101, later_ts, &cursor));
     }
 
@@ -484,8 +436,7 @@ mod tests {
             tie_breaker_id: Some(100),
         };
 
-        // MR with earlier timestamp blocked
-        let earlier_ts = 1705226400000; // 2024-01-14T10:00:00Z
+        let earlier_ts = 1705226400000;
         assert!(!passes_cursor_filter_with_ts(99, earlier_ts, &cursor));
     }
 
@@ -496,20 +447,17 @@ mod tests {
             tie_breaker_id: Some(100),
         };
 
-        // Same timestamp, higher ID passes
         assert!(passes_cursor_filter_with_ts(101, 1705312800000, &cursor));
 
-        // Same timestamp, same ID blocked
         assert!(!passes_cursor_filter_with_ts(100, 1705312800000, &cursor));
 
-        // Same timestamp, lower ID blocked
         assert!(!passes_cursor_filter_with_ts(99, 1705312800000, &cursor));
     }
 
     #[test]
     fn cursor_filter_allows_all_when_no_cursor() {
         let cursor = SyncCursor::default();
-        let old_ts = 1577836800000; // 2020-01-01T00:00:00Z
+        let old_ts = 1577836800000;
         assert!(passes_cursor_filter_with_ts(1, old_ts, &cursor));
     }
 }
diff --git a/src/ingestion/mod.rs b/src/ingestion/mod.rs
index a49946d..d422f07 100644
--- a/src/ingestion/mod.rs
+++ b/src/ingestion/mod.rs
@@ -1,8 +1,3 @@
-//! Data ingestion modules for GitLab resources.
-//!
-//! This module handles fetching and storing issues, discussions, and notes
-//! from GitLab with cursor-based incremental sync.
-
 pub mod dirty_tracker;
 pub mod discussion_queue;
 pub mod discussions;
diff --git a/src/ingestion/mr_discussions.rs b/src/ingestion/mr_discussions.rs
index ecae87b..00b0434 100644
--- a/src/ingestion/mr_discussions.rs
+++ b/src/ingestion/mr_discussions.rs
@@ -1,15 +1,3 @@
-//! MR Discussion ingestion with atomicity guarantees.
-//!
-//! Critical requirements:
-//! - Parse notes BEFORE any destructive DB operations
-//! - Watermark advanced ONLY on full pagination success
-//! - Upsert + sweep pattern for data replacement
-//! - Sync health telemetry for debugging failures
-//!
-//! Supports two modes:
-//! - Streaming: fetch and write incrementally (memory efficient)
-//! - Prefetch: fetch all upfront, then write (enables parallel API calls)
-
 use futures::StreamExt;
 use rusqlite::{Connection, params};
 use tracing::{debug, info, warn};
@@ -29,7 +17,6 @@ use crate::ingestion::dirty_tracker;
 
 use super::merge_requests::MrForDiscussionSync;
 
-/// Result of MR discussion ingestion for a single MR.
 #[derive(Debug, Default)]
 pub struct IngestMrDiscussionsResult {
     pub discussions_fetched: usize,
@@ -40,20 +27,15 @@ pub struct IngestMrDiscussionsResult {
     pub pagination_succeeded: bool,
 }
 
-/// Prefetched discussions for an MR (ready for DB write).
-/// This separates the API fetch phase from the DB write phase to enable parallelism.
 #[derive(Debug)]
 pub struct PrefetchedMrDiscussions {
     pub mr: MrForDiscussionSync,
     pub discussions: Vec<PrefetchedDiscussion>,
     pub fetch_error: Option<String>,
-    /// True if any discussions failed to transform (skip sweep if true)
     pub had_transform_errors: bool,
-    /// Count of notes skipped due to transform errors
     pub notes_skipped_count: usize,
 }
 
-/// A single prefetched discussion with transformed data.
 #[derive(Debug)]
 pub struct PrefetchedDiscussion {
     pub raw: GitLabDiscussion,
@@ -61,8 +43,6 @@ pub struct PrefetchedDiscussion {
     pub notes: Vec<NormalizedNote>,
 }
 
-/// Fetch discussions for an MR without writing to DB.
-/// This can be called in parallel for multiple MRs.
 pub async fn prefetch_mr_discussions(
     client: &GitLabClient,
     gitlab_project_id: i64,
@@ -71,7 +51,6 @@ pub async fn prefetch_mr_discussions(
 ) -> PrefetchedMrDiscussions {
     debug!(mr_iid = mr.iid, "Prefetching discussions for MR");
 
-    // Fetch all discussions from GitLab
     let raw_discussions = match client
         .fetch_all_mr_discussions(gitlab_project_id, mr.iid)
         .await
@@ -88,13 +67,11 @@ pub async fn prefetch_mr_discussions(
         }
     };
 
-    // Transform each discussion
     let mut discussions = Vec::with_capacity(raw_discussions.len());
     let mut had_transform_errors = false;
     let mut notes_skipped_count = 0;
 
     for raw in raw_discussions {
-        // Transform notes
         let notes = match transform_notes_with_diff_position(&raw, local_project_id) {
             Ok(n) => n,
             Err(e) => {
@@ -104,14 +81,12 @@ pub async fn prefetch_mr_discussions(
                     error = %e,
                     "Note transform failed during prefetch"
                 );
-                // Track the failure - don't sweep stale data if transforms failed
                 had_transform_errors = true;
                 notes_skipped_count += raw.notes.len();
                 continue;
             }
         };
 
-        // Transform discussion
         let normalized = transform_mr_discussion(&raw, local_project_id, mr.local_mr_id);
 
         discussions.push(PrefetchedDiscussion {
@@ -130,15 +105,12 @@ pub async fn prefetch_mr_discussions(
     }
 }
 
-/// Write prefetched discussions to DB.
-/// This must be called serially (rusqlite Connection is not Send).
 pub fn write_prefetched_mr_discussions(
     conn: &Connection,
     config: &Config,
     local_project_id: i64,
     prefetched: PrefetchedMrDiscussions,
 ) -> Result<IngestMrDiscussionsResult> {
-    // Sync succeeds only if no fetch errors AND no transform errors
     let sync_succeeded = prefetched.fetch_error.is_none() && !prefetched.had_transform_errors;
 
     let mut result = IngestMrDiscussionsResult {
@@ -149,7 +121,6 @@ pub fn write_prefetched_mr_discussions(
 
     let mr = &prefetched.mr;
 
-    // Handle fetch errors
     if let Some(error) = &prefetched.fetch_error {
         warn!(mr_iid = mr.iid, error = %error, "Prefetch failed for MR");
         record_sync_health_error(conn, mr.local_mr_id, error)?;
@@ -158,9 +129,7 @@ pub fn write_prefetched_mr_discussions(
 
     let run_seen_at = now_ms();
 
-    // Write each discussion
     for disc in &prefetched.discussions {
-        // Count DiffNotes upfront (independent of transaction)
         let diffnotes_in_disc = disc
             .notes
             .iter()
@@ -168,10 +137,8 @@ pub fn write_prefetched_mr_discussions(
             .count();
         let notes_in_disc = disc.notes.len();
 
-        // Start transaction
         let tx = conn.unchecked_transaction()?;
 
-        // Store raw payload
         let payload_bytes = serde_json::to_vec(&disc.raw)?;
         let payload_id = Some(store_payload(
             &tx,
@@ -184,20 +151,16 @@ pub fn write_prefetched_mr_discussions(
             },
         )?);
 
-        // Upsert discussion
         upsert_discussion(&tx, &disc.normalized, run_seen_at, payload_id)?;
 
-        // Get local discussion ID
         let local_discussion_id: i64 = tx.query_row(
             "SELECT id FROM discussions WHERE project_id = ? AND gitlab_discussion_id = ?",
             params![local_project_id, &disc.normalized.gitlab_discussion_id],
             |row| row.get(0),
         )?;
 
-        // Mark dirty for document regeneration (inside transaction)
         dirty_tracker::mark_dirty_tx(&tx, SourceType::Discussion, local_discussion_id)?;
 
-        // Upsert notes
         for note in &disc.notes {
             let should_store_payload = !note.is_system
                 || note.position_new_path.is_some()
@@ -229,15 +192,12 @@ pub fn write_prefetched_mr_discussions(
 
         tx.commit()?;
 
-        // Increment counters AFTER successful commit to keep metrics honest
         result.discussions_fetched += 1;
         result.discussions_upserted += 1;
         result.notes_upserted += notes_in_disc;
         result.diffnotes_count += diffnotes_in_disc;
     }
 
-    // Only sweep stale data and advance watermark on full success
-    // If any discussions failed to transform, preserve existing data
     if sync_succeeded {
         sweep_stale_discussions(conn, mr.local_mr_id, run_seen_at)?;
         sweep_stale_notes(conn, local_project_id, mr.local_mr_id, run_seen_at)?;
@@ -259,7 +219,6 @@ pub fn write_prefetched_mr_discussions(
     Ok(result)
 }
 
-/// Ingest discussions for MRs that need sync.
 pub async fn ingest_mr_discussions(
     conn: &Connection,
     client: &GitLabClient,
@@ -269,7 +228,7 @@ pub async fn ingest_mr_discussions(
     mrs: &[MrForDiscussionSync],
 ) -> Result<IngestMrDiscussionsResult> {
     let mut total_result = IngestMrDiscussionsResult {
-        pagination_succeeded: true, // Start optimistic
+        pagination_succeeded: true,
         ..Default::default()
     };
 
@@ -289,7 +248,6 @@ pub async fn ingest_mr_discussions(
         total_result.notes_upserted += result.notes_upserted;
         total_result.notes_skipped_bad_timestamp += result.notes_skipped_bad_timestamp;
         total_result.diffnotes_count += result.diffnotes_count;
-        // Pagination failed for any MR means overall failure
         if !result.pagination_succeeded {
             total_result.pagination_succeeded = false;
         }
@@ -309,7 +267,6 @@ pub async fn ingest_mr_discussions(
     Ok(total_result)
 }
 
-/// Ingest discussions for a single MR.
 async fn ingest_discussions_for_mr(
     conn: &Connection,
     client: &GitLabClient,
@@ -329,13 +286,10 @@ async fn ingest_discussions_for_mr(
         "Fetching discussions for MR"
     );
 
-    // Record sync start time for sweep
     let run_seen_at = now_ms();
 
-    // Stream discussions from GitLab
     let mut discussions_stream = client.paginate_mr_discussions(gitlab_project_id, mr.iid);
 
-    // Track if we've received any response
     let mut received_first_response = false;
 
     while let Some(disc_result) = discussions_stream.next().await {
@@ -343,7 +297,6 @@ async fn ingest_discussions_for_mr(
             received_first_response = true;
         }
 
-        // Handle pagination errors - don't advance watermark
         let gitlab_discussion = match disc_result {
             Ok(d) => d,
             Err(e) => {
@@ -357,7 +310,6 @@ async fn ingest_discussions_for_mr(
                 break;
             }
         };
-        // CRITICAL: Parse notes BEFORE any destructive DB operations
         let notes = match transform_notes_with_diff_position(&gitlab_discussion, local_project_id) {
             Ok(notes) => notes,
             Err(e) => {
@@ -369,25 +321,21 @@ async fn ingest_discussions_for_mr(
                 );
                 result.notes_skipped_bad_timestamp += gitlab_discussion.notes.len();
                 result.pagination_succeeded = false;
-                continue; // Skip this discussion, preserve existing data
+                continue;
             }
         };
 
-        // Count DiffNotes upfront (independent of transaction)
         let diffnotes_in_disc = notes
             .iter()
             .filter(|n| n.position_new_path.is_some() || n.position_old_path.is_some())
             .count();
         let notes_count = notes.len();
 
-        // Transform discussion
         let normalized_discussion =
             transform_mr_discussion(&gitlab_discussion, local_project_id, mr.local_mr_id);
 
-        // Only NOW start transaction (after parse succeeded)
         let tx = conn.unchecked_transaction()?;
 
-        // Store raw payload
         let payload_bytes = serde_json::to_vec(&gitlab_discussion)?;
         let payload_id = Some(store_payload(
             &tx,
@@ -400,10 +348,8 @@ async fn ingest_discussions_for_mr(
             },
         )?);
 
-        // Upsert discussion with run_seen_at
         upsert_discussion(&tx, &normalized_discussion, run_seen_at, payload_id)?;
 
-        // Get local discussion ID
         let local_discussion_id: i64 = tx.query_row(
             "SELECT id FROM discussions WHERE project_id = ? AND gitlab_discussion_id = ?",
             params![
@@ -413,12 +359,9 @@ async fn ingest_discussions_for_mr(
             |row| row.get(0),
         )?;
 
-        // Mark dirty for document regeneration (inside transaction)
         dirty_tracker::mark_dirty_tx(&tx, SourceType::Discussion, local_discussion_id)?;
 
-        // Upsert notes (not delete-all-then-insert)
         for note in &notes {
-            // Selective payload storage: skip system notes without position
             let should_store_payload = !note.is_system
                 || note.position_new_path.is_some()
                 || note.position_old_path.is_some();
@@ -452,22 +395,17 @@ async fn ingest_discussions_for_mr(
 
         tx.commit()?;
 
-        // Increment counters AFTER successful commit to keep metrics honest
         result.discussions_fetched += 1;
         result.discussions_upserted += 1;
         result.notes_upserted += notes_count;
         result.diffnotes_count += diffnotes_in_disc;
     }
 
-    // Only sweep stale data and advance watermark on full success
     if result.pagination_succeeded && received_first_response {
-        // Sweep stale discussions for this MR
         sweep_stale_discussions(conn, mr.local_mr_id, run_seen_at)?;
 
-        // Sweep stale notes for this MR
         sweep_stale_notes(conn, local_project_id, mr.local_mr_id, run_seen_at)?;
 
-        // Advance watermark
         mark_discussions_synced(conn, mr.local_mr_id, mr.updated_at)?;
         clear_sync_health_error(conn, mr.local_mr_id)?;
 
@@ -476,7 +414,6 @@ async fn ingest_discussions_for_mr(
             "MR discussion sync complete, watermark advanced"
         );
     } else if result.pagination_succeeded && !received_first_response {
-        // Empty response (no discussions) - still safe to sweep and advance
         sweep_stale_discussions(conn, mr.local_mr_id, run_seen_at)?;
         sweep_stale_notes(conn, local_project_id, mr.local_mr_id, run_seen_at)?;
         mark_discussions_synced(conn, mr.local_mr_id, mr.updated_at)?;
@@ -493,7 +430,6 @@ async fn ingest_discussions_for_mr(
     Ok(result)
 }
 
-/// Upsert a discussion with last_seen_at for sweep.
 fn upsert_discussion(
     conn: &Connection,
     discussion: &crate::gitlab::transformers::NormalizedDiscussion,
@@ -531,7 +467,6 @@ fn upsert_discussion(
     Ok(())
 }
 
-/// Upsert a note with last_seen_at for sweep.
 fn upsert_note(
     conn: &Connection,
     discussion_id: i64,
@@ -601,7 +536,6 @@ fn upsert_note(
     Ok(())
 }
 
-/// Sweep stale discussions (not seen in this run).
 fn sweep_stale_discussions(conn: &Connection, local_mr_id: i64, run_seen_at: i64) -> Result<usize> {
     let deleted = conn.execute(
         "DELETE FROM discussions
@@ -614,7 +548,6 @@ fn sweep_stale_discussions(conn: &Connection, local_mr_id: i64, run_seen_at: i64
     Ok(deleted)
 }
 
-/// Sweep stale notes for discussions belonging to this MR.
 fn sweep_stale_notes(
     conn: &Connection,
     local_project_id: i64,
@@ -636,7 +569,6 @@ fn sweep_stale_notes(
     Ok(deleted)
 }
 
-/// Mark MR discussions as synced (advance watermark).
 fn mark_discussions_synced(conn: &Connection, local_mr_id: i64, updated_at: i64) -> Result<()> {
     conn.execute(
         "UPDATE merge_requests SET discussions_synced_for_updated_at = ? WHERE id = ?",
@@ -645,7 +577,6 @@ fn mark_discussions_synced(conn: &Connection, local_mr_id: i64, updated_at: i64)
     Ok(())
 }
 
-/// Record sync health error for debugging.
 fn record_sync_health_error(conn: &Connection, local_mr_id: i64, error: &str) -> Result<()> {
     conn.execute(
         "UPDATE merge_requests SET
@@ -658,7 +589,6 @@ fn record_sync_health_error(conn: &Connection, local_mr_id: i64, error: &str) ->
     Ok(())
 }
 
-/// Clear sync health error on success.
 fn clear_sync_health_error(conn: &Connection, local_mr_id: i64) -> Result<()> {
     conn.execute(
         "UPDATE merge_requests SET
diff --git a/src/lib.rs b/src/lib.rs
index 98d7b71..a271c48 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,8 +1,3 @@
-//! Gitlore - Semantic search for GitLab issues, MRs, and discussions.
-//!
-//! A self-hosted CLI tool that syncs GitLab data to a local SQLite database
-//! with fast querying and semantic search capabilities.
-
 pub mod cli;
 pub mod core;
 pub mod documents;
diff --git a/src/main.rs b/src/main.rs
index 8319258..e444355 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,5 +1,3 @@
-//! Gitlore CLI entry point.
-
 use clap::Parser;
 use console::style;
 use dialoguer::{Confirm, Input};
@@ -37,42 +35,30 @@ use lore::core::sync_run::SyncRunRecorder;
 
 #[tokio::main]
 async fn main() {
-    // Reset SIGPIPE to default behavior so piping (e.g. `lore issues | head`) doesn't panic
     #[cfg(unix)]
     unsafe {
         libc::signal(libc::SIGPIPE, libc::SIG_DFL);
     }
 
-    // Parse CLI first so we know verbosity settings before initializing the subscriber.
     let cli = Cli::parse();
     let robot_mode = cli.is_robot_mode();
 
-    // Try to load logging config for file layer settings.
-    // If config isn't available yet (e.g. during `lore init`), use defaults.
     let logging_config = lore::Config::load(cli.config.as_deref())
         .map(|c| c.logging)
         .unwrap_or_default();
 
-    // Clean up old log files before initializing subscriber (so deleted handles aren't held open)
     let log_dir = get_log_dir(logging_config.log_dir.as_deref());
     if logging_config.file_logging && logging_config.retention_days > 0 {
         logging::cleanup_old_logs(&log_dir, logging_config.retention_days);
     }
 
-    // Build triple-layer subscriber:
-    // - stderr layer: human-readable or JSON, controlled by -v flags
-    // - file layer: always-on JSON to daily-rotated log files
-    // - metrics layer: captures span timing for robot-mode performance data
     let stderr_filter = logging::build_stderr_filter(cli.verbose, cli.quiet);
     let metrics_layer = MetricsLayer::new();
 
     let registry = tracing_subscriber::registry();
 
-    // Hold the file writer guard at function scope so it flushes on exit.
-    // WorkerGuard::drop() flushes pending log entries — forgetting it loses them.
     let _file_guard: Option<tracing_appender::non_blocking::WorkerGuard>;
 
-    // stderr layer: format depends on --log-format flag
     if cli.log_format == "json" {
         let stderr_layer = tracing_subscriber::fmt::layer()
             .json()
@@ -131,11 +117,10 @@ async fn main() {
         }
     }
 
-    // Apply color settings (console crate handles NO_COLOR/CLICOLOR natively in "auto" mode)
     match cli.color.as_str() {
         "never" => console::set_colors_enabled(false),
         "always" => console::set_colors_enabled(true),
-        "auto" => {} // console crate handles this natively
+        "auto" => {}
         _ => unreachable!(),
     }
 
@@ -193,7 +178,6 @@ async fn main() {
         Commands::Health => handle_health(cli.config.as_deref(), robot_mode).await,
         Commands::RobotDocs => handle_robot_docs(robot_mode),
 
-        // --- Backward-compat: deprecated aliases ---
         Commands::List {
             entity,
             limit,
@@ -296,7 +280,6 @@ async fn main() {
     }
 }
 
-/// Fallback error output for non-LoreError errors in robot mode.
 #[derive(Serialize)]
 struct FallbackErrorOutput {
     error: FallbackError,
@@ -309,15 +292,12 @@ struct FallbackError {
 }
 
 fn handle_error(e: Box<dyn std::error::Error>, robot_mode: bool) -> ! {
-    // Try to downcast to LoreError for structured output
     if let Some(gi_error) = e.downcast_ref::<LoreError>() {
         if robot_mode {
             let output = RobotErrorOutput::from(gi_error);
-            // Use serde_json for safe serialization; fallback constructs JSON safely
             eprintln!(
                 "{}",
                 serde_json::to_string(&output).unwrap_or_else(|_| {
-                    // Fallback uses serde to ensure proper escaping
                     let fallback = FallbackErrorOutput {
                         error: FallbackError {
                             code: "INTERNAL_ERROR".to_string(),
@@ -338,7 +318,6 @@ fn handle_error(e: Box<dyn std::error::Error>, robot_mode: bool) -> ! {
         }
     }
 
-    // Fallback for non-LoreError errors - use serde for proper JSON escaping
     if robot_mode {
         let output = FallbackErrorOutput {
             error: FallbackError {
@@ -359,10 +338,6 @@ fn handle_error(e: Box<dyn std::error::Error>, robot_mode: bool) -> ! {
     std::process::exit(1);
 }
 
-// ============================================================================
-// Primary command handlers
-// ============================================================================
-
 fn handle_issues(
     config_override: Option<&str>,
     args: IssuesArgs,
@@ -375,7 +350,6 @@ fn handle_issues(
     let order = if asc { "asc" } else { "desc" };
 
     if let Some(iid) = args.iid {
-        // Show mode
         let result = run_show_issue(&config, iid, args.project.as_deref())?;
         if robot_mode {
             print_show_issue_json(&result);
@@ -383,7 +357,6 @@ fn handle_issues(
             print_show_issue(&result);
         }
     } else {
-        // List mode
         let filters = ListFilters {
             limit: args.limit,
             project: args.project.as_deref(),
@@ -424,7 +397,6 @@ fn handle_mrs(
     let order = if asc { "asc" } else { "desc" };
 
     if let Some(iid) = args.iid {
-        // Show mode
         let result = run_show_mr(&config, iid, args.project.as_deref())?;
         if robot_mode {
             print_show_mr_json(&result);
@@ -432,7 +404,6 @@ fn handle_mrs(
             print_show_mr(&result);
         }
     } else {
-        // List mode
         let filters = MrListFilters {
             limit: args.limit,
             project: args.project.as_deref(),
@@ -481,7 +452,6 @@ async fn handle_ingest(
     let force = args.force && !args.no_force;
     let full = args.full && !args.no_full;
 
-    // Record ingest run lifecycle in sync_runs table
     let entity_label = args.entity.as_deref().unwrap_or("all");
     let command = format!("ingest:{entity_label}");
     let db_path = get_db_path(config.storage.db_path.as_deref());
@@ -493,7 +463,6 @@ async fn handle_ingest(
     let ingest_result: std::result::Result<(), Box<dyn std::error::Error>> = async {
         match args.entity.as_deref() {
             Some(resource_type) => {
-                // Single entity ingest
                 let result = run_ingest(
                     &config,
                     resource_type,
@@ -512,7 +481,6 @@ async fn handle_ingest(
                 }
             }
             None => {
-                // Ingest everything: issues then MRs
                 if !robot_mode && !quiet {
                     println!(
                         "{}",
@@ -571,7 +539,6 @@ async fn handle_ingest(
     }
 }
 
-/// JSON output for combined ingest (issues + mrs).
 #[derive(Serialize)]
 struct CombinedIngestOutput {
     ok: bool,
@@ -666,7 +633,6 @@ async fn handle_sync_status_cmd(
     Ok(())
 }
 
-/// JSON output for init command.
 #[derive(Serialize)]
 struct InitOutput {
     ok: bool,
@@ -725,7 +691,6 @@ async fn handle_init(
     token_env_var_flag: Option<String>,
     projects_flag: Option<String>,
 ) -> Result<(), Box<dyn std::error::Error>> {
-    // Robot mode: require all inputs via flags, skip interactive prompts
     if robot_mode {
         let missing: Vec<&str> = [
             gitlab_url_flag.is_none().then_some("--gitlab-url"),
@@ -773,7 +738,6 @@ async fn handle_init(
         return Ok(());
     }
 
-    // Human mode: interactive prompts
     let config_path = get_config_path(config_override);
     let mut confirmed_overwrite = force;
 
@@ -903,7 +867,6 @@ async fn handle_init(
     Ok(())
 }
 
-/// JSON output for auth-test command.
 #[derive(Serialize)]
 struct AuthTestOutput {
     ok: bool,
@@ -953,7 +916,7 @@ async fn handle_auth_test(
             } else {
                 eprintln!("{}", style(format!("Error: {e}")).red());
             }
-            std::process::exit(5); // AUTH_FAILED exit code
+            std::process::exit(5);
         }
     }
 }
@@ -977,7 +940,6 @@ async fn handle_doctor(
     Ok(())
 }
 
-/// JSON output for version command.
 #[derive(Serialize)]
 struct VersionOutput {
     ok: bool,
@@ -1071,7 +1033,6 @@ fn handle_reset(robot_mode: bool) -> Result<(), Box<dyn std::error::Error>> {
     std::process::exit(1);
 }
 
-/// JSON output for migrate command.
 #[derive(Serialize)]
 struct MigrateOutput {
     ok: bool,
@@ -1085,7 +1046,6 @@ struct MigrateData {
     migrated: bool,
 }
 
-/// JSON error output with suggestion field.
 #[derive(Serialize)]
 struct RobotErrorWithSuggestion {
     error: RobotErrorSuggestionData,
@@ -1125,7 +1085,7 @@ async fn handle_migrate(
                 style("Run 'lore init' first to create the database.").yellow()
             );
         }
-        std::process::exit(10); // DB_ERROR exit code
+        std::process::exit(10);
     }
 
     let conn = create_connection(&db_path)?;
@@ -1174,7 +1134,6 @@ async fn handle_stats(
     robot_mode: bool,
 ) -> Result<(), Box<dyn std::error::Error>> {
     let config = Config::load(config_override)?;
-    // Auto-enable --check when --repair is used
     let check = (args.check && !args.no_check) || args.repair;
     let result = run_stats(&config, check, args.repair)?;
     if robot_mode {
@@ -1273,7 +1232,6 @@ async fn handle_sync_cmd(
         robot_mode,
     };
 
-    // Record sync run lifecycle in sync_runs table
     let db_path = get_db_path(config.storage.db_path.as_deref());
     let recorder_conn = create_connection(&db_path)?;
     let run_id = uuid::Uuid::new_v4().simple().to_string();
@@ -1290,7 +1248,6 @@ async fn handle_sync_cmd(
                 + result.documents_regenerated
                 + result.documents_embedded;
             let total_errors = result.resource_events_failed;
-            // Best-effort: don't fail the command if recording fails
             let _ = recorder.succeed(&recorder_conn, &stages, total_items, total_errors);
 
             if robot_mode {
@@ -1308,11 +1265,6 @@ async fn handle_sync_cmd(
     }
 }
 
-// ============================================================================
-// Health + Robot-docs handlers
-// ============================================================================
-
-/// JSON output for health command.
 #[derive(Serialize)]
 struct HealthOutput {
     ok: bool,
@@ -1406,7 +1358,6 @@ async fn handle_health(
     Ok(())
 }
 
-/// JSON output for robot-docs command.
 #[derive(Serialize)]
 struct RobotDocsOutput {
     ok: bool,
@@ -1591,10 +1542,6 @@ fn handle_robot_docs(robot_mode: bool) -> Result<(), Box<dyn std::error::Error>>
     Ok(())
 }
 
-// ============================================================================
-// Backward-compat handlers (deprecated, delegate to new handlers)
-// ============================================================================
-
 #[allow(clippy::too_many_arguments)]
 async fn handle_list_compat(
     config_override: Option<&str>,
diff --git a/src/search/filters.rs b/src/search/filters.rs
index ce8aebb..2c30f8d 100644
--- a/src/search/filters.rs
+++ b/src/search/filters.rs
@@ -5,14 +5,12 @@ use rusqlite::Connection;
 const DEFAULT_LIMIT: usize = 20;
 const MAX_LIMIT: usize = 100;
 
-/// Path filter: exact match or prefix match (trailing `/`).
 #[derive(Debug, Clone)]
 pub enum PathFilter {
     Exact(String),
     Prefix(String),
 }
 
-/// Filters applied to search results post-retrieval.
 #[derive(Debug, Clone, Default)]
 pub struct SearchFilters {
     pub source_type: Option<SourceType>,
@@ -26,7 +24,6 @@ pub struct SearchFilters {
 }
 
 impl SearchFilters {
-    /// Returns true if any filter (besides limit) is set.
     pub fn has_any_filter(&self) -> bool {
         self.source_type.is_some()
             || self.author.is_some()
@@ -37,7 +34,6 @@ impl SearchFilters {
             || self.path.is_some()
     }
 
-    /// Clamp limit to [1, 100], defaulting 0 to 20.
     pub fn clamp_limit(&self) -> usize {
         if self.limit == 0 {
             DEFAULT_LIMIT
@@ -47,17 +43,12 @@ impl SearchFilters {
     }
 }
 
-/// Escape SQL LIKE wildcards in a string.
 fn escape_like(s: &str) -> String {
     s.replace('\\', "\\\\")
         .replace('%', "\\%")
         .replace('_', "\\_")
 }
 
-/// Apply filters to a ranked list of document IDs, preserving rank order.
-///
-/// Uses json_each() to pass ranked IDs efficiently and maintain ordering
-/// via ORDER BY j.key.
 pub fn apply_filters(
     conn: &Connection,
     document_ids: &[i64],
@@ -216,8 +207,6 @@ mod tests {
 
     #[test]
     fn test_empty_ids() {
-        // Cannot test apply_filters without DB, but we can verify empty returns empty
-        // by testing the early return path logic
         let f = SearchFilters::default();
         assert!(!f.has_any_filter());
     }
diff --git a/src/search/fts.rs b/src/search/fts.rs
index adb8ee6..1277726 100644
--- a/src/search/fts.rs
+++ b/src/search/fts.rs
@@ -1,16 +1,12 @@
 use crate::core::error::Result;
 use rusqlite::Connection;
 
-/// FTS query mode.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum FtsQueryMode {
-    /// Safe mode: each token wrapped in quotes, trailing * preserved on alphanumeric tokens.
     Safe,
-    /// Raw mode: query passed directly to FTS5 (for advanced users).
     Raw,
 }
 
-/// A single FTS5 search result.
 #[derive(Debug)]
 pub struct FtsResult {
     pub document_id: i64,
@@ -18,14 +14,6 @@ pub struct FtsResult {
     pub snippet: String,
 }
 
-/// Convert raw user input into a safe FTS5 query.
-///
-/// Safe mode:
-/// - Splits on whitespace
-/// - Wraps each token in double quotes (escaping internal quotes)
-/// - Preserves trailing `*` on alphanumeric-only tokens (prefix search)
-///
-/// Raw mode: passes through unchanged.
 pub fn to_fts_query(raw: &str, mode: FtsQueryMode) -> String {
     match mode {
         FtsQueryMode::Raw => raw.to_string(),
@@ -38,16 +26,13 @@ pub fn to_fts_query(raw: &str, mode: FtsQueryMode) -> String {
             let tokens: Vec<String> = trimmed
                 .split_whitespace()
                 .map(|token| {
-                    // Check if token ends with * and the rest is alphanumeric
                     if let Some(stem) = token.strip_suffix('*')
                         && !stem.is_empty()
                         && stem.chars().all(|c| c.is_alphanumeric() || c == '_')
                     {
-                        // Preserve prefix search: "stem"*
                         let escaped = stem.replace('"', "\"\"");
                         return format!("\"{}\"*", escaped);
                     }
-                    // Default: wrap in quotes, escape internal quotes
                     let escaped = token.replace('"', "\"\"");
                     format!("\"{}\"", escaped)
                 })
@@ -58,10 +43,6 @@ pub fn to_fts_query(raw: &str, mode: FtsQueryMode) -> String {
     }
 }
 
-/// Execute an FTS5 search query.
-///
-/// Returns results ranked by BM25 score (lower = better match) with
-/// contextual snippets highlighting matches.
 pub fn search_fts(
     conn: &Connection,
     query: &str,
@@ -97,14 +78,11 @@ pub fn search_fts(
     Ok(results)
 }
 
-/// Generate a fallback snippet for results without FTS snippets.
-/// Truncates at a word boundary and appends "...".
 pub fn generate_fallback_snippet(content_text: &str, max_chars: usize) -> String {
     if content_text.chars().count() <= max_chars {
         return content_text.to_string();
     }
 
-    // Collect the char boundary at max_chars to slice correctly for multi-byte content
     let byte_end = content_text
         .char_indices()
         .nth(max_chars)
@@ -112,7 +90,6 @@ pub fn generate_fallback_snippet(content_text: &str, max_chars: usize) -> String
         .unwrap_or(content_text.len());
     let truncated = &content_text[..byte_end];
 
-    // Walk backward to find a word boundary (space)
     if let Some(last_space) = truncated.rfind(' ') {
         format!("{}...", &truncated[..last_space])
     } else {
@@ -120,7 +97,6 @@ pub fn generate_fallback_snippet(content_text: &str, max_chars: usize) -> String
     }
 }
 
-/// Get the best snippet: prefer FTS snippet, fall back to truncated content.
 pub fn get_result_snippet(fts_snippet: Option<&str>, content_text: &str) -> String {
     match fts_snippet {
         Some(s) if !s.is_empty() => s.to_string(),
@@ -179,11 +155,9 @@ mod tests {
 
     #[test]
     fn test_prefix_only_alphanumeric() {
-        // Non-alphanumeric prefix: C++* should NOT be treated as prefix search
         let result = to_fts_query("C++*", FtsQueryMode::Safe);
         assert_eq!(result, "\"C++*\"");
 
-        // Pure alphanumeric prefix: auth* should be prefix search
         let result = to_fts_query("auth*", FtsQueryMode::Safe);
         assert_eq!(result, "\"auth\"*");
     }
@@ -205,7 +179,7 @@ mod tests {
         let content = "This is a moderately long piece of text that should be truncated at a word boundary for readability purposes";
         let result = generate_fallback_snippet(content, 50);
         assert!(result.ends_with("..."));
-        assert!(result.len() <= 55); // 50 + "..."
+        assert!(result.len() <= 55);
     }
 
     #[test]
diff --git a/src/search/hybrid.rs b/src/search/hybrid.rs
index a30cf32..e6d5d2e 100644
--- a/src/search/hybrid.rs
+++ b/src/search/hybrid.rs
@@ -1,5 +1,3 @@
-//! Hybrid search orchestrator combining FTS5 + sqlite-vec via RRF.
-
 use rusqlite::Connection;
 
 use crate::core::error::Result;
@@ -11,7 +9,6 @@ const BASE_RECALL_MIN: usize = 50;
 const FILTERED_RECALL_MIN: usize = 200;
 const RECALL_CAP: usize = 1500;
 
-/// Search mode selection.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SearchMode {
     Hybrid,
@@ -38,7 +35,6 @@ impl SearchMode {
     }
 }
 
-/// Combined search result with provenance from both retrieval lists.
 pub struct HybridResult {
     pub document_id: i64,
     pub score: f64,
@@ -47,11 +43,6 @@ pub struct HybridResult {
     pub rrf_score: f64,
 }
 
-/// Execute hybrid search, returning ranked results + any warnings.
-///
-/// `client` is `Option` to enable graceful degradation: when Ollama is
-/// unavailable, the caller passes `None` and hybrid mode falls back to
-/// FTS-only with a warning.
 pub async fn search_hybrid(
     conn: &Connection,
     client: Option<&OllamaClient>,
@@ -62,7 +53,6 @@ pub async fn search_hybrid(
 ) -> Result<(Vec<HybridResult>, Vec<String>)> {
     let mut warnings: Vec<String> = Vec::new();
 
-    // Adaptive recall
     let requested = filters.clamp_limit();
     let top_k = if filters.has_any_filter() {
         (requested * 50).clamp(FILTERED_RECALL_MIN, RECALL_CAP)
@@ -159,7 +149,6 @@ pub async fn search_hybrid(
         })
         .collect();
 
-    // Apply post-retrieval filters and limit
     let limit = filters.clamp_limit();
     let results = if filters.has_any_filter() {
         let all_ids: Vec<i64> = results.iter().map(|r| r.document_id).collect();
@@ -232,7 +221,7 @@ mod tests {
         };
         let requested = filters.clamp_limit();
         let top_k = (requested * 50).clamp(FILTERED_RECALL_MIN, RECALL_CAP);
-        assert_eq!(top_k, RECALL_CAP); // 5000 capped to 1500
+        assert_eq!(top_k, RECALL_CAP);
     }
 
     #[test]
@@ -243,6 +232,6 @@ mod tests {
         };
         let requested = filters.clamp_limit();
         let top_k = (requested * 10).clamp(BASE_RECALL_MIN, RECALL_CAP);
-        assert_eq!(top_k, BASE_RECALL_MIN); // 10 -> 50
+        assert_eq!(top_k, BASE_RECALL_MIN);
     }
 }
diff --git a/src/search/rrf.rs b/src/search/rrf.rs
index b8b6e88..bea6461 100644
--- a/src/search/rrf.rs
+++ b/src/search/rrf.rs
@@ -2,39 +2,24 @@ use std::collections::HashMap;
 
 const RRF_K: f64 = 60.0;
 
-/// A single result from Reciprocal Rank Fusion, containing both raw and
-/// normalized scores plus per-list rank provenance for --explain output.
 pub struct RrfResult {
     pub document_id: i64,
-    /// Raw RRF score: sum of 1/(k + rank) across all lists.
     pub rrf_score: f64,
-    /// Normalized to [0, 1] where the best result is 1.0.
     pub normalized_score: f64,
-    /// 1-indexed rank in the vector results list, if present.
     pub vector_rank: Option<usize>,
-    /// 1-indexed rank in the FTS results list, if present.
     pub fts_rank: Option<usize>,
 }
 
-/// Combine vector and FTS retrieval results using Reciprocal Rank Fusion.
-///
-/// Input tuples are `(document_id, score/distance)` — already sorted by each retriever.
-/// Ranks are 1-indexed (first result = rank 1).
-///
-/// Score = sum of 1/(k + rank) for each list containing the document.
 pub fn rank_rrf(vector_results: &[(i64, f64)], fts_results: &[(i64, f64)]) -> Vec<RrfResult> {
     if vector_results.is_empty() && fts_results.is_empty() {
         return Vec::new();
     }
 
-    // (rrf_score, vector_rank, fts_rank)
     let mut scores: HashMap<i64, (f64, Option<usize>, Option<usize>)> = HashMap::new();
 
     for (i, &(doc_id, _)) in vector_results.iter().enumerate() {
-        let rank = i + 1; // 1-indexed
+        let rank = i + 1;
         let entry = scores.entry(doc_id).or_insert((0.0, None, None));
-        // Only count the first occurrence per list to prevent duplicates
-        // from inflating the score.
         if entry.1.is_none() {
             entry.0 += 1.0 / (RRF_K + rank as f64);
             entry.1 = Some(rank);
@@ -42,7 +27,7 @@ pub fn rank_rrf(vector_results: &[(i64, f64)], fts_results: &[(i64, f64)]) -> Ve
     }
 
     for (i, &(doc_id, _)) in fts_results.iter().enumerate() {
-        let rank = i + 1; // 1-indexed
+        let rank = i + 1;
         let entry = scores.entry(doc_id).or_insert((0.0, None, None));
         if entry.2.is_none() {
             entry.0 += 1.0 / (RRF_K + rank as f64);
@@ -55,16 +40,14 @@ pub fn rank_rrf(vector_results: &[(i64, f64)], fts_results: &[(i64, f64)]) -> Ve
         .map(|(doc_id, (rrf_score, vector_rank, fts_rank))| RrfResult {
             document_id: doc_id,
             rrf_score,
-            normalized_score: 0.0, // filled in below
+            normalized_score: 0.0,
             vector_rank,
             fts_rank,
         })
         .collect();
 
-    // Sort descending by rrf_score
     results.sort_by(|a, b| b.rrf_score.total_cmp(&a.rrf_score));
 
-    // Normalize: best = 1.0
     if let Some(max_score) = results.first().map(|r| r.rrf_score).filter(|&s| s > 0.0) {
         for result in &mut results {
             result.normalized_score = result.rrf_score / max_score;
@@ -84,10 +67,8 @@ mod tests {
         let fts = vec![(1, 5.0), (3, 3.0)];
         let results = rank_rrf(&vector, &fts);
 
-        // Doc 1 appears in both lists, should rank highest
         assert_eq!(results[0].document_id, 1);
 
-        // Doc 1 score should be higher than doc 2 and doc 3
         let doc1 = &results[0];
         let doc2_score = results
             .iter()
@@ -121,10 +102,8 @@ mod tests {
         let fts = vec![(1, 5.0), (3, 3.0)];
         let results = rank_rrf(&vector, &fts);
 
-        // Best result should have normalized_score = 1.0
         assert!((results[0].normalized_score - 1.0).abs() < f64::EPSILON);
 
-        // All scores in [0, 1]
         for r in &results {
             assert!(r.normalized_score >= 0.0);
             assert!(r.normalized_score <= 1.0);
@@ -165,7 +144,6 @@ mod tests {
         assert_eq!(results.len(), 1);
         let r = &results[0];
 
-        // RRF score = 1/(60+1) + 1/(60+1) = 2/61
         let expected = 2.0 / 61.0;
         assert!((r.rrf_score - expected).abs() < 1e-10);
         assert!((r.normalized_score - 1.0).abs() < f64::EPSILON);
@@ -177,7 +155,6 @@ mod tests {
         let results = rank_rrf(&vector, &[]);
 
         assert_eq!(results.len(), 2);
-        // Single result should still have normalized_score = 1.0
         assert!((results[0].normalized_score - 1.0).abs() < f64::EPSILON);
     }
 }
diff --git a/src/search/vector.rs b/src/search/vector.rs
index f882512..d60863e 100644
--- a/src/search/vector.rs
+++ b/src/search/vector.rs
@@ -5,16 +5,13 @@ use rusqlite::Connection;
 use crate::core::error::Result;
 use crate::embedding::chunk_ids::decode_rowid;
 
-/// A single vector search result (document-level, deduplicated).
 #[derive(Debug)]
 pub struct VectorResult {
     pub document_id: i64,
     pub distance: f64,
 }
 
-/// Query the maximum number of chunks per document for adaptive dedup sizing.
 fn max_chunks_per_document(conn: &Connection) -> i64 {
-    // Fast path: stored chunk_count on sentinel rows (post-migration 010)
     let stored: Option<i64> = conn
         .query_row(
             "SELECT MAX(chunk_count) FROM embedding_metadata
@@ -28,7 +25,6 @@ fn max_chunks_per_document(conn: &Connection) -> i64 {
         return max;
     }
 
-    // Fallback for pre-migration data: count chunks per document
     conn.query_row(
         "SELECT COALESCE(MAX(cnt), 1) FROM (
             SELECT COUNT(*) as cnt FROM embedding_metadata
@@ -40,12 +36,6 @@ fn max_chunks_per_document(conn: &Connection) -> i64 {
     .unwrap_or(1)
 }
 
-/// Search documents using sqlite-vec KNN query.
-///
-/// Over-fetches by an adaptive multiplier based on actual max chunks per document
-/// to handle chunk deduplication (multiple chunks per document produce multiple
-/// KNN results for the same document_id).
-/// Returns deduplicated results with best (lowest) distance per document.
 pub fn search_vector(
     conn: &Connection,
     query_embedding: &[f32],
@@ -55,7 +45,6 @@ pub fn search_vector(
         return Ok(Vec::new());
     }
 
-    // Convert to raw little-endian bytes for sqlite-vec
     let embedding_bytes: Vec<u8> = query_embedding
         .iter()
         .flat_map(|f| f.to_le_bytes())
@@ -79,7 +68,6 @@ pub fn search_vector(
         })?
         .collect::<std::result::Result<Vec<_>, _>>()?;
 
-    // Dedup by document_id, keeping best (lowest) distance
     let mut best: HashMap<i64, f64> = HashMap::new();
     for (rowid, distance) in rows {
         let (document_id, _chunk_index) = decode_rowid(rowid);
@@ -92,7 +80,6 @@ pub fn search_vector(
             .or_insert(distance);
     }
 
-    // Sort by distance ascending, take limit
     let mut results: Vec<VectorResult> = best
         .into_iter()
         .map(|(document_id, distance)| VectorResult {
@@ -110,29 +97,20 @@ pub fn search_vector(
 mod tests {
     use super::*;
 
-    // Note: Full integration tests require sqlite-vec loaded, which happens via
-    // create_connection in db.rs. These are basic unit tests for the dedup logic.
-
     #[test]
     fn test_empty_returns_empty() {
-        // Can't test KNN without sqlite-vec, but we can test edge cases
         let result = search_vector_dedup(vec![], 10);
         assert!(result.is_empty());
     }
 
     #[test]
     fn test_dedup_keeps_best_distance() {
-        // Simulate: doc 1 has chunks at rowid 1000 (idx 0) and 1001 (idx 1)
-        let rows = vec![
-            (1000_i64, 0.5_f64), // doc 1, chunk 0
-            (1001, 0.3),         // doc 1, chunk 1 (better)
-            (2000, 0.4),         // doc 2, chunk 0
-        ];
+        let rows = vec![(1000_i64, 0.5_f64), (1001, 0.3), (2000, 0.4)];
         let results = search_vector_dedup(rows, 10);
         assert_eq!(results.len(), 2);
-        assert_eq!(results[0].document_id, 1); // doc 1 best = 0.3
+        assert_eq!(results[0].document_id, 1);
         assert!((results[0].distance - 0.3).abs() < f64::EPSILON);
-        assert_eq!(results[1].document_id, 2); // doc 2 = 0.4
+        assert_eq!(results[1].document_id, 2);
     }
 
     #[test]
@@ -142,7 +120,6 @@ mod tests {
         assert_eq!(results.len(), 2);
     }
 
-    /// Helper for testing dedup logic without sqlite-vec
     fn search_vector_dedup(rows: Vec<(i64, f64)>, limit: usize) -> Vec<VectorResult> {
         let mut best: HashMap<i64, f64> = HashMap::new();
         for (rowid, distance) in rows {