diff --git a/crates/g3-core/src/lib.rs b/crates/g3-core/src/lib.rs
index 616a015..41d7371 100644
--- a/crates/g3-core/src/lib.rs
+++ b/crates/g3-core/src/lib.rs
@@ -153,6 +153,10 @@ pub struct Agent<W: UiWriter> {
 }
 
 impl<W: UiWriter> Agent<W> {
+    // =========================================================================
+    // CONSTRUCTION METHODS
+    // =========================================================================
+
     pub async fn new(config: Config, ui_writer: W) -> Result<Self> {
         Self::new_with_mode(config, ui_writer, false, false).await
     }
@@ -436,6 +440,10 @@ impl<W: UiWriter> Agent<W> {
         })
     }
 
+    // =========================================================================
+    // CONFIGURATION & PROVIDER RESOLUTION
+    // =========================================================================
+
     /// Validate that the system prompt is the first message in the conversation history.
     /// This is a critical invariant that must be maintained for proper agent operation.
     ///
@@ -772,6 +780,10 @@ impl<W: UiWriter> Agent<W> {
         self.session_id.as_deref()
     }
 
+    // =========================================================================
+    // TASK EXECUTION
+    // =========================================================================
+
     pub async fn execute_task(
         &mut self,
         description: &str,
@@ -1050,6 +1062,10 @@ impl<W: UiWriter> Agent<W> {
         Ok(task_result)
     }
 
+    // =========================================================================
+    // SESSION MANAGEMENT
+    // =========================================================================
+
     /// Generate a session ID based on the initial prompt
     fn generate_session_id(&self, description: &str) -> String {
         session::generate_session_id(description, self.agent_name.as_deref())
@@ -1124,6 +1140,10 @@ impl<W: UiWriter> Agent<W> {
         }
     }
 
+    // =========================================================================
+    // CONTEXT WINDOW OPERATIONS
+    // =========================================================================
+
     /// Manually trigger context compaction regardless of context window size
     /// Returns Ok(true) if compaction was successful, Ok(false) if it failed
     pub async fn force_compact(&mut self) -> Result<bool> {
@@ -1536,6 +1556,10 @@ impl<W: UiWriter> Agent<W> {
         );
     }
 
+    // =========================================================================
+    // STREAMING & LLM INTERACTION
+    // =========================================================================
+
     /// Build the final response and prepare for return.
     ///
     /// This is the single canonical path for completing a streaming turn:
@@ -2795,6 +2819,10 @@ Skip if nothing new. Be brief."#;
         ))
     }
 
+    // =========================================================================
+    // TOOL EXECUTION
+    // =========================================================================
+
     pub async fn execute_tool(&mut self, tool_call: &ToolCall) -> Result<String> {
         // Tool tracking is handled by execute_tool_in_dir
         self.execute_tool_in_dir(tool_call, None).await