diff --git a/treetest/src/app/actions.rs b/treetest/src/app/actions.rs
index 68b5a63..09ea098 100644
--- a/treetest/src/app/actions.rs
+++ b/treetest/src/app/actions.rs
@@ -1,17 +1,29 @@
 //! User-triggered TUI actions.
+//!
+//! These handlers intentionally stay thin: each one maps one keypress to one
+//! simulator operation, then updates UI-local state such as the selected row and
+//! status message. Keeping them small makes it easier to audit which user action
+//! changed which part of the app state.
 
 use super::{App, AppError, NodeId, Selection};
 
 impl App {
+    /// Performs protocol introspection for the current selection.
+    ///
+    /// Rationale: node and leaf introspection share one key because the protocol
+    /// also shares one reserved procedure id for both operations.
     pub(super) fn perform_introspection(&mut self) -> Result<(), AppError> {
         match self.selected().clone() {
             Selection::Node(node_id) => {
+                // Route the blank procedure to endpoint-wide introspection.
                 let result = self.simulation.call_endpoint_introspection(node_id)?;
+                // Drain immediately so the inspector reflects the learned state.
                 let steps = self.simulation.drain()?;
                 self.refresh_selections(Some(node_id));
                 self.status = format!("{} ({steps} steps)", result.label);
             }
             Selection::Leaf { node_id, leaf_name } => {
+                // Route the blank procedure to one specific leaf.
                 let result = self
                     .simulation
                     .call_leaf_introspection(node_id, &leaf_name)?;
@@ -23,6 +35,10 @@ impl App {
         Ok(())
     }
 
+    /// Calls the currently selected echo leaf.
+    ///
+    /// Rationale: the payload is fixed so the demo highlights packet flow rather
+    /// than turning the TUI into a line editor.
     pub(super) fn perform_echo(&mut self) -> Result<(), AppError> {
         if let Selection::Leaf { node_id, leaf_name } = self.selected().clone() {
             let result =
@@ -37,6 +53,7 @@ impl App {
         Ok(())
     }
 
+    /// Calls the first endpoint-level procedure on the selected node.
     pub(super) fn perform_ping(&mut self) -> Result<(), AppError> {
         if let Selection::Node(node_id) = self.selected().clone() {
             if let Some(procedure_id) = self
@@ -63,6 +80,7 @@ impl App {
         Ok(())
     }
 
+    /// Calls the chunked-response procedure on the selected node.
     pub(super) fn perform_chunked(&mut self) -> Result<(), AppError> {
         if let Selection::Node(node_id) = self.selected().clone() {
             if let Some(procedure_id) = self
@@ -93,6 +111,7 @@ impl App {
         Ok(())
     }
 
+    /// Opens a long-lived chat hook on the selected node.
     pub(super) fn perform_chat_call(&mut self) -> Result<(), AppError> {
         if let Selection::Node(node_id) = self.selected().clone() {
             if let Some(procedure_id) = self
@@ -120,6 +139,10 @@ impl App {
         Ok(())
     }
 
+    /// Sends follow-up data on the newest known hook.
+    ///
+    /// Rationale: using the latest hook keeps the demo simple while still
+    /// exposing bidirectional hook behavior.
     pub(super) fn perform_chat_data(&mut self) -> Result<(), AppError> {
         if let Some(hook_id) = self.simulation.hook_ids().last().copied() {
             let result =
@@ -134,6 +157,7 @@ impl App {
         Ok(())
     }
 
+    /// Ends the newest known chat hook from the root side.
     pub(super) fn perform_chat_bye(&mut self) -> Result<(), AppError> {
         if let Some(hook_id) = self.simulation.hook_ids().last().copied() {
             let result = self.simulation.send_root_hook_data(hook_id, "bye", true)?;
@@ -146,10 +170,13 @@ impl App {
         Ok(())
     }
 
+    /// Injects intentionally invalid hook data to exercise fault handling.
     pub(super) fn perform_invalid_fault_demo(&mut self) -> Result<(), AppError> {
         if let Some(hook_id) = self.simulation.hook_ids().last().copied() {
+            // The root is always node zero in every built-in scenario.
             let root_id = NodeId(0);
             if self.simulation.tree.nodes.len() > 1 {
+                // The first child is enough to spoof a wrong peer path.
                 let attacker = NodeId(1);
                 let result = self.simulation.inject_invalid_peer_data(
                     attacker,
diff --git a/treetest/src/app/mod.rs b/treetest/src/app/mod.rs
index a1f21e9..8ed009d 100644
--- a/treetest/src/app/mod.rs
+++ b/treetest/src/app/mod.rs
@@ -1,4 +1,8 @@
 //! Ratatui application shell for the protocol demo.
+//!
+//! The `app` module only defines the high-level pieces and re-exports the entry
+//! point. The actual behavior is split into shell, actions, and UI modules so
+//! the control flow reads from broad orchestration down to specific rendering.
 
 mod actions;
 mod shell;
diff --git a/treetest/src/app/shell.rs b/treetest/src/app/shell.rs
index 290ea08..433268a 100644
--- a/treetest/src/app/shell.rs
+++ b/treetest/src/app/shell.rs
@@ -1,4 +1,8 @@
 //! Application lifecycle and event loop glue.
+//!
+//! This module owns terminal setup/teardown and the high-level event loop. The
+//! rest of the app modules assume they run inside this shell and therefore do
+//! not repeat raw-mode or alternate-screen management logic.
 
 use std::{io, time::Duration};
 
@@ -10,12 +14,18 @@ use crossterm::{
 
 use super::{App, AppError, DefaultTerminal, NodeId, built_in_scenarios, ui};
 
+/// Boots the terminal UI and guarantees cleanup on exit.
 pub(super) fn run() -> Result<(), AppError> {
+    // Enter raw mode first so every later keypress is visible to the app.
     enable_raw_mode()?;
     let mut stdout = io::stdout();
     execute!(stdout, EnterAlternateScreen)?;
+
+    // ratatui wraps the terminal backend after the alternate screen is active.
     let terminal = ratatui::init();
     let result = App::new()?.run(terminal);
+
+    // Restore terminal state even when the app exits through an error path.
     ratatui::restore();
     disable_raw_mode()?;
     execute!(io::stdout(), LeaveAlternateScreen)?;
@@ -23,14 +33,25 @@ pub(super) fn run() -> Result<(), AppError> {
 }
 
 impl App {
+    /// Creates the initial application state.
+    ///
+    /// The first built-in scenario is loaded immediately so the user sees a
+    /// working demo as soon as the TUI opens.
     pub(super) fn new() -> Result<Self, AppError> {
         let scenarios = built_in_scenarios();
+
+        // Start on the first scenario rather than waiting for manual selection.
         let simulation = crate::sim::Simulation::new(scenarios[0].clone())?;
+
+        // Build visible rows from the current inspector mode.
         let selections = ui::build_selections(&simulation);
+
+        // Prefer the scenario's declared initial focus when available.
         let selection_index = selections
             .iter()
             .position(|selection| *selection == simulation.initial_selection())
             .unwrap_or(0);
+
         Ok(Self {
             scenarios,
             scenario_index: 0,
@@ -41,9 +62,12 @@ impl App {
         })
     }
 
+    /// Runs the main draw/poll loop.
     pub(super) fn run(mut self, mut terminal: DefaultTerminal) -> Result<(), AppError> {
         loop {
             terminal.draw(|frame| self.render(frame))?;
+
+            // Poll with a timeout so redraws stay responsive without busy-spinning.
             if event::poll(Duration::from_millis(100))?
                 && let Event::Key(key) = event::read()?
                 && key.kind == KeyEventKind::Press
@@ -55,6 +79,7 @@ impl App {
         Ok(())
     }
 
+    /// Routes one keypress into one app action.
     pub(super) fn handle_key(&mut self, code: KeyCode) -> Result<bool, AppError> {
         match code {
             KeyCode::Char('q') => return Ok(false),
@@ -79,6 +104,8 @@ impl App {
                 }
             }
             KeyCode::Enter => {
+                // Enter cycles scenarios so the demo works even on keyboards
+                // without convenient left/right usage in some terminals.
                 let next = (self.scenario_index + 1) % self.scenarios.len();
                 self.load_scenario(next)?;
             }
@@ -92,6 +119,8 @@ impl App {
             KeyCode::Char('f') => self.perform_invalid_fault_demo()?,
             KeyCode::Char('g') => {
                 self.simulation.toggle_inspector_mode();
+
+                // Rebuild rows because realistic mode can hide undiscovered nodes.
                 self.refresh_selections(Some(self.selected().node_id()));
                 self.status = if self.simulation.is_realistic_mode() {
                     "Inspector switched to realistic mode.".to_owned()
@@ -101,6 +130,8 @@ impl App {
             }
             KeyCode::Char('m') => {
                 self.simulation.enable_realistic_mode_with_memory_reset();
+
+                // Jump to root because deeper selections may no longer be known.
                 self.refresh_selections(Some(NodeId(0)));
                 self.status =
                     "Cleared root memory for deeper nodes and enabled realistic mode.".to_owned();
@@ -122,21 +153,33 @@ impl App {
         Ok(true)
     }
 
+    /// Replaces the active scenario with a fresh simulation.
     pub(super) fn load_scenario(&mut self, index: usize) -> Result<(), AppError> {
         self.scenario_index = index;
+
+        // Rebuild from scratch so each scenario switch resets learned state,
+        // trace history, and active hooks.
         self.simulation = crate::sim::Simulation::new(self.scenarios[index].clone())?;
         self.refresh_selections(Some(self.simulation.initial_selection().node_id()));
         self.status = format!("Loaded scenario: {}", self.scenarios[index].name);
         Ok(())
     }
 
+    /// Returns the current tree selection.
     pub(super) fn selected(&self) -> &crate::model::Selection {
         &self.selections[self.selection_index]
     }
 
+    /// Rebuilds the visible selection list and preserves focus when possible.
+    ///
+    /// Rationale: realistic mode can hide items that ground-truth mode showed,
+    /// so selection repair needs to happen in one dedicated place.
     pub(super) fn refresh_selections(&mut self, preferred_node: Option<NodeId>) {
+        // Prefer an explicit node if the caller knows what should stay selected.
         let current = preferred_node.unwrap_or_else(|| self.selected().node_id());
         self.selections = ui::build_selections(&self.simulation);
+
+        // Fall back to the first row when the previous node disappeared.
         self.selection_index = self
             .selections
             .iter()
diff --git a/treetest/src/app/ui/panels/chrome.rs b/treetest/src/app/ui/panels/chrome.rs
index c8c0cca..d583870 100644
--- a/treetest/src/app/ui/panels/chrome.rs
+++ b/treetest/src/app/ui/panels/chrome.rs
@@ -16,7 +16,10 @@ use crate::{
 use super::super::super::App;
 
 impl App {
+    /// Renders the full non-modal application chrome.
     pub(crate) fn render(&self, frame: &mut Frame<'_>) {
+        // Split the screen into a small header, a large working area, and a
+        // persistent status/footer region.
         let chunks = Layout::default()
             .direction(Direction::Vertical)
             .constraints([
@@ -31,6 +34,7 @@ impl App {
         self.render_footer(frame, chunks[2]);
     }
 
+    /// Renders the scenario header bar.
     fn render_header(&self, frame: &mut Frame<'_>, area: Rect) {
         let mode = match self.simulation.inspector_mode {
             InspectorMode::GroundTruth => "ground truth",
@@ -49,6 +53,7 @@ impl App {
         );
     }
 
+    /// Renders the middle area with scenarios, tree, inspector, and trace panes.
     fn render_body(&self, frame: &mut Frame<'_>, area: Rect) {
         let columns = Layout::default()
             .direction(Direction::Horizontal)
@@ -59,6 +64,8 @@ impl App {
             ])
             .split(area);
 
+        // Keep scenario selection visible at all times so the user always knows
+        // which canned topology produced the current trace.
         let scenario_items = self
             .scenarios
             .iter()
@@ -93,6 +100,7 @@ impl App {
         self.render_hooks(frame, right[1]);
     }
 
+    /// Renders the trace pane.
     fn render_trace(&self, frame: &mut Frame<'_>, area: Rect) {
         let items = self
             .simulation
@@ -113,6 +121,7 @@ impl App {
         );
     }
 
+    /// Renders the hook table.
     fn render_hooks(&self, frame: &mut Frame<'_>, area: Rect) {
         let items = self
             .simulation
@@ -135,6 +144,7 @@ impl App {
         );
     }
 
+    /// Renders the footer with controls and the latest local event summary.
     fn render_footer(&self, frame: &mut Frame<'_>, area: Rect) {
         let help = vec![
             Line::from(self.status.clone()).style(Style::default().add_modifier(Modifier::BOLD)),
diff --git a/treetest/src/app/ui/panels/lists.rs b/treetest/src/app/ui/panels/lists.rs
index 7f3b75d..1cc6abe 100644
--- a/treetest/src/app/ui/panels/lists.rs
+++ b/treetest/src/app/ui/panels/lists.rs
@@ -14,6 +14,7 @@ use crate::{
 use super::super::super::App;
 
 impl App {
+    /// Renders the selection list for nodes and leaves.
     pub(super) fn render_selection_list(&self, frame: &mut Frame<'_>, area: Rect) {
         let items = self
             .selections
@@ -53,6 +54,10 @@ impl App {
     }
 }
 
+/// Builds the visible selection rows for the current inspector mode.
+///
+/// Rationale: realistic mode can only offer rows the root host already knows,
+/// while ground-truth mode intentionally exposes the entire scenario tree.
 pub(crate) fn build_selections(simulation: &Simulation) -> Vec<Selection> {
     let mut selections = Vec::new();
     let node_ids: Vec<_> = match simulation.inspector_mode {
diff --git a/treetest/src/scenarios/complex.rs b/treetest/src/scenarios/complex.rs
index 0da3924..45ee0a4 100644
--- a/treetest/src/scenarios/complex.rs
+++ b/treetest/src/scenarios/complex.rs
@@ -1,4 +1,8 @@
 //! Larger sandbox scenarios.
+//!
+//! The complex scenarios intentionally trade brevity for breadth. They combine
+//! several procedures and branches so the UI can serve as a sandbox after the
+//! smaller scenarios teach the mechanics.
 
 use crate::model::{
     EndpointProcedureKind, EndpointProcedureSpec, LeafKind, LeafSpec, NodeId, NodeSpec,
@@ -7,10 +11,12 @@ use crate::model::{
 
 use super::simple::{PROC_CHAT, PROC_CHUNKED, PROC_ECHO, PROC_PING};
 
+/// Returns the larger sandbox scenarios.
 pub(super) fn scenarios() -> Vec<ScenarioDefinition> {
     vec![complex_tree()]
 }
 
+/// Larger mixed-topology tree used as the free-play sandbox.
 fn complex_tree() -> ScenarioDefinition {
     ScenarioDefinition {
         name: "Complex Tree".to_owned(),
diff --git a/treetest/src/scenarios/simple.rs b/treetest/src/scenarios/simple.rs
index 60975fb..1f60f69 100644
--- a/treetest/src/scenarios/simple.rs
+++ b/treetest/src/scenarios/simple.rs
@@ -1,15 +1,24 @@
 //! Smaller onboarding scenarios.
+//!
+//! These scenarios are intentionally compact. Each one isolates one major part
+//! of the protocol so users can learn the tree, hook, and fault mechanics before
+//! switching to the larger sandbox topology.
 
 use crate::model::{
     EndpointProcedureKind, EndpointProcedureSpec, LeafKind, LeafSpec, NodeId, NodeSpec,
     ScenarioDefinition, Selection,
 };
 
+/// Single-response endpoint procedure used in small scenarios.
 pub(super) const PROC_PING: &str = "demo.endpoint.v1.control.ping";
+/// Multi-packet endpoint procedure used to visualize chunked responses.
 pub(super) const PROC_CHUNKED: &str = "demo.endpoint.v1.stream.chunked_greeting";
+/// Long-lived endpoint procedure used for bidirectional hook traffic.
 pub(super) const PROC_CHAT: &str = "demo.endpoint.v1.chat.session";
+/// Leaf echo contract used throughout the demos.
 pub(super) const PROC_ECHO: &str = "demo.leaf.v1.echo.invoke";
 
+/// Returns the onboarding scenarios in the order they should be explored.
 pub(super) fn scenarios() -> Vec<ScenarioDefinition> {
     vec![
         local_introspection(),
@@ -20,6 +29,7 @@ pub(super) fn scenarios() -> Vec<ScenarioDefinition> {
     ]
 }
 
+/// Minimal introspection walkthrough.
 fn local_introspection() -> ScenarioDefinition {
     ScenarioDefinition {
         name: "Local Introspection".to_owned(),
@@ -58,6 +68,7 @@ fn local_introspection() -> ScenarioDefinition {
     }
 }
 
+/// Simple leaf-call scenario.
 fn echo_leaf() -> ScenarioDefinition {
     ScenarioDefinition {
         name: "Echo Leaf".to_owned(),
@@ -97,6 +108,7 @@ fn echo_leaf() -> ScenarioDefinition {
     }
 }
 
+/// Multi-branch routing scenario.
 fn branch_routing() -> ScenarioDefinition {
     ScenarioDefinition {
         name: "Branch Routing".to_owned(),
@@ -156,10 +168,12 @@ fn branch_routing() -> ScenarioDefinition {
     }
 }
 
+/// Long-lived hook scenario.
 fn bidirectional_chat() -> ScenarioDefinition {
     ScenarioDefinition {
         name: "Bidirectional Chat".to_owned(),
-        description: "Keeps a hook active so the root can continue sending `Data` packets.".to_owned(),
+        description: "Keeps a hook active so the root can continue sending `Data` packets."
+            .to_owned(),
         highlights: vec![
             "After activation, either side may send hook data first.".to_owned(),
             "The chat handler exists outside the core runtime so the demo can show application-level behavior without changing the protocol.".to_owned(),
@@ -187,6 +201,7 @@ fn bidirectional_chat() -> ScenarioDefinition {
     }
 }
 
+/// Protocol-fault walkthrough.
 fn fault_showcase() -> ScenarioDefinition {
     ScenarioDefinition {
         name: "Fault Showcase".to_owned(),
diff --git a/treetest/src/sim/actions/driver.rs b/treetest/src/sim/actions/driver.rs
index c2bf5ba..7797c3a 100644
--- a/treetest/src/sim/actions/driver.rs
+++ b/treetest/src/sim/actions/driver.rs
@@ -14,6 +14,8 @@ impl Simulation {
         for node_id in 0..self.nodes.len() {
             match self.nodes[node_id].rx.try_recv() {
                 Ok(envelope) => {
+                    // Record ingress before handing the frame to the protocol
+                    // runtime so the trace shows the channel-level hop too.
                     self.record_trace(
                         NodeId(node_id),
                         format!("received frame via {:?}", envelope.ingress),
@@ -36,6 +38,7 @@ impl Simulation {
 
     /// Runs frames until the network becomes idle.
     pub fn drain(&mut self) -> Result<usize, SimError> {
+        // Count steps so callers can surface how much work one action caused.
         let mut steps = 0;
         while self.step()? {
             steps += 1;
diff --git a/treetest/src/sim/build.rs b/treetest/src/sim/build.rs
index e3bc069..35c9d1d 100644
--- a/treetest/src/sim/build.rs
+++ b/treetest/src/sim/build.rs
@@ -1,4 +1,7 @@
 //! Construction and mode-management helpers for the simulator.
+//!
+//! These helpers are kept separate from runtime packet flow so scenario boot and
+//! mode transitions remain easy to read and test in isolation.
 
 use std::collections::{BTreeMap, VecDeque};
 
@@ -12,12 +15,28 @@ use super::types::{ChatSession, SimError, SimNode, Simulation};
 
 impl Simulation {
     /// Creates a fresh simulation from a scenario definition.
+    ///
+    /// # Example
+    /// ```rust
+    /// use treetest::{scenarios::built_in_scenarios, sim::Simulation};
+    ///
+    /// let scenario = built_in_scenarios().into_iter().next().unwrap();
+    /// let simulation = Simulation::new(scenario).unwrap();
+    /// assert_eq!(simulation.node(treetest::model::NodeId(0)).display_path(), "/");
+    /// ```
     pub fn new(scenario: ScenarioDefinition) -> Result<Self, SimError> {
+        // Flatten the recursive scenario description once so the rest of the
+        // simulator can address nodes by stable ids.
         let tree = DemoTree::from_root(&scenario.root);
         let mut nodes = Vec::with_capacity(tree.nodes.len());
 
         for demo_node in &tree.nodes {
+            // Each endpoint gets one mailbox pair. The simulator never opens a
+            // real socket, so every hop is just channel delivery.
             let (tx, rx) = unbounded();
+
+            // Materialize child routes up front so the protocol runtime can make
+            // longest-prefix decisions without consulting the demo model again.
             let children = demo_node
                 .children
                 .iter()
@@ -26,6 +45,8 @@ impl Simulation {
                     state: ConnectionState::Registered,
                 })
                 .collect::<Vec<_>>();
+
+            // Translate demo leaf metadata into protocol-runtime leaf specs.
             let leaves = demo_node
                 .leaves
                 .iter()
@@ -37,6 +58,9 @@ impl Simulation {
                     },
                 })
                 .collect::<Vec<_>>();
+
+            // Parents are stored by path because the protocol runtime reasons in
+            // terms of endpoint paths rather than UI node ids.
             let parent_path = demo_node
                 .parent
                 .map(|parent_id| tree.node(parent_id).path.clone());
@@ -49,6 +73,7 @@ impl Simulation {
                     .map_err(|error| SimError::Protocol(error.to_string()))?;
             }
 
+            // Store the runtime endpoint alongside topology and mailbox state.
             nodes.push(SimNode {
                 parent: demo_node.parent,
                 children: demo_node.children.clone(),
@@ -58,6 +83,8 @@ impl Simulation {
             });
         }
 
+        // The root starts with only its own configuration plus direct-child
+        // awareness, which realistic mode later uses as its initial knowledge.
         let root_knowledge = RootKnowledge::new(&tree);
 
         Ok(Self {
@@ -65,6 +92,7 @@ impl Simulation {
             tree,
             nodes,
             root_id: NodeId(0),
+            // Tick counting starts at one so trace output reads naturally.
             next_tick: 1,
             trace: VecDeque::new(),
             recorded_events: Vec::new(),
@@ -86,6 +114,9 @@ impl Simulation {
     }
 
     /// Clears deeper root memory and switches the inspector into realistic mode.
+    ///
+    /// Rationale: this mirrors a host that only retains locally configured and
+    /// one-hop information until it learns more by introspection or traffic.
     pub fn enable_realistic_mode_with_memory_reset(&mut self) {
         self.root_knowledge.clear_deeper_than_one_hop();
         self.inspector_mode = InspectorMode::Realistic;