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/tool/workflow.rs

@@ -1,8 +1,23 @@
+//! Tools for orchestrating multi-agent workflow runs.
+//!
+//! Flow: the LLM emits a `workflow_run` tool call with a JSON-encoded
+//! `WorkflowScript` (Agent/Parallel/Pipeline/Phase primitives) which is
+//! deserialized and handed to `app::workflow::engine::run_workflow` for
+//! execution. Sibling agents spawned within the same run can share
+//! ephemeral text via the `note_finding` tool, which forwards to
+//! `app::workflow::engine::note_finding`.
+//!
+//! Why: decomposing a task into a workflow script lets the harness fan
+//! out independent subtasks (parallel/pipeline/phased) instead of the
+//! agent handling everything inline; simple tasks should skip this tool
+//! entirely per its own description string.
+
 use serde_json::{json, Value};
 use anyhow::{Result, anyhow};
 use super::Tool;
 use super::ToolCtx;
 
+/// Tool that parses and executes a JSON-encoded workflow script (Agent/Parallel/Pipeline/Phase).
 pub struct WorkflowRun;
 
 impl Tool for WorkflowRun {
@@ -31,6 +46,18 @@ impl Tool for WorkflowRun {
         })
     }
 
+    /// Parse the `script`/`args` tool arguments and execute the workflow.
+    ///
+    /// Flow: extract `script` string → deserialize into `WorkflowScript` →
+    /// collect optional `args` object into a `HashMap<String, String>` for
+    /// `{{key}}` template substitution → delegate to
+    /// `app::workflow::engine::run_workflow`.
+    ///
+    /// Why: template args are silently filtered to string values only
+    /// (non-string values are dropped rather than erroring).
+    ///
+    /// Return: the workflow engine's output string, or an error if the
+    /// script argument is missing or fails to parse as JSON.
     fn run(&self, _ctx: &ToolCtx, args: &Value) -> Result<String> {
         let script_str = args.get("script")
             .and_then(|v| v.as_str())
@@ -53,6 +80,7 @@ impl Tool for WorkflowRun {
     }
 }
 
+/// Tool that shares a text finding with sibling agents in the current workflow run.
 pub struct NoteFinding;
 
 impl Tool for NoteFinding {
@@ -77,6 +105,17 @@ impl Tool for NoteFinding {
         })
     }
 
+    /// Record `text` as a finding visible to sibling agents in the run.
+    ///
+    /// Flow: extract `text` argument → forward to
+    /// `app::workflow::engine::note_finding` → return a truncated
+    /// confirmation echo.
+    ///
+    /// Why: findings are ephemeral (not persisted to memory) and are
+    /// meant to be prepended to sibling agents' next tool-round context.
+    ///
+    /// Return: confirmation string containing up to the first 80 chars
+    /// of the recorded text.
     fn run(&self, _ctx: &ToolCtx, args: &Value) -> Result<String> {
         let text = args.get("text")
             .and_then(|v| v.as_str())