docs: add item-level rustdoc to 7 worst-offender crates Refs #2137

248 doc comments added across 30 files:
- terraphim_grep: 91 items (95% gap -> <5%)
- terraphim-markdown-parser: 45 items (79% gap -> <5%)
- terraphim_usage: 68 items (68% gap -> <5%)
- terraphim_agent_messaging: 22 items
- terraphim_merge_coordinator: 13 items
- terraphim_file_search: 6 items
- terraphim_middleware: 3 items

All clippy/fmt checks pass on affected crates.

Co-Authored-By: Terraphim AI <noreply@terraphim.ai>

Author: Test User

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **terraphim_grep hybrid searcher** complete implementation: parallel KG + grep execution via `tokio::spawn`, CLI with thesaurus discovery, `Serialize` on `GrepResult`/`GrepStats`/`SufficiencyState` (Refs #1743, PR#1825, 2026-05-24)
 - **terraphim_merge_coordinator** minimal skeleton proving crate structure (Refs #1805, PR#1823, 2026-05-23)
 - **Config-error circuit-breaker** `ExitClass::ConfigError` quarantines agents after 3 consecutive config failures; `AgentDefinition.enabled` field; memory watchdog systemd units; `bigbox-sync.sh` (Refs #1817, PR#1822, 2026-05-23)
+- **Rustdoc gaps resolved** doc comments added to public items in `terraphim_grep` (95% gap, 91 items), `terraphim-markdown-parser` (79% gap, 45 items), `terraphim_usage` (68% gap, 68 items), `terraphim_agent_messaging` (22 items), `terraphim_file_search`, `terraphim_merge_coordinator`, and `terraphim_middleware` -- 248 doc comments added across 30 files (Refs #2137, 2026-06-05)
 - **Rustdoc gaps resolved** doc comments added to all public items in `terraphim_types` (`LlmUsage`, `LlmResult`, `ModelPricing`, `ReviewFinding`, `ReviewAgentOutput`, `FindingSeverity`, `FindingCategory`, `DocumentType`, `MarkdownDirectives`, `Scorer`, `Query`, `Similarity`, `ScoreError`, and score sub-modules) -- 93 warnings eliminated (2026-05-30)
 - **terraphim_rlm CLI binary** with 6 commands (code, bash, query, context, snapshot, status) for stateless RLM execution (Refs #RLM-CLI, 2026-05-18)
 - **MCP server RLM integration** via process spawning — 6 new tools exposed without linking terraphim_rlm (avoids static init hang) (Refs #RLM-CLI, 2026-05-18)

crates/terraphim-markdown-parser/src/chunk.rs

@@ -3,22 +3,32 @@ use ulid::Ulid;
 use crate::NormalizedMarkdown;
 use crate::heading::{HeadingNode, HeadingTree, SectionType};
 
+/// Represents a semantically coherent chunk of content under a heading, ready for indexing.
 #[derive(Debug, Clone)]
 pub struct ContentChunk {
+    /// The composite identifier combining content source, section path, and first block ULID.
     pub chunk_id: String,
+    /// The identifier of the source document this chunk belongs to.
     pub content_id: String,
+    /// The ordered list of block ULIDs whose text makes up this chunk.
     pub block_ids: Vec<Ulid>,
+    /// The chapter number assigned by depth-first traversal order, if applicable.
     pub chapter_number: Option<u8>,
+    /// The dot-separated path of section indices, e.g. `"1.2.3"`.
     pub section_path: String,
+    /// The classified section type for this chunk (main body, sidebar, career, assessment).
     pub chunk_type: SectionType,
+    /// The plain text content of the chunk with block-id comments stripped.
     pub text: String,
+    /// The approximate token count based on whitespace-delimited words.
     pub token_count: u32,
 }
 
 struct ChunkState {
     chapter_counter: u8,
 }
 
+/// Builds a flat list of [`ContentChunk`]s by traversing the heading tree depth-first.
 pub fn chunk_by_headings(
     content_id: &str,
     tree: &HeadingTree,

crates/terraphim-markdown-parser/src/heading.rs

@@ -15,11 +15,16 @@ pub enum MatchStrategy {
     Contains,
 }
 
+/// Describes the semantic role of a heading section in a document.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum SectionType {
+    /// The primary body content of the section.
     Main,
+    /// A named sidebar or callout box, identified by its label.
     Sidebar(String),
+    /// A career-focused section (e.g. "Selling U" textbook sections).
     Career,
+    /// An assessment or review section (e.g. key takeaways, quizzes).
     Assessment,
 }
 
@@ -34,19 +39,26 @@ impl std::fmt::Display for SectionType {
     }
 }
 
+/// Represents a single rule that maps a heading title pattern to a [`SectionType`].
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SectionPattern {
+    /// The string pattern to match against a heading title.
     pub pattern: String,
+    /// The section type to assign when the pattern matches.
     pub section_type: SectionType,
+    /// The strategy used to compare the heading title against `pattern`.
     pub match_strategy: MatchStrategy,
 }
 
+/// Represents an ordered collection of [`SectionPattern`] rules for classifying headings.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SectionConfig {
+    /// The ordered list of pattern rules; first match wins.
     pub rules: Vec<SectionPattern>,
 }
 
 impl SectionConfig {
+    /// Returns a default [`SectionConfig`] with common textbook section patterns pre-configured.
     pub fn textbook_default() -> Self {
         Self {
             rules: vec![
@@ -86,6 +98,7 @@ impl SectionConfig {
         }
     }
 
+    /// Classifies a heading `title` against the configured rules, returning the matched [`SectionType`].
     pub fn classify(&self, title: &str) -> SectionType {
         let title_trimmed = title.trim();
         for rule in &self.rules {
@@ -107,21 +120,31 @@ impl Default for SectionConfig {
     }
 }
 
+/// Represents a single node in the heading hierarchy tree.
 #[derive(Debug, Clone)]
 pub struct HeadingNode {
+    /// The heading depth level (1 for `#`, 2 for `##`, etc.).
     pub level: u8,
+    /// The plain-text title extracted from the heading.
     pub title: String,
+    /// The classified section type for this heading.
     pub section_type: SectionType,
+    /// The ULIDs of blocks whose content falls directly under this heading.
     pub blocks: Vec<Ulid>,
+    /// The child heading nodes nested beneath this heading.
     pub children: Vec<HeadingNode>,
+    /// The byte range in the source covering this heading and its content.
     pub byte_range: Range<usize>,
 }
 
+/// Represents the full heading hierarchy extracted from a normalised markdown document.
 #[derive(Debug, Clone)]
 pub struct HeadingTree {
+    /// The top-level heading nodes (depth-1 headings or document roots).
     pub roots: Vec<HeadingNode>,
 }
 
+/// Builds a [`HeadingTree`] from the AST embedded in a [`NormalizedMarkdown`] value.
 pub fn build_heading_tree(
     normalized: &NormalizedMarkdown,
 ) -> Result<HeadingTree, MarkdownParserError> {
@@ -134,6 +157,7 @@ pub fn build_heading_tree(
     Ok(tree)
 }
 
+/// Classifies every node in the heading tree in-place using the provided [`SectionConfig`].
 pub fn classify_sections(tree: &mut HeadingTree, config: &SectionConfig) {
     for root in &mut tree.roots {
         classify_node(root, config);

crates/terraphim-markdown-parser/src/lib.rs

@@ -21,6 +21,7 @@ pub use heading::{
     build_heading_tree, classify_sections,
 };
 
+/// The prefix used inside HTML comments to identify Terraphim block-id anchors.
 pub const TERRAPHIM_BLOCK_ID_PREFIX: &str = "terraphim:block-id:";
 
 /// Extract the first H1 heading from markdown content using AST parsing.
@@ -69,15 +70,21 @@ pub(crate) fn collect_text_content(nodes: &[Node]) -> String {
     text
 }
 
+/// Describes the structural kind of a Terraphim block.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BlockKind {
+    /// A standalone markdown paragraph block.
     Paragraph,
+    /// A markdown list-item block.
     ListItem,
 }
 
+/// Represents a single annotated content block extracted from normalised markdown.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Block {
+    /// The stable unique identifier assigned to this block.
     pub id: Ulid,
+    /// The structural kind of this block (paragraph or list item).
     pub kind: BlockKind,
 
     /// Byte span of the block in the markdown buffer.
@@ -93,13 +100,18 @@ pub struct Block {
     pub id_span: Range<usize>,
 }
 
+/// Represents markdown content that has been normalised with stable Terraphim block-id anchors.
 #[derive(Debug, Clone)]
 pub struct NormalizedMarkdown {
+    /// The normalised markdown source with all block-id comments inserted.
     pub markdown: String,
+    /// The ordered list of blocks extracted from the normalised source.
     pub blocks: Vec<Block>,
+    /// The parsed AST of the normalised markdown, if available.
     pub ast: Option<markdown::mdast::Node>,
 }
 
+/// Describes errors that can occur during markdown parsing and normalisation.
 #[derive(Debug, Error)]
 pub enum MarkdownParserError {
     #[error("failed to parse markdown: {0}")]

crates/terraphim_agent_messaging/src/delivery.rs

@@ -37,19 +37,30 @@ pub enum DeliveryStatus {
 /// Delivery record for tracking message delivery
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct DeliveryRecord {
+    /// The unique identifier of the tracked message.
     pub message_id: MessageId,
+    /// The sending agent, if known.
     pub from: Option<AgentPid>,
+    /// The intended recipient agent.
     pub to: AgentPid,
+    /// The current delivery status.
     pub status: DeliveryStatus,
+    /// Number of delivery attempts made so far.
     pub attempts: u32,
+    /// The UTC timestamp when the record was created.
     pub created_at: DateTime<Utc>,
+    /// The UTC timestamp of the most recent delivery attempt.
     pub last_attempt: Option<DateTime<Utc>>,
+    /// The UTC timestamp when the message was delivered.
     pub delivered_at: Option<DateTime<Utc>>,
+    /// The UTC timestamp when the message was acknowledged.
     pub acknowledged_at: Option<DateTime<Utc>>,
+    /// The error description from the most recent failed attempt.
     pub error_message: Option<String>,
 }
 
 impl DeliveryRecord {
+    /// Creates a new pending delivery record for the given message.
     pub fn new(message_id: MessageId, from: Option<AgentPid>, to: AgentPid) -> Self {
         Self {
             message_id,
@@ -65,31 +76,37 @@ impl DeliveryRecord {
         }
     }
 
+    /// Transitions the record to `InTransit` and increments the attempt counter.
     pub fn mark_in_transit(&mut self) {
         self.status = DeliveryStatus::InTransit;
         self.attempts += 1;
         self.last_attempt = Some(Utc::now());
     }
 
+    /// Transitions the record to `Delivered` and records the delivery timestamp.
     pub fn mark_delivered(&mut self) {
         self.status = DeliveryStatus::Delivered;
         self.delivered_at = Some(Utc::now());
     }
 
+    /// Transitions the record to `Acknowledged` and records the acknowledgement timestamp.
     pub fn mark_acknowledged(&mut self) {
         self.status = DeliveryStatus::Acknowledged;
         self.acknowledged_at = Some(Utc::now());
     }
 
+    /// Transitions the record to `Failed` and stores the error description.
     pub fn mark_failed(&mut self, error: String) {
         self.status = DeliveryStatus::Failed(error.clone());
         self.error_message = Some(error);
     }
 
+    /// Transitions the record to `Expired`.
     pub fn mark_expired(&mut self) {
         self.status = DeliveryStatus::Expired;
     }
 
+    /// Returns `true` if the record is in a terminal state (acknowledged, failed, or expired).
     pub fn is_final_state(&self) -> bool {
         matches!(
             self.status,
@@ -390,6 +407,7 @@ pub struct DeliveryStats {
 }
 
 impl DeliveryStats {
+    /// Returns the fraction of messages that were successfully acknowledged.
     pub fn success_rate(&self) -> f64 {
         if self.total_messages == 0 {
             0.0
@@ -398,6 +416,7 @@ impl DeliveryStats {
         }
     }
 
+    /// Returns the fraction of messages that failed delivery.
     pub fn failure_rate(&self) -> f64 {
         if self.total_messages == 0 {
             0.0
@@ -406,6 +425,7 @@ impl DeliveryStats {
         }
     }
 
+    /// Returns the average number of delivery attempts per message.
     pub fn average_attempts(&self) -> f64 {
         if self.total_messages == 0 {
             0.0

crates/terraphim_agent_messaging/src/mailbox.rs

@@ -37,17 +37,26 @@ impl Default for MailboxConfig {
 /// Mailbox statistics
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MailboxStats {
+    /// The identifier of the agent owning this mailbox.
     pub agent_id: AgentPid,
+    /// Total number of messages received since creation.
     pub total_messages_received: u64,
+    /// Total number of messages processed since creation.
     pub total_messages_processed: u64,
+    /// Current number of messages waiting in the queue.
     pub current_queue_size: usize,
+    /// Peak queue depth observed since creation.
     pub max_queue_size_reached: usize,
+    /// Timestamp of the most recently received message.
     pub last_message_received: Option<DateTime<Utc>>,
+    /// Timestamp of the most recently processed message.
     pub last_message_processed: Option<DateTime<Utc>>,
+    /// Running average time taken to process each message.
     pub average_processing_time: std::time::Duration,
 }
 
 impl MailboxStats {
+    /// Creates zeroed statistics for the given agent.
     pub fn new(agent_id: AgentPid) -> Self {
         Self {
             agent_id,
@@ -61,13 +70,15 @@ impl MailboxStats {
         }
     }
 
+    /// Records the receipt of a new message and updates queue-depth counters.
     pub fn record_message_received(&mut self) {
         self.total_messages_received += 1;
         self.current_queue_size += 1;
         self.max_queue_size_reached = self.max_queue_size_reached.max(self.current_queue_size);
         self.last_message_received = Some(Utc::now());
     }
 
+    /// Records a processed message and updates the running average processing time.
     pub fn record_message_processed(&mut self, processing_time: std::time::Duration) {
         self.total_messages_processed += 1;
         self.current_queue_size = self.current_queue_size.saturating_sub(1);

crates/terraphim_agent_messaging/src/message.rs

@@ -17,10 +17,12 @@ use crate::AgentPid;
 pub struct MessageId(pub Uuid);
 
 impl MessageId {
+    /// Creates a new randomly-generated `MessageId`.
     pub fn new() -> Self {
         Self(Uuid::new_v4())
     }
 
+    /// Returns the string representation of the message ID.
     pub fn as_str(&self) -> String {
         self.0.to_string()
     }
@@ -295,13 +297,18 @@ impl MessageEnvelope {
 
 /// Typed message wrapper for type-safe messaging
 pub struct TypedMessage<T> {
+    /// The unique identifier for this message.
     pub id: MessageId,
+    /// The sending agent, if known.
     pub from: Option<AgentPid>,
+    /// The typed message payload.
     pub payload: T,
+    /// The UTC timestamp when this message was created.
     pub created_at: DateTime<Utc>,
 }
 
 impl<T> TypedMessage<T> {
+    /// Creates a new `TypedMessage` wrapping the given payload.
     pub fn new(payload: T) -> Self {
         Self {
             id: MessageId::new(),
@@ -311,6 +318,7 @@ impl<T> TypedMessage<T> {
         }
     }
 
+    /// Sets the sending agent for this message.
     pub fn with_from(mut self, from: AgentPid) -> Self {
         self.from = Some(from);
         self

crates/terraphim_agent_messaging/src/router.rs

@@ -18,9 +18,13 @@ use crate::{
 /// Message router configuration
 #[derive(Debug, Clone)]
 pub struct RouterConfig {
+    /// Delivery guarantee settings used for all routed messages.
     pub delivery_config: DeliveryConfig,
+    /// How often the background task checks for messages to retry.
     pub retry_interval: Duration,
+    /// Maximum number of in-flight deliveries processed concurrently.
     pub max_concurrent_deliveries: usize,
+    /// Whether to collect routing metrics.
     pub enable_metrics: bool,
 }
 
@@ -38,10 +42,15 @@ impl Default for RouterConfig {
 /// Router statistics
 #[derive(Debug, Default, Clone)]
 pub struct RouterStats {
+    /// Total messages submitted to the router.
     pub messages_routed: u64,
+    /// Total messages successfully delivered.
     pub messages_delivered: u64,
+    /// Total messages that failed all delivery attempts.
     pub messages_failed: u64,
+    /// Number of currently registered agent routes.
     pub active_routes: usize,
+    /// Total retry attempts made by the background retry task.
     pub retry_attempts: u64,
 }