Enhance tool documentation and add new features

- Added module-level documentation for memory tools (`remember`, `recall`, `forget`) to clarify their purpose.
- Improved documentation in `recall.rs` and `remember.rs` to describe the functionality and flow of memory entry operations.
- Updated `mod.rs` to include descriptions for the tool trait and execution context.
- Enhanced `plan.rs` with detailed comments on plan-mode signaling tools.
- Documented text search tools in `search.rs` to explain their functionality.
- Improved sequential-thinking tool documentation in `seqthink.rs`.
- Added safety filter documentation in `shell_filter` for credential and git operations.
- Enhanced utility tools documentation, including `cd`, `dir_cache_update`, and `todowrite`.
- Improved rendering documentation in view modules (`chat`, `markdown`, `status`, `workflow`) to clarify rendering flows and purposes.

src/ipc/frame.rs

@@ -1,8 +1,28 @@
+//! Length-prefixed binary framing and JSON (de)serialization helpers for
+//! the IPC wire protocol.
+//!
+//! Flow: `write_frame`/`read_frame` handle the raw byte-level framing
+//! (4-byte big-endian length header + payload) over any `Read`/`Write`;
+//! `serialize_frame`/`deserialize_frame` handle the JSON layer on top.
+//! `Connection` (see `conn.rs`) composes both layers for a full send/receive.
+//!
+//! Why: a fixed-size length prefix lets the reader know exactly how many
+//! bytes to pull before attempting to parse, avoiding partial-JSON reads
+//! over a stream socket.
+
 use std::io::{Read, Write};
 use anyhow::Result;
 
+/// Upper bound on a single frame's byte size (64 MiB), enforced on both
+/// the write and read paths to bound memory use and reject malformed or
+/// malicious oversized length headers.
 pub(crate) const MAX_FRAME_SIZE: usize = 64 * 1024 * 1024;
 
+/// Write `data` as a length-prefixed frame: 4-byte big-endian length
+/// followed by the raw bytes, then flush.
+///
+/// Why: rejects frames over `MAX_FRAME_SIZE` to bound memory use on the
+/// reading side before any bytes are read.
 pub fn write_frame<W: Write>(writer: &mut W, data: &[u8]) -> Result<()> {
     let len = data.len();
     if len > MAX_FRAME_SIZE {
@@ -15,6 +35,14 @@ pub fn write_frame<W: Write>(writer: &mut W, data: &[u8]) -> Result<()> {
     Ok(())
 }
 
+/// Read one length-prefixed frame written by `write_frame`.
+///
+/// Flow: read 4-byte length header → on clean EOF before any bytes,
+/// return `Ok(None)` (peer closed) → validate against `MAX_FRAME_SIZE`
+/// → read the payload.
+///
+/// Return: `Ok(None)` signals a graceful connection close, distinct
+/// from an `Err` mid-frame I/O failure.
 pub fn read_frame<R: Read>(reader: &mut R) -> Result<Option<Vec<u8>>> {
     let mut len_buf = [0u8; 4];
     match reader.read_exact(&mut len_buf) {
@@ -31,6 +59,7 @@ pub fn read_frame<R: Read>(reader: &mut R) -> Result<Option<Vec<u8>>> {
     Ok(Some(buf))
 }
 
+/// Serialize `value` to JSON bytes, rejecting output over `MAX_FRAME_SIZE`.
 pub fn serialize_frame<T: serde::Serialize>(value: &T) -> Result<Vec<u8>> {
     let json = serde_json::to_vec(value)?;
     if json.len() > MAX_FRAME_SIZE {
@@ -39,6 +68,7 @@ pub fn serialize_frame<T: serde::Serialize>(value: &T) -> Result<Vec<u8>> {
     Ok(json)
 }
 
+/// Deserialize a frame's raw JSON bytes into `T`.
 pub fn deserialize_frame<'a, T: serde::Deserialize<'a>>(data: &'a [u8]) -> Result<T> {
     Ok(serde_json::from_slice(data)?)
 }