docs: consolidate design documentation and standardize crate English

crates/mcp/README.md

@@ -0,0 +1,7 @@
+# mcp
+
+`mcp` implements local stdio MCP server startup, JSON-RPC communication, discovery, and shutdown. The `worker` Feature owns decisions to register MCP Tools, resources, and prompts for models; this crate handles communication and process lifetime.
+
+## Main entry points
+
+- [`stdio`](src/stdio.rs): Server launch configuration resolution, bounded responses, diagnostics, and shutdown.

crates/mcp/src/lib.rs

@@ -1,7 +1,3 @@
-//! Model Context Protocol client foundations.
-//!
-//! This crate intentionally only owns protocol/lifecycle plumbing. It does not
-//! register MCP tools, resources, or prompts into Yoi's model-visible tool
-//! surface.
+#![doc = include_str!("../README.md")]
 
 pub mod stdio;

crates/mcp/src/stdio.rs

@@ -1,3 +1,20 @@
+//! Local stdio MCP server communication and process lifecycle.
+//!
+//! The Host resolves launch specs, clears the environment, and passes only explicit
+//! values to child processes. Values resolved from SecretStore or inherited from
+//! the environment are redacted in diagnostics. This is not a sandbox: child
+//! execution capabilities depend on Host and OS user boundaries.
+//!
+//! Handles stdout as JSON-RPC and stderr as bounded diagnostics, separately.
+//! Limits line lengths, response bytes, discovery pages, and request deadlines;
+//! malformed communication is not registered as valid descriptors. Requests are
+//! accepted only after the initialize/initialized handshake. Shutdown closes stdin,
+//! waits for exit within a deadline, and kills/waits to reap the process if needed.
+//! Startup failures also trigger cleanup; killing on Drop is a last resort.
+//!
+//! This module preserves Tool/resource/prompt wire values. `worker::feature::mcp`
+//! owns Yoi naming, schema acceptance, model output limits, and Feature registration.
+
 use std::collections::{BTreeMap, BTreeSet, VecDeque};
 use std::env;
 use std::fmt;