docs(platform): Add README.md for all platform crates

crates/platform/auth/README.md

@@ -0,0 +1,17 @@
+# Owlen Auth Manager
+
+Unified authentication management for the Owlen AI agent.
+
+## Overview
+This crate manages the lifecycle of authentication credentials for various LLM providers. It supports both API key-based authentication and OAuth flows with automatic token refresh.
+
+## Features
+- **Multi-Source Credentials:** Load credentials from environment variables, secure storage, or command-line helpers.
+- **OAuth Integration:** Built-in support for device code flows and standard OAuth 2.0.
+- **Token Refresh:** Automatic background refreshing of expiring OAuth tokens.
+- **Secure Handling:** Leverages the `credentials` crate for encrypted storage.
+
+## Components
+- `AuthManager`: The central coordinator for all authentication logic.
+- `LoginFlow`: Manages the interactive login process for providers.
+- `Refresher`: Handles periodic checks and updates for expiring credentials.

crates/platform/config/README.md

@@ -0,0 +1,18 @@
+# Owlen Config Agent
+
+Configuration management for the Owlen AI agent.
+
+## Overview
+This crate handles loading, parsing, and persisting configuration settings. It uses a hierarchical approach, allowing global user settings to be overridden by project-specific configurations and environment variables.
+
+## Features
+- **Hierarchical Configuration:** Merges defaults, user config, project config, and env vars.
+- **Strong Typing:** Provides a type-safe `Settings` struct for application-wide use.
+- **Provider Preferences:** Manage model selections and provider-specific URLs.
+- **Permission Mapping:** Integrates with the `permissions` crate to define tool-use policies.
+
+## Usage
+Configuration is typically loaded via `load_settings()`, which looks for:
+1. `~/.config/owlen/config.toml` (Global)
+2. `<project_root>/.owlen.toml` (Project-specific)
+3. `OWLEN_*` environment variables (Overriding)

crates/platform/credentials/README.md

@@ -0,0 +1,18 @@
+# Owlen Credentials
+
+Secure credential storage for the Owlen AI agent.
+
+## Overview
+This crate provides a cross-platform abstraction for storing sensitive data like API keys and OAuth tokens. It prioritizes system-native keychains and falls back to encrypted file storage when necessary.
+
+## Features
+- **Keyring Support:** Native integration with macOS Keychain, Windows Credential Manager, and Linux Secret Service.
+- **Encrypted Fallback:** AES-encrypted JSON file storage (`~/.config/owlen/credentials.json`).
+- **Credential Helpers:** Support for external tools like `op` (1Password) or `bw` (Bitwarden).
+- **Security First:** Implements proper zeroing of sensitive memory where possible.
+
+## Components
+- `CredentialManager`: Primary interface for store/retrieve operations.
+- `KeyringStore`: System-native backend.
+- `FileStore`: Encrypted local file backend.
+- `HelperManager`: Integration with external credential CLI tools.

crates/platform/hooks/README.md

@@ -0,0 +1,17 @@
+# Owlen Hooks
+
+Plugin hook system for the Owlen AI agent.
+
+## Overview
+This crate enables extending the agent's behavior through a flexible hook system. It allows various parts of the application to emit events that plugins can intercept and respond to.
+
+## Features
+- **Lifecycle Hooks:** Register callbacks for key agent events (session start, tool execution, response generated).
+- **Synchronous & Asynchronous:** Supports both immediate and future-based hook handlers.
+- **Priority-Based Execution:** Fine-grained control over the order in which hooks are processed.
+
+## Common Hooks
+- `on_session_start`: Setup tasks when a new conversation begins.
+- `before_tool_execution`: Validate or modify tool arguments before they run.
+- `after_tool_execution`: Process or log tool results.
+- `on_message_received`: Intercept incoming user messages.

crates/platform/permissions/README.md

@@ -0,0 +1,19 @@
+# Owlen Permissions
+
+Safety and permission system for the Owlen AI agent.
+
+## Overview
+This crate implements the security policies that govern what tools the agent can execute. It ensures that dangerous operations (like `bash` or `write`) are only performed with explicit user consent or according to predefined rules.
+
+## Features
+- **Operation Modes:** 
+    - `Plan`: Read-only mode for planning.
+    - `AcceptEdits`: Automatically allow file modifications but prompt for system changes.
+    - `Code`: Full access mode.
+- **Rule-Based Access:** Define granular permissions for specific tools or path patterns.
+- **Decision Logic:** Centralized logic for `Allow`, `Ask`, and `Deny` decisions.
+
+## Components
+- `PermissionManager`: The core policy engine.
+- `Tool`: Enum representing all available system operations.
+- `PermissionRule`: A specific grant or restriction for a tool/context.

crates/platform/plugins/README.md

@@ -0,0 +1,14 @@
+# Owlen Plugins
+
+Plugin management system for the Owlen AI agent.
+
+## Overview
+This crate manages the loading and discovery of Owlen plugins. It handles plugin metadata, dependency resolution, and provides the interface for plugins to register their tools and hooks.
+
+## Features
+- **Discovery:** Scan directories for compatible plugin manifests.
+- **Isolation:** (Future) Ensure plugins run in a secure, isolated environment.
+- **Registration:** Seamlessly add new tools and command handlers to the agent.
+
+## Usage
+Plugins are typically located in `~/.owlen/plugins/` or project-local `.owlen/plugins/` directories. Each plugin is defined by a manifest file (e.g., `plugin.toml` or `.owlen-plugin.json`).