# Architecture Decision Records

Each file in this directory captures one architecture decision: the context, the choice, and its consequences. See the ADRs section in [`AGENTS.md`](../../AGENTS.md) for the rules on adding, updating, naming, and citing ADRs.

## Index

- [Local Runtime Architecture](local-runtime-architecture.md)
- [Approval And Audit Substrate](approval-and-audit-substrate.md) — supersedes [Trust Substrate](trust-substrate.md)
- [Browser Fill-Secret Tool](browser-fill-secret.md)
- [Browser Stealth Identity](browser-stealth-identity.md)
- [Browser Automation Engine — In-Process playwright-core, Not agent-browser](browser-automation-engine.md)
- [Per-Agent Browser Domain Policy](browser-domain-policy.md)
- [Instances And Control Surface](instances-and-control-surface.md)
- [Agent Loop With Native Tool Calling](agent-loop-tool-calling.md)
- [Deferred Tools (Load-On-Demand Catalog)](deferred-tools.md)
- [Self-Config Registry as Deferred Direct Tools](self-config-registry.md)
- [Subagent Delegation](subagent-delegation.md)
- [Agents Replace Profiles And Drive Runtime Behavior](agents-replace-profiles.md)
- [Per-Agent Provider Settings (Editable Override + In-Chat Settings Tab)](per-agent-provider-settings.md)
- [Model-First Selection (Models With Routes, Not Providers With Models)](model-first-selection.md)
- [Approval Mode (three-state policy)](approval-mode.md) — supersedes [dangerouslyAutoApprove](dangerously-auto-approve.md)
- [Per-Agent Memory Isolation](agent-memory-isolation.md)
- [Connector Secret Storage](connector-secret-storage.md)
- [Skills As Packages, Connectors As Credentials](skills-and-connectors.md)
- [Typed, Named Credentials Referenced By Name](typed-named-credentials.md)
- [Approval Execution Abort Protocol](approval-execution-abort.md)
- [Runtime Update Surface And Automatic Restart](runtime-update-surface.md)
- [Always-Up Supervision For launchd-Managed Instances](always-up-supervision.md)
- [Crash Reporting And Issue Filing](crash-reporting-and-issue-filing.md)
- [Connector + Provider Vocabulary, Spec Compliance, And Meta-Skills](connector-provider-spec-compliance.md)
- [Provider extraBody Escape Hatch And Reserved-Key Denylist](provider-extra-body.md)
- [Native Anthropic Messages Provider (First-Party Claude)](anthropic-messages-provider.md)
- [Amazon Bedrock Provider via the Converse API (Model-Agnostic, SigV4)](bedrock-converse-provider.md)
- [Azure OpenAI As A First-Class Provider](azure-provider.md)
- [Pinned in_memory Prompt-Cache Tier, No Active Warming](prompt-cache-in-memory-tier.md)
- [Telegram Messaging Bridge](telegram-bridge.md)
- [Discord Messaging Bridge](discord-bridge.md)
- [Email Watch](email-watch.md)
- [Pre-LLM Job Hooks](job-pre-run-hooks.md)
- [Job Concern Fan-Out](job-concern-fanout.md)
- [Runtime Identity Injection With Tell-Once + Delta + Periodic Refresh](runtime-identity-injection.md)
- [Runtime Identity Files (INSTRUCTIONS.md, SOUL.md, USER.md)](runtime-identity-files.md)
- [Identity-File Long-Horizon Design](identity-file-long-horizon-design.md)
- [Openclaw Migration](openclaw-migration.md)
- [BFF Trust Boundary For Privileged POSTs](bff-trust-boundary.md)
- [Gateway Reverse-Proxies The Web App As A Single Origin](gateway-web-reverse-proxy.md)
- [Tunnel Connectivity](tunnel-connectivity.md)
- [Device-Pairing Authentication (Loopback-Trusted, Relay-Gated)](device-pairing-auth.md)
- [Mobile Push Notifications (APNs + NSE + Inline Actions)](mobile-push-notifications.md)
- [Codex Session-Rotation Retry, UA Mirroring, And auth.json Race Handling](codex-session-rotation-retry.md)
- [Authorization vs SetupRequest](authorization-vs-setup-request.md)
- [User Choice Prompt (ask_user / chat.choice)](user-choice-prompt.md)
- [Skill Env Containment For terminal_exec And skill_run](skill-env-containment.md)
- [Per-Skill Connector Consent Grant](skill-connector-consent.md)
- [Multiple Tagged Google Accounts For The Workspace Skills](google-multi-account.md)
- [Chat-Driven Credential Provisioning](chat-credential-provisioning.md)
- [Provider Re-Authentication Guidance](provider-reauth-guidance.md)
- [Voice Messages With Gateway-Side Local Speech-To-Text](voice-messages-and-local-stt.md)
- [Chat File Attachments — Capability-Driven Delivery](chat-file-attachments.md)
- [One Chat Per Agent, Threads, And Job Channels](agent-chat-threads-and-channels.md)
- [Connector-Backed Web Search](web-search-connectors.md)
- [In-App Doc References Render Inline](in-app-doc-references.md)
- [Per-Agent Structured Database Primitive](agent-database.md)
- [In-App Log Viewing](logs-viewing.md)
