Merge pull request #1008 from zeroclaw-labs/fix/docs-module-level-docs

docs(code): add module-level doc blocks to providers, channels, tools, and security

src/channels/mod.rs

@@ -1,3 +1,19 @@
+//! Channel subsystem for messaging platform integrations.
+//!
+//! This module provides the multi-channel messaging infrastructure that connects
+//! ZeroClaw to external platforms. Each channel implements the [`Channel`] trait
+//! defined in [`traits`], which provides a uniform interface for sending messages,
+//! listening for incoming messages, health checking, and typing indicators.
+//!
+//! Channels are instantiated by [`start_channels`] based on the runtime configuration.
+//! The subsystem manages per-sender conversation history, concurrent message processing
+//! with configurable parallelism, and exponential-backoff reconnection for resilience.
+//!
+//! # Extension
+//!
+//! To add a new channel, implement [`Channel`] in a new submodule and wire it into
+//! [`start_channels`]. See `AGENTS.md` §7.2 for the full change playbook.
+
 pub mod cli;
 pub mod dingtalk;
 pub mod discord;

src/providers/mod.rs

@@ -1,3 +1,21 @@
+//! Provider subsystem for model inference backends.
+//!
+//! This module implements the factory pattern for AI model providers. Each provider
+//! implements the [`Provider`] trait defined in [`traits`], and is registered in the
+//! factory function [`create_provider`] by its canonical string key (e.g., `"openai"`,
+//! `"anthropic"`, `"ollama"`, `"gemini"`). Provider aliases are resolved internally
+//! so that user-facing keys remain stable.
+//!
+//! The subsystem supports resilient multi-provider configurations through the
+//! [`ReliableProvider`](reliable::ReliableProvider) wrapper, which handles fallback
+//! chains and automatic retry. Model routing across providers is available via
+//! [`create_routed_provider`].
+//!
+//! # Extension
+//!
+//! To add a new provider, implement [`Provider`] in a new submodule and register it
+//! in [`create_provider_with_url`]. See `AGENTS.md` §7.1 for the full change playbook.
+
 pub mod anthropic;
 pub mod bedrock;
 pub mod compatible;

src/security/mod.rs

@@ -1,3 +1,23 @@
+//! Security subsystem for policy enforcement, sandboxing, and secret management.
+//!
+//! This module provides the security infrastructure for ZeroClaw. The core type
+//! [`SecurityPolicy`] defines autonomy levels, workspace boundaries, and
+//! access-control rules that are enforced across the tool and runtime subsystems.
+//! [`PairingGuard`] implements device pairing for channel authentication, and
+//! [`SecretStore`] handles encrypted credential storage.
+//!
+//! OS-level isolation is provided through the [`Sandbox`] trait defined in
+//! [`traits`], with pluggable backends including Docker, Firejail, Bubblewrap,
+//! and Landlock. The [`create_sandbox`] function selects the best available
+//! backend at runtime. An [`AuditLogger`] records security-relevant events for
+//! forensic review.
+//!
+//! # Extension
+//!
+//! To add a new sandbox backend, implement [`Sandbox`] in a new submodule and
+//! register it in [`detect::create_sandbox`]. See `AGENTS.md` §7.5 for security
+//! change guidelines.
+
 pub mod audit;
 #[cfg(feature = "sandbox-bubblewrap")]
 pub mod bubblewrap;

src/tools/mod.rs

@@ -1,3 +1,20 @@
+//! Tool subsystem for agent-callable capabilities.
+//!
+//! This module implements the tool execution surface exposed to the LLM during
+//! agentic loops. Each tool implements the [`Tool`] trait defined in [`traits`],
+//! which requires a name, description, JSON parameter schema, and an async
+//! `execute` method returning a structured [`ToolResult`].
+//!
+//! Tools are assembled into registries by [`default_tools`] (shell, file read/write)
+//! and [`all_tools`] (full set including memory, browser, cron, HTTP, delegation,
+//! and optional integrations). Security policy enforcement is injected via
+//! [`SecurityPolicy`](crate::security::SecurityPolicy) at construction time.
+//!
+//! # Extension
+//!
+//! To add a new tool, implement [`Tool`] in a new submodule and register it in
+//! [`all_tools_with_runtime`]. See `AGENTS.md` §7.3 for the full change playbook.
+
 pub mod browser;
 pub mod browser_open;
 pub mod composio;