Improve protocol implementation

CLAUDE.md

@@ -16,7 +16,7 @@ Key routing rules:
 - Design system, brand → invoke design-consultation
 - Visual audit, design polish → invoke design-review
 - Architecture review → invoke plan-eng-review
-- Save progress, checkpoint, resume → invoke checkpoint
+- Save progress, checkpoint, resume → invoke context-save or context-restore
 - Code quality, health check → invoke health
 
 ## Execution standards
@@ -24,13 +24,78 @@ Key routing rules:
 - Use exact, current dependency versions. Never guess package versions. Check the latest available release before adding or updating any dependency. If a version conflict appears, first try to resolve it while keeping dependencies on their latest compatible releases. Only fall back to an older version when the conflict is truly unavoidable, and explain why.
 - Leave the project warning-free. Fix all compiler, linter, and tooling warnings before finishing. If a warning cannot be eliminated cleanly, silence it in the narrowest possible scope and add a short rationale.
 - Document code thoroughly. Add rustdoc, module docs, examples, and inline comments where they improve comprehension. Public APIs should be documented with clear meaning and examples. Non-obvious internal logic should also be documented. Comments should explain intent, invariants, and behavior, not restate syntax.
-- Maintain clear architecture. Do not allow files or functions to grow without bound. When code becomes too large or mixes concerns, split it into smaller modules, helper files, or folders with clear names. Prefer structure that improves readability, navigation, and maintenance.
+- Maintain clear architecture. Do not allow files or functions to grow without bound. When code becomes too large or mixes concerns, split it into smaller modules, helper files, or folders with clear names. Prefer structure that improves readability, navigation, and maintenance. 
+- If a file is longer than 500 lines, split it up however seen fit. Create a rust module in place of the file, then split each component of the file into it's own file. Split utils into their own files. If it's a really big struct, split the functions into their own files with pub(super) to prevent confusion.
+- If a function is longer than 150 lines, it must be split up as well. In this case, create a master function around multiple 'steps' to this larger one, describing in more detail how it works with appropriate comments.
 - Research library behavior when needed. Do not assume library APIs, feature flags, version compatibility, or known issues. Verify them, including online research when appropriate, before making decisions.
-- Commit at every real milestone. Create a local git commit each time a meaningful milestone is reached. Commit messages must be accurate, specific, and reflect the actual change.
+- Commit at every real milestone when implementation is allowed and the user has not forbidden commits. Create a local git commit each time a meaningful milestone is reached. Commit messages must be accurate, specific, and reflect the actual change.
 - Explain unintuitive choices. Whenever an implementation, algorithm, or control flow could appear backwards, surprising, or overly indirect, add a short rationale comment or documentation note explaining why it is correct.
 - Track work with TODOs. Use a task list throughout the work so progress, remaining steps, and milestone boundaries stay explicit.
 - ALL Sub-agents must be told to read this file before continuing.
 
+## Comments
+
+Because everything must be documented, comments should look like the below. This is a very unimportant function that isn't called often. Use significantly more description for more important ones.
+
+```rust
+/// Attaches `strace` to `process` and decodes reads/writes on `fd`.
+///
+/// This is passive: it observes the legacy host's serial traffic and never
+/// writes to the MCU device. It requires permission to attach to the target
+/// process and will return an error if the process is not running.
+pub fn trace_serial(process: &str, fd: u32) -> io::Result<()> { ... }
+```
+
+```rust
+/// Human-readable mapping for Elegoo `DeviceSensorStatus` sensor ids.
+///
+/// Source trail:
+/// - `serial-test/src/protocol/device_sensor_status.rs` shows `0x48` starts with
+///   a stable `sensor_id` and existing traces contain ids `0`, `1`, and `3`.
+/// - `config/cc2/printer_dsp.cfg` defines the corresponding CC2 sensors:
+///   `[ztemperature_sensor box] sensor_pin=PH0 #GPADC0`, `[heater_bed]
+///   sensor_pin=PH1 #GPADC1`, and `[extruder] sensor_pin=toolhead:PA3`.
+/// - `serial-test` samples show sensor id `1` carrying extruder up/down telemetry
+///   markers (`0x96`/`0x97`), so id `1` is the toolhead/extruder stream.
+///
+/// This is deliberately separate from `0x3d` live status: live `0x3d` fields are
+/// useful telemetry, but they are not stable object ids in the captured stream.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct SensorName { ... }
+```
+
+Add documentation for not what each struct and function does, but WHY as well. It's very important for debug purposes.
+
+In the case that a function is either user-facing in a library, or is used widely enough in a project to be considered a reference, add comments describing an example in how to use the function or struct.
+
+Also, add documentation inside of functions like the below:
+
+```rust
+pub fn is_watertight(&self) -> bool {
+    // Create the map of edges with an approximate amount of unique edges
+    let mut edge_map: AHashMap<(usize, usize), usize> =
+        AHashMap::with_capacity(self.indices.len() * 3 / 2);
+    
+    let mut check_edge = |a: usize, b: usize| {
+        // Always choose smaller edge first
+        let (a, b) = if b < a { (b, a) } else { (a, b) };
+    
+        // Find the pair of edges in the hash map
+        *edge_map.entry((a, b)).or_insert(0) += 1;
+    };
+    
+    // Check each edge on each triangle
+    for (a, b, c) in &self.indices {
+        check_edge(*a, *b);
+        check_edge(*b, *c);
+        check_edge(*a, *c);
+    }
+    
+    // Check if all edges come in pairs
+    edge_map.iter().all(|(_, checked)| *checked == 2)
+}
+```
+
 ## Plan mode rules
 
 - Plan mode is strictly read-only. When plan mode is active, do not edit files, write output files, change configuration, make commits, or perform any system modifications.