Docs: Comprehensive inline rustdoc and architectural summary PDF

chrs-agent/src/main.rs

@@ -1,3 +1,11 @@
+/// chrs-agent crate implements the core CHORUS agent runtime.
+///
+/// An agent runs a message loop that receives tasks from a `Mailbox`, logs them to a
+/// `DoltGraph` (the persistent state graph), and marks them as read. The design
+/// follows the CHORUS architectural pattern where agents are autonomous workers
+/// that interact through the `chrs_mail` messaging layer and maintain a provable
+/// execution history in the graph.
+
 use chrs_graph::DoltGraph;
 use chrs_mail::{Mailbox, Message};
 use chrono::Utc;
@@ -6,13 +14,36 @@ use std::time::Duration;
 use tokio::time::sleep;
 use uuid::Uuid;
 
-struct CHORUSAgent {
+/// Represents a running CHORUS agent.
+///
+/// # Fields
+/// * `id` – Logical identifier for the agent (e.g., "agent-001").
+/// * `mailbox` – The `Mailbox` used for inter‑agent communication.
+/// * `graph` – Persistence layer (`DoltGraph`) where task logs are stored.
+///
+/// # Rationale
+/// Agents are isolated units of work. By keeping a dedicated mailbox and a graph
+/// per agent we guarantee that each agent can be started, stopped, and reasoned
+/// about independently while still contributing to the global CHORUS state.
+pub struct CHORUSAgent {
     id: String,
     mailbox: Mailbox,
     graph: DoltGraph,
 }
 
 impl CHORUSAgent {
+    /// Initializes a new `CHORUSAgent`.
+    ///
+    /// This creates the filesystem layout under `base_path`, opens or creates the
+    /// SQLite mailbox, and initialises a `DoltGraph` for state persistence.
+    /// It also ensures that a `task_log` table exists for recording incoming
+    /// messages.
+    ///
+    /// # Parameters
+    /// * `id` – Identifier for the agent instance.
+    /// * `base_path` – Directory where the agent stores its data.
+    ///
+    /// Returns an instance ready to run its event loop.
     async fn init(id: &str, base_path: &Path) -> Result<Self, Box<dyn std::error::Error>> {
         let mail_path = base_path.join("mail.sqlite");
         let graph_path = base_path.join("state_graph");
@@ -32,6 +63,12 @@ impl CHORUSAgent {
         })
     }
 
+    /// Main event loop of the agent.
+    ///
+    /// It repeatedly polls the mailbox for pending messages addressed to this
+    /// agent, logs each message into the `task_log` table, commits the graph, and
+    /// acknowledges the message. The loop sleeps for a configurable interval to
+    /// avoid busy‑waiting.
     async fn run_loop(&self) {
         println!("Agent {} starting run loop...", self.id);
         loop {
@@ -60,6 +97,11 @@ impl CHORUSAgent {
     }
 }
 
+/// Entry point for the CHORUS agent binary.
+///
+/// It creates a data directory under `/home/Tony/rust/projects/reset/CHORUS/data`
+/// (note the capitalised `Tony` matches the original path), initialises the
+/// `CHORUSAgent`, and starts its run loop.
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let agent_id = "agent-001";