diff --git a/AGENTS.md b/AGENTS.md
index db5d68eb5..2c052b2c6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -106,6 +106,13 @@
 ## Troubleshooting
 - Rebrand/migration issues or legacy config/service warnings: run `openclaw doctor` (see `docs/gateway/doctor.md`).
 
+## Security & Secrets Handling
+- **Never Read/Write**: Never attempt to read or modify session files, logs, or credentials outside the authorized agent directories (`~/.clawdbot/`).
+- **Data Redaction**: Always mask or use placeholders for PII (phone numbers, emails) and secrets (API keys) in any logs, documentation, or screenshots.
+- **Credential Storage**: Use the authorized `authStorage` and `authStore` mechanisms; never hardcode keys or store them in plain text files.
+- **Tool Safety**: Exercise extreme caution with shell execution tools. Never execute commands that could lead to data exfiltration or unauthorized system access.
+- **Reporting**: If you encounter exposed credentials or security vulnerabilities during exploration, stop and alert the operator immediately.
+
 ## Agent-Specific Notes
 - Vocabulary: "makeup" = "mac app".
 - Never edit `node_modules` (global/Homebrew/npm/git installs too). Updates overwrite. Skill notes go in `tools.md` or `AGENTS.md`.
diff --git a/docs/channels/adding-channels.md b/docs/channels/adding-channels.md
new file mode 100644
index 000000000..4026b95dc
--- /dev/null
+++ b/docs/channels/adding-channels.md
@@ -0,0 +1,29 @@
+# New Channel Checklist
+
+Follow this guide when adding a new messaging channel or provider to Clawdbot.
+
+## 1. Extension Setup
+- [ ] Create a new directory in `extensions/<channel-name>`.
+- [ ] Initialize `package.json` and `clawdbot.plugin.json`.
+- [ ] Export a `ChannelPlugin` definition from the main entrypoint.
+
+## 2. Plugin SDK Implementation
+- [ ] Implement `capabilities` (polls, reactions, media).
+- [ ] Define `configSchema` for account settings.
+- [ ] Implement `gateway.startAccount` for lifecycle management.
+- [ ] Implement `outbound.sendText` and `outbound.sendMedia`.
+
+## 3. Docking & Routing
+- [ ] Register the channel in `src/channels/registry.ts` (if core) or via the plugin loader.
+- [ ] Add the channel to `CHAT_CHANNEL_ORDER` for UI ranking.
+- [ ] Verify message normalization in `src/auto-reply/dispatch.ts`.
+
+## 4. UI & Docs
+- [ ] Add UI metadata to the catalog in `src/channels/plugins/catalog.ts`.
+- [ ] Create a documentation page in `docs/channels/<channel-name>.md`.
+- [ ] Add the channel to the "Supported Channels" list in the main README.
+
+## 5. Verification
+- [ ] Run `pnpm lint` and `pnpm build`.
+- [ ] Test incoming message routing and agent reply delivery.
+- [ ] Verify account linking/login flow (e.g., QR code or API key).
diff --git a/docs/reference/RELEASING.md b/docs/reference/RELEASING.md
index f5bbd2373..1cb04e27b 100644
--- a/docs/reference/RELEASING.md
+++ b/docs/reference/RELEASING.md
@@ -10,6 +10,15 @@ read_when:
 
 Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tagging/publishing.
 
+## Release Sequence Summary
+1.  **Preparation**: Bump versions, sync plugins, and update CLI strings.
+2.  **Build**: Run `pnpm build` and bundle A2UI.
+3.  **Documentation**: Update `CHANGELOG.md` and README.
+4.  **Verification**: Execute linting, unit tests, and installer smoke tests.
+5.  **macOS Build**: Build, sign, and zip the macOS app; update Sparkle appcast.
+6.  **Publishing**: Publish to npm and create the GitHub release with artifacts.
+7.  **Final Ack**: Verify the published package via `npx`.
+
 ## Operator trigger
 When the operator says “release”, immediately do this preflight (no extra questions unless blocked):
 - Read this doc and `docs/platforms/mac/release.md`.
diff --git a/docs/reference/agent-roles.md b/docs/reference/agent-roles.md
new file mode 100644
index 000000000..cd62d18bf
--- /dev/null
+++ b/docs/reference/agent-roles.md
@@ -0,0 +1,38 @@
+# Agent Role Catalog
+
+Clawdbot utilizes a multi-agent architecture where different components have distinct responsibilities and guardrails.
+
+## Roles
+
+### 1. The Gateway
+- **Responsibility**: Management of messaging channels, routing, configuration, and API surface.
+- **Scope**: `src/gateway/`
+- **Ownership**: Core Infrastructure
+
+### 2. The Runner (Pi Embedded Runner)
+- **Responsibility**: Executing the core reasoning loop for an agent session.
+- **Scope**: `src/agents/pi-embedded-runner/`
+- **Ownership**: Agent Logic
+
+### 3. Subagents
+- **Responsibility**: Specialized tasks spawned by the main runner (e.g., browser automation, heavy data processing).
+- **Scope**: Managed via `src/agents/subagent-registry.ts`
+
+## Handoff Protocol
+
+When an agent needs to transition work or request assistance:
+1. **Tool Invocation**: The primary agent calls a subagent tool.
+2. **State Transfer**: The current session context (messages, files) is shared via the `SubagentRegistry`.
+3. **Control Return**: Upon completion, the subagent returns a structured result to the primary runner.
+
+## Blocked Behavior
+
+An agent is considered **blocked** if:
+- **Authentication Failure**: Multiple auth profiles for a provider are in cooldown or invalid.
+- **Context Overflow**: The history exceeds the model's window and cannot be compacted.
+- **Safety Violation**: The model refuses to generate a response due to safety filters.
+
+**Action on Blocked**:
+- Gateway emits a `chat:error` event.
+- The UI displays a distinct "Blocked" state with the reason.
+- For interactive sessions, the user is prompted to resolve (e.g., `/new` for context overflow).
diff --git a/docs/reference/ownership.md b/docs/reference/ownership.md
new file mode 100644
index 000000000..0647930c1
--- /dev/null
+++ b/docs/reference/ownership.md
@@ -0,0 +1,20 @@
+# Architecture & Code Ownership Map
+
+This map defines the primary domains and their respective owners within the Clawdbot codebase.
+
+| Domain | Scope | Primary Entrypoint | Owner |
+| :--- | :--- | :--- | :--- |
+| **CLI** | `src/cli/` | `src/entry.ts` | CLI Team |
+| **Gateway** | `src/gateway/` | `src/gateway/server.impl.ts` | Core Infra |
+| **Agent Runner** | `src/agents/` | `src/agents/pi-embedded-runner.ts` | AI Logic |
+| **Channels** | `src/channels/`, `src/web/` | `src/gateway/server-channels.ts` | Messaging |
+| **Extensions** | `extensions/` | `extensions/*/index.ts` | Plugins |
+| **Mobile Apps** | `apps/ios/`, `apps/android/` | N/A | Mobile Team |
+| **Mac App** | `apps/macos/` | N/A | Desktop Team |
+
+## Entrypoints for Exploration
+
+- **Initialize Logic**: `src/entry.ts` -> `src/cli/run-main.ts` -> `src/cli/program.ts`
+- **Main Server**: `src/gateway/server.impl.ts` (Gateway initialization)
+- **Message Flow**: `src/gateway/server-chat.ts` (Routing incoming to agent)
+- **Agent Loop**: `src/agents/pi-embedded-runner/run.ts`
diff --git a/docs/reference/tooling-policy.md b/docs/reference/tooling-policy.md
new file mode 100644
index 000000000..cb2341345
--- /dev/null
+++ b/docs/reference/tooling-policy.md
@@ -0,0 +1,27 @@
+# Tooling Policy
+
+To ensure consistency and reliability, agents and contributors should follow this tooling policy.
+
+## Preferred Tools
+
+### 1. Search & Exploration
+- **Primary**: `ripgrep` (via `grep_search` or CLI).
+- **Directory Listing**: `fd` or standard `ls`.
+- **Outline**: `view_file_outline` for quick structural understanding.
+
+### 2. File Editing
+- **Primary**: `multi_replace_file_content` for non-contiguous edits.
+- **Secondary**: `replace_file_content` for single blocks.
+- **New Files**: `write_to_file`.
+
+### 3. CI/CD & Build
+- **Package Manager**: `pnpm`.
+- **Runtime**: Node 22+ (Bun for local dev/testing).
+- **Linter/Formatter**: Oxlint / Oxfmt.
+
+## Agent Usage Guidelines
+
+- **Conciseness**: Keep edits minimal and focused. Avoid broad refactors unless requested.
+- **Verification**: Always run `pnpm lint` and `pnpm build` after making changes.
+- **Safety**: Do not use `rm -rf` or other destructive commands without high confidence and explicit need.
+- **Communication**: Use `notify_user` for blocking questions or artifact reviews.