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/model/agent_def/builtin.rs

@@ -1,5 +1,17 @@
+//! Hardcoded built-in subagent definitions (coder, reviewer, researcher, planner).
+
 use crate::app::subagent::spawn::AgentDefinition;
 
+/// Build the fixed list of built-in agent definitions shipped with zesdex.
+///
+/// Flow: construct each `AgentDefinition` with a name, system prompt, and
+/// allowed tool list, then collect into a `Vec`.
+///
+/// Why: these agents are always available regardless of global/session
+/// config, giving users a baseline set of roles out of the box.
+///
+/// Return: a freshly-built `Vec<AgentDefinition>` (coder, reviewer,
+/// researcher, planner).
 pub fn builtin_agents() -> Vec<AgentDefinition> {
     vec![
         AgentDefinition::new(

src/model/agent_def/global.rs

@@ -1,5 +1,19 @@
+//! Load, save, and remove user-defined agent definitions stored globally
+//! (under the store's `agents/` directory), independent of any session.
+
 use crate::app::subagent::spawn::AgentDefinition;
 
+/// Load all globally-registered agent definitions from disk.
+///
+/// Flow: resolve `<store>/agents/` → read directory → parse each `*.json`
+/// file into an `AgentDefinition`, skipping any that fail to read or parse.
+///
+/// Why: missing directory or unreadable/invalid files are silently
+/// skipped rather than failing the whole load, so one corrupt file
+/// doesn't break agent loading.
+///
+/// Return: a `Vec<AgentDefinition>`, empty if the directory doesn't exist
+/// or contains no valid definitions.
 pub fn load_global_agents() -> Vec<AgentDefinition> {
     let store = crate::model::store::Store::new();
     let agents_dir = store.base_dir.join("agents");
@@ -22,6 +36,16 @@ pub fn load_global_agents() -> Vec<AgentDefinition> {
     agents
 }
 
+/// Persist a global agent definition as `<store>/agents/<name>.json`.
+///
+/// Flow: ensure the `agents/` directory exists → serialize `def` to
+/// pretty JSON → write to a file named after `def.name`.
+///
+/// Why: writing by name overwrites any existing definition with the
+/// same name, acting as an upsert.
+///
+/// Return: `Ok(())` on success, or an error if directory creation,
+/// serialization, or the write fails.
 pub fn save_global_agent(def: &AgentDefinition) -> anyhow::Result<()> {
     let store = crate::model::store::Store::new();
     let agents_dir = store.base_dir.join("agents");
@@ -32,6 +56,14 @@ pub fn save_global_agent(def: &AgentDefinition) -> anyhow::Result<()> {
     Ok(())
 }
 
+/// Delete a global agent definition by name, if it exists.
+///
+/// Flow: resolve `<store>/agents/<name>.json` → remove the file if present.
+///
+/// Why: a no-op (not an error) when the file is already absent.
+///
+/// Return: `Ok(())` whether or not the file existed; `Err` only on an
+/// actual filesystem removal failure.
 pub fn remove_global_agent(name: &str) -> anyhow::Result<()> {
     let store = crate::model::store::Store::new();
     let path = store.base_dir.join("agents").join(format!("{}.json", name));

src/model/agent_def/mod.rs

@@ -1,3 +1,6 @@
+//! Agent definition sources: built-in defaults, global (user-wide), and
+//! per-session overrides.
+
 pub mod builtin;
 pub mod global;
 pub mod session;

src/model/agent_def/session.rs

@@ -1,6 +1,20 @@
+//! Load, save, add, and remove agent definitions scoped to a single
+//! session (`<session_dir>/agents.json`).
+
 use std::path::Path;
 use crate::app::subagent::spawn::AgentDefinition;
 
+/// Load agent definitions saved for a specific session.
+///
+/// Flow: check `<session_dir>/agents.json` exists → read → JSON-decode
+/// into `Vec<AgentDefinition>`.
+///
+/// Why: a missing file or a parse failure both degrade gracefully to an
+/// empty list (parse errors are logged via `tracing::warn!`), so a
+/// corrupt session file doesn't crash agent loading.
+///
+/// Return: the session's agent definitions, or an empty `Vec` if none
+/// exist or the file is malformed.
 pub fn load_session_agents(session_dir: &Path) -> Vec<AgentDefinition> {
     let agents_file = session_dir.join("agents.json");
     if !agents_file.exists() {
@@ -17,6 +31,13 @@ pub fn load_session_agents(session_dir: &Path) -> Vec<AgentDefinition> {
     }
 }
 
+/// Overwrite `<session_dir>/agents.json` with the given agent list.
+///
+/// Flow: serialize `agents` to pretty JSON → write to
+/// `<session_dir>/agents.json`.
+///
+/// Return: `Ok(())` on success, or an error if serialization or the
+/// write fails.
 pub fn save_session_agents(session_dir: &Path, agents: &[AgentDefinition]) -> anyhow::Result<()> {
     let agents_file = session_dir.join("agents.json");
     let content = serde_json::to_string_pretty(agents)?;
@@ -24,6 +45,14 @@ pub fn save_session_agents(session_dir: &Path, agents: &[AgentDefinition]) -> an
     Ok(())
 }
 
+/// Add or replace a session agent definition by name.
+///
+/// Flow: load existing session agents → drop any with the same name as
+/// `def` → push `def` → save the updated list.
+///
+/// Why: name-based dedup makes this an upsert rather than an append.
+///
+/// Return: `Ok(())` on success, propagating any load/save error.
 pub fn add_session_agent(session_dir: &Path, def: AgentDefinition) -> anyhow::Result<()> {
     let mut agents = load_session_agents(session_dir);
     agents.retain(|a| a.name != def.name);
@@ -31,6 +60,12 @@ pub fn add_session_agent(session_dir: &Path, def: AgentDefinition) -> anyhow::Re
     save_session_agents(session_dir, &agents)
 }
 
+/// Remove a session agent definition by name, if present.
+///
+/// Flow: load existing session agents → filter out entries matching
+/// `name` → save the updated list.
+///
+/// Return: `Ok(())` whether or not an entry with `name` existed.
 pub fn remove_session_agent(session_dir: &Path, name: &str) -> anyhow::Result<()> {
     let mut agents = load_session_agents(session_dir);
     agents.retain(|a| a.name != name);