diff --git a/docs/architecture/settings-integration-configuration-model.md b/docs/architecture/settings-integration-configuration-model.md
index b7aa4659..8fff4fc5 100644
--- a/docs/architecture/settings-integration-configuration-model.md
+++ b/docs/architecture/settings-integration-configuration-model.md
@@ -1,79 +1,84 @@
 # Settings Integration Configuration Model
 
-This document records the current logical model behind Settings -> Integrations,
-with the provider catalog aligned to the bridge-only design.
+Last Updated: 2026-04-13
+
+本文件记录当前 `Settings -> Integrations` 在主链中的职责边界。
 
 ## Current Rule
 
-- Settings only manages bridge connection parameters and account sync metadata.
-- The provider picker is not derived from local endpoint presets.
-- `xworkmate-bridge` is the only source of truth for the provider catalog.
+- Settings 只管理 bridge connection 参数与 account sync 元数据
+- app 不从本地 endpoint preset、旧 module 配置、历史 fallback 恢复 provider catalog
+- `xworkmate-bridge` 是 provider catalog、gateway capability、routing resolve 的唯一真源
 
-## Bridge-Only Provider Source Of Truth
+## Bridge-Owned Source Of Truth
 
 ```mermaid
 flowchart TD
-  A["Settings UI
-  仅管理 Bridge 连接参数
-  与账号同步元数据"] --> G["acp.capabilities"]
-  G --> H["providerCatalog[]
-  singleAgent / multiAgent"]
+  subgraph SETTINGS["Settings surface"]
+    A["SettingsPage / SettingsAccountPanel"]
+    B["bridge connection params<br/>account sync metadata<br/>secure refs"]
+    A --> B
+  end
 
-  H --> I["refreshSingleAgentCapabilitiesRuntimeInternal()"]
-  I --> J["bridgeProviderCatalogInternal
-  App 内唯一 provider 名单源"]
-  I --> K["singleAgentCapabilitiesByProviderInternal
-  App 内唯一 provider 可用性源"]
+  subgraph BRIDGE["Bridge contract"]
+    C["acp.capabilities"]
+    D["xworkmate.routing.resolve"]
+    E["xworkmate.gateway.*"]
+    B --> C
+  end
 
-  G --> L["refreshAcpCapabilitiesRuntimeInternal()"]
-  L --> M["GatewayAcpCapabilities
-  providerCatalog / singleAgent / multiAgent"]
-  M --> N["mergeAcpCapabilitiesIntoMountTargetsRuntimeInternal()"]
-  N --> O["ManagedMountTargetState
-  codex / opencode / claude / gemini / aris / openclaw
-  available / discoveryState"]
+  subgraph APPSTATE["App-side derived state"]
+    F["refreshSingleAgentCapabilitiesRuntimeInternal()"]
+    G["bridgeProviderCatalogInternal"]
+    H["singleAgentCapabilitiesByProviderInternal"]
+    I["refreshAcpCapabilitiesRuntimeInternal()"]
+    J["GatewayAcpCapabilities"]
+    K["mergeAcpCapabilitiesIntoMountTargetsRuntimeInternal()"]
+    L["ManagedMountTargetState"]
+    C --> F --> G
+    F --> H
+    C --> I --> J --> K --> L
+  end
 
-  J --> P["bridgeProviderCatalog
-  = bridgeProviderCatalogInternal"]
-  P --> Q["singleAgentProviderOptions
-  Composer / Thread Picker 唯一数据源"]
+  subgraph UI["Visible affordances"]
+    M["assistant provider picker"]
+    N["available assistant targets"]
+    O["settings gateway connection affordances"]
+    G --> M
+    H --> N
+    L --> O
+  end
 
-  K --> R["availableSingleAgentProviders
-  = bridge 当前可用 provider"]
-  R --> S["visibleAssistantExecutionTargets(...)
-  agent / gateway 是否显示
-  只看 bridge runtime capabilities"]
-
-  O --> T["visible gateway affordances
-  gateway discovery 只看 bridge capabilities"]
-
-  Q --> U["setSingleAgentProvider(providerId)
-  仅写入 thread executionBinding.providerId"]
-
-  U --> V["singleAgentProviderForSession()
-  恢复线程已选 providerId"]
-
-  V --> W["sendSingleAgentMessageDesktopGoTaskFlowInternal()"]
-  W --> X["xworkmate.routing.resolve"]
-  X --> Y["bridge 返回 resolvedExecutionTarget /
-  resolvedProviderId /
-  unavailableCode /
-  unavailableMessage"]
-
-  Y --> Z{"unavailable?"}
-  Z -->|"no"| AA["executeTask(... resolved routing ...)"]
-  Z -->|"yes"| AB["provider unavailable UX
-  直接使用 bridge unavailable message"]
+  subgraph EXEC["Execution"]
+    P["setSingleAgentProvider(providerId)"]
+    Q["singleAgentProviderForSession()"]
+    R["executeTask(...)"]
+    S["resolved provider / unavailable message"]
+    T["provider unavailable UX"]
+    M --> P --> Q --> R
+    R --> D --> S
+    S --> T
+    O --> E
+  end
 ```
 
+## What Settings Owns
+
+- bridge host / transport / auth input
+- account-linked bridge configuration metadata
+- secure secret references
+- gateway connection test / connect / disconnect affordance
+
+## What Settings Does Not Own
+
+- 独立 provider catalog
+- 独立 module matrix
+- app-side gateway preset backfill
+- 旧 `ai_gateway` / `secrets` / `account` 页面壳
+
 ## Notes
 
-- Production cloud mode does not use app-side provider sync.
-- Provider visibility and picker contents come from
-  `acp.capabilities.providerCatalog`.
-- Auto-provider resolution and unavailable messaging come from
-  `xworkmate.routing.resolve`.
-- `openclaw` and other mount-target discovery states are also bridge-owned and
-  come from ACP capabilities merged into `ManagedMountTargetState`.
-- Persisted thread `providerId` restores the user's previous selection, but it
-  does not repopulate the provider catalog.
+- `providerCatalog` 只负责 assistant provider picker；不会因为线程里保存过 `providerId` 就被 app 反向重建
+- gateway runtime 可见性来自 bridge capability snapshot 与 `xworkmate.gateway.*` 返回，不来自旧设置页枚举
+- bridge 若返回额外 capability flag，这些 flag 只属于合同元数据，不会自动生成新的 settings tab 或 module page
+- production provider / gateway 选择继续由 bridge 拥有，app 只保留消费与展示
diff --git a/docs/architecture/task-control-plane-unification.md b/docs/architecture/task-control-plane-unification.md
index 2c0aaa56..0d458bab 100644
--- a/docs/architecture/task-control-plane-unification.md
+++ b/docs/architecture/task-control-plane-unification.md
@@ -1,197 +1,108 @@
-# 任务执行链路统一收敛
+# Task Control Plane Unification
 
-Last Updated: 2026-04-11
+Last Updated: 2026-04-13
 
-## 背景
+## Background
 
-当前仓库里已经存在 `GoTaskService`、Go ACP `Router.Resolve`、`Skills.Resolve`、
-`Memory` 与 `buildResolvedExecutionParams`，说明统一控制面已经具备核心骨架。
+当前 `xworkmate-app` 的主链已经不是“多模块并列入口”模型，而是：
 
-但旧设计文档长期把不同实现通道写成并列主链，导致：
+- shell 只保留 `assistant + settings`
+- assistant 负责线程、任务、结果与 bridge task/runtime 主链
+- settings 负责 bridge connection、account sync、integration affordance
+- app 不再维护本地 provider preset、旧 gateway 直连叙述、模块页矩阵
 
-- Desktop / Web / Mobile 的现状与目标混在一起
-- controller 层的历史分流被误认为长期规范
-- `local / remote / multi-agent` 被描述成 app 侧一级执行路径
+本文件定义的统一口径是：
 
-本文件把官方口径统一为：
+- app 内任务入口统一走 `GoTaskService.executeTask`
+- bridge capability / routing / gateway runtime 由 `xworkmate-bridge` 提供
+- app 只消费 bridge 合同，不重建第二套 provider/gateway 真源
 
-- UI 不变
-- `GoTaskService.executeTask` 是唯一公开入口
-- ACP 是统一控制面
-- `bridge` 是 app 客户端的发现 / 配置 / 连接 / 对话枢纽
-- app 当前只保留 `agent / gateway` 两条路径
-- ACP Server list / gateway upstream 由 `xworkmate-bridge` 动态发现与维护
-- `$INTERNAL_SERVICE_TOKEN` 仅属于 bridge / internal service 注入责任
-- 账户同步只同步 bridge 相关配置属性与安全引用，不做自动连接
+## Canonical Mainline
 
-
-## 目标态
 ```mermaid
 flowchart TD
-    subgraph APP["App surfaces"]
-        A["Desktop / Web / Mobile UI"]
-        B["sendMessage<br/>Task Envelope"]
-        C["GoTaskService.executeTask<br/>唯一公开入口"]
-        A --> B --> C
+    subgraph APP["xworkmate-app"]
+        A1["AssistantPage"]
+        A2["SettingsPage"]
+        A3["AppControllerDesktop*"]
+        A4["GoTaskService.executeTask"]
+        A5["GatewayAcpClient / ExternalCodeAgentAcpDesktopTransport"]
+        A1 --> A3
+        A2 --> A3
+        A3 --> A4
+        A3 --> A5
     end
 
-    subgraph ACP["ACP control plane"]
-        D["ACP.session.start / session.message"]
-        E["Router.Resolve"]
-        F["Skills.Resolve"]
-        G["Memory.Inject"]
-        H["buildResolvedExecutionParams"]
-        I{"resolvedExecutionPath"}
-        D --> E --> F --> G --> H --> I
+    subgraph CONTRACT["Bridge-facing contract"]
+        B1["acp.capabilities"]
+        B2["xworkmate.routing.resolve"]
+        B3["session.start / session.message / session.cancel / session.close"]
+        B4["xworkmate.gateway.connect / request / disconnect"]
     end
 
     subgraph BRIDGE["xworkmate-bridge"]
-        J["agent route"]
-        K["gateway route"]
-        L["bridge routing hub<br/>dynamic discovery / policy / auth injection"]
-        M["Provider adapters<br/>codex / opencode / claude / gemini"]
-        N["Gateway adapters<br/>openclaw / aris / hosted gateway capability"]
-        J --> L
-        K --> L
-        L --> M
-        L --> N
+        C1["bridge-owned provider catalog"]
+        C2["bridge-owned routing"]
+        C3["bridge-owned gateway runtime"]
+        C4["upstream ACP and gateway adapters"]
     end
 
     subgraph RETURN["Return path"]
-        O["stream events / result"]
-        P["Memory.Record"]
-        Q["Update Thread State"]
-        R["UI stream render"]
-        O --> P --> Q --> R
+        D1["stream events / runtime state"]
+        D2["thread/session state update"]
+        D3["assistant render / settings status"]
     end
 
-    C --> D
-    I -->|"agent"| J
-    I -->|"gateway"| K
-    M --> O
-    N --> O
+    A4 --> B2
+    A4 --> B3
+    A5 --> B1
+    A5 --> B4
+    B1 --> C1
+    B2 --> C2
+    B3 --> C2
+    B4 --> C3
+    C1 --> C4
+    C2 --> C4
+    C3 --> C4
+    C4 --> D1 --> D2 --> D3
 ```
 
-## Provider 真源
+## App-Side Truth Sources
 
-Single-agent provider catalog and availability are owned by
-`xworkmate-bridge`, not by local endpoint presets inside the app.
+### Surface Truth
 
-ACP server addresses and gateway upstreams are also bridge-owned dynamic
-discovery data. The app must not treat concrete endpoints such as
-`https://acp-server.svc.plus/*` or `wss://openclaw.svc.plus` as app-side
-hardcoded truth sources.
+- `feature_flags.yaml -> UiFeatureManifest / AppCapabilities -> Shell / Registry` 是唯一 surface 事实源
+- app 不再把 provider topology、gateway backend、旧模块入口写成 shell 级分类
 
-```mermaid
-flowchart TD
-  subgraph INPUT["Config / discovery input"]
-    A["Settings UI<br/>仅管理 bridge 连接参数<br/>与账号同步元数据"]
-    B["acp.capabilities"]
-    C["bridge capability snapshot<br/>providerCatalog / agent / gateway<br/>dynamic upstream discovery"]
-    A --> B --> C
-  end
+### Provider Truth
 
-  subgraph APPSTATE["App-side truth sources"]
-    D["refreshSingleAgentCapabilitiesRuntimeInternal()"]
-    E["bridgeProviderCatalogInternal<br/>App 内唯一 provider 名单源"]
-    F["singleAgentCapabilitiesByProviderInternal<br/>App 内唯一 provider 可用性源"]
-    G["refreshAcpCapabilitiesRuntimeInternal()"]
-    H["GatewayAcpCapabilities"]
-    I["mergeAcpCapabilitiesIntoMountTargetsRuntimeInternal()"]
-    J["ManagedMountTargetState<br/>gateway capability / discovery state"]
-    C --> D --> E
-    D --> F
-    C --> G --> H --> I --> J
-  end
+- `acp.capabilities.providerCatalog` 是 assistant provider picker 的唯一上游真源
+- 持久化在线程上的 `providerId` 只表示用户历史选择，不负责反向生成 catalog
+- provider unavailable 文案与 resolved provider 都来自 `xworkmate.routing.resolve`
 
-  subgraph UISTATE["UI affordances"]
-    K["bridgeProviderCatalog<br/>Composer / Thread Picker provider source"]
-    L["availableSingleAgentProviders<br/>agent path visibility"]
-    M["visible gateway affordances<br/>只看 bridge capabilities / discovery"]
-    E --> K
-    F --> L
-    J --> M
-  end
+### Gateway Truth
 
-  subgraph EXEC["Execution resolution"]
-    N["setSingleAgentProvider(providerId)<br/>仅写入 thread executionBinding.providerId"]
-    O["singleAgentProviderForSession()"]
-    P["buildExternalAcpRoutingForSessionInternal()"]
-    Q["xworkmate.routing.resolve"]
-    R["resolvedProviderId / unavailableMessage"]
-    S{"unavailable?"}
-    T["executeTask(... resolved routing ...)"]
-    U["provider unavailable UX<br/>直接使用 bridge unavailable message"]
-    K --> N --> O --> P --> Q --> R --> S
-    S -->|"no"| T
-    S -->|"yes"| U
-```
+- gateway runtime 可见性、连接状态、mount target discovery 都由 bridge capability / runtime snapshot 驱动
+- `xworkmate.gateway.*` 是 gateway runtime 的稳定 app-facing 方法族
+- app 不再把 production gateway endpoint、fallback endpoint、local preset 当真源
 
-## 端侧桥接规则
+## Mainline Rules
 
-### Desktop App
+1. Assistant 所有正常任务都先进入 `GoTaskService.executeTask`。
+2. Settings 只管理 bridge connection 参数、account sync 元数据与 gateway/integration affordance。
+3. provider catalog、routing resolve、gateway runtime state 都由 bridge 提供。
+4. bridge 若暴露额外 capability flag 或协作模式，它们属于合同元数据，不自动抬升为 app shell / module taxonomy。
+5. app 不直接调用 `acp-server.svc.plus/*`、`openclaw.svc.plus` 等 upstream 地址。
 
-- Desktop App 直接桥接 Go 代码
-- Desktop 正常执行链路不以“先启动一个本地 HTTP server，再由 Desktop 自己回连”作为目标架构
-- Desktop 的 `sendMessage -> GoTaskService.executeTask -> ACP` 应理解为进程内或直接桥接语义
-- Production cloud mode does not call `xworkmate.providers.sync`
-- Production provider upstreams are bridge-owned, not app-owned
-- Production ACP server list / gateway upstreams are bridge-owned, not app-owned
-- `$INTERNAL_SERVICE_TOKEN` 只允许在 bridge / internal service 层使用，app 不持有
-- 对 app 来说，bridge 是 discovery / config / connect / dialogue 的统一枢纽
+## Removed From Target
 
-### Web / Mobile
+- `TasksPage`、`SkillsPage`、`ModulesPage` 之类独立 surface 叙述
+- `local / remote / preset / fallback` 作为 app 一级执行路径心智
+- “app 自己维护 provider matrix，再把 bridge 当可选后端”的旧设计
+- 通过 alias、compat 分流去保留旧模块入口
 
-- Web / Mobile UI 连接的是 Go 代码启动出来的 server
-- Web / Mobile 通过标准 ACP contract 与该 server 通信
-- 对 Web / Mobile 来说，`/acp` 与 `/acp/rpc` 是稳定的网络协议入口
+## See Also
 
-## 协议约束
-
-### 传输协议
-
-- app 侧当前不再把 `local / remote` 作为执行路径语义
-- Desktop 只区分 `agent / gateway` 两条路径，二者都经由 `xworkmate-bridge` 路由
-- 如果 bridge endpoint 是网络地址，则必须遵守 TLS 要求
-- loopback / non-TLS 只允许作为底层 adapter / 开发态传输细节，不能重新上升为产品执行路径语义
-- app 不直接持有 ACP server upstream 或 gateway upstream 的授权头
-- `Authorization: Bearer $INTERNAL_SERVICE_TOKEN` 属于 bridge / internal service 注入责任
-
-### ACP contract
-
-- websocket endpoint 规范路径：`/acp`
-- RPC endpoint 规范路径：`/acp/rpc`
-- base URL 派生时必须避免重复拼接 `/acp`
-- 以上 endpoint contract 主要适用于 Web / Mobile 与外部 ACP server 的通信语义
-- Desktop 目标态不要求为自身 UI 再额外启动一层本地 HTTP ACP server
-
-## 收敛原则
-
-### Current implementation note
-
-- 当前实现可能仍残留历史分流代码
-- 这些实现痕迹不再代表规范
-
-### Target architecture rule
-
-- 所有正常发送请求都先进入 `GoTaskService.executeTask`
-- 所有任务都先进入 ACP 控制面，再解析到 executor
-- Desktop 采用直接桥接 Go 代码的控制面接入方式
-- Web / Mobile 采用连接 Go server 的控制面接入方式
-- app 侧一级执行路径只保留 `agent / gateway`
-- `multi-agent` 是 bridge / gateway 内部能力，不再作为 app 侧一级路径
-- app 不直接调用 `acp-server.svc.plus/*` 或 `openclaw.svc.plus`
-- 如果需要补全或变更 ACP / gateway upstream，优先在 `xworkmate-bridge` 仓库实现动态发现能力
-
-### Compatibility route (removed from target)
-
-- `openClawTask` 不再属于目标架构
-- `GatewayRuntime`、`Web relay`、`GatewayAcpClient` 只作为 adapter/executor 能力存在
-
-## 分阶段方向
-
-1. 文档口径收敛
-2. Dart 请求模型统一
-3. route 决策内收到 `GoTaskService` / ACP
-4. app 侧 bridge 枢纽与 provider / gateway 适配关系收敛
-5. `multi-agent` 下沉为 bridge 内部能力，而不是 app 一级路径
+- [XWorkmate Core Module Inventory](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/xworkmate-core-module-inventory-2026-04-13.md)
+- [Settings Integration Configuration Model](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/settings-integration-configuration-model.md)
+- [ACP Forwarding Topology](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)
diff --git a/docs/architecture/xworkmate-bridge-migration.md b/docs/architecture/xworkmate-bridge-migration.md
index 53859776..8ba2b9f1 100644
--- a/docs/architecture/xworkmate-bridge-migration.md
+++ b/docs/architecture/xworkmate-bridge-migration.md
@@ -1,60 +1,56 @@
 # XWorkmate Bridge Migration
 
+Last Updated: 2026-04-13
+
 ## Summary
 
-The ACP Bridge Server implementation was migrated out of `xworkmate-app` into the standalone sibling repository `xworkmate-bridge`.
+`xworkmate-app` 已不再承载内嵌 Go bridge 实现；bridge runtime、ACP forwarding、gateway runtime 与 upstream routing 的主设计都已经迁移到独立 sibling repo：
 
-This migration separates the embedded Go bridge/server from the Flutter application repository. The app now depends on the sibling `xworkmate-bridge` repo for the helper/runtime contract instead of carrying an in-repo Go bridge copy.
+- repo: `/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge`
 
-## New Repository
+这个迁移不是兼容壳，而是当前真实的 cross-repo runtime contract。
 
-- Repository path: `/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge`
-- Go module: `xworkmate-bridge`
-- Helper binary output name: `xworkmate-go-core`
+## Current Repo Split
 
-## What Moved
+### xworkmate-app Owns
 
-The previous `xworkmate-app/go/go_core` implementation was migrated to `xworkmate-bridge`, including:
+- `assistant + settings` 双端 surface
+- feature flags、shell、registry、navigation
+- app controller、本地状态编排、secure storage 消费
+- bridge contract client：`GoTaskService`、`GatewayAcpClient`、`ExternalCodeAgentAcpDesktopTransport`
 
-- ACP Bridge HTTP/WebSocket server
-- ACP stdio entrypoint
-- internal routing, dispatch, mounts, shared RPC helpers, gateway runtime support, memory, skills, and toolbridge packages
-- Go tests for ACP routing/contracts and bridge helper behavior
-- legacy static token auth helper code previously stored under `xworkmate-app/go_service`
+### xworkmate-bridge Owns
 
-## What Stayed In xworkmate-app
+- ACP entrypoints 与 forwarding topology
+- provider catalog、routing resolve、gateway runtime
+- upstream ACP adapter / gateway adapter
+- internal service auth injection 与 bridge-owned routing truth
 
-The following app-side concerns remain in `xworkmate-app`:
+## Canonical Cross-Repo Docs
 
-- Flutter UI and settings pages
-- ACP Bridge client-side configuration and secure-storage handling
-- Dart runtime launch/locator logic for the helper binary
+建议按下面顺序阅读当前主链文档：
+
+1. app surface inventory
+   - [XWorkmate Core Module Inventory](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/xworkmate-core-module-inventory-2026-04-13.md)
+2. app control-plane view
+   - [Task Control Plane Unification](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-control-plane-unification.md)
+3. bridge forwarding view
+   - [ACP Forwarding Topology](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)
+4. bridge entrypoint ADR
+   - [ADR: Unified Bridge Entry Points](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/adr-unified-bridge-entrypoints.md)
 
 ## Build Contract
 
-`xworkmate-app` expects the helper artifact named `xworkmate-go-core`.
+`xworkmate-app` 仍然消费名为 `xworkmate-go-core` 的 helper artifact。
 
-This is the current cross-repo runtime contract for local development flows, not a legacy compatibility shim. The helper is built from `xworkmate-bridge` and consumed by `xworkmate-app` outside the shipped app bundle.
+这表示：
 
-## App Repository Changes
-
-In `xworkmate-app`:
-
-- `go/go_core` was removed
-- `scripts/build-go-core.sh` now resolves and builds from sibling repo `xworkmate-bridge`
-- the script supports both normal workspace layout and worktree layout
-- release notes references were updated to point at the new repository
-
-## Validation
-
-Validated during migration:
-
-- `cd xworkmate-bridge && go test ./...`
-- `cd xworkmate-bridge && bash scripts/build-helper.sh`
-- `cd xworkmate-app && bash scripts/build-go-core.sh`
+- helper 从 `xworkmate-bridge` 构建
+- app 负责定位与调用 helper
+- helper 内部的 bridge/runtime 行为以 bridge repo 为准，不再在 app repo 内保留并列设计文档
 
 ## Operational Note
 
-For local development and packaging, `xworkmate-bridge` must exist as a sibling repository next to `xworkmate-app`, unless `XWORKMATE_BRIDGE_DIR` is set explicitly.
-
-At runtime, the app treats bridge-related discovery, provider sync, connection metadata, and ACP conversation forwarding as bridge-owned concerns. Account sync only updates bridge-linked configuration attributes and secure secret references; it does not auto-connect the bridge.
+- 本地开发默认要求 `xworkmate-app` 与 `xworkmate-bridge` 以 sibling repo 形式存在
+- 若目录布局不同，可通过 `XWORKMATE_BRIDGE_DIR` 显式指定 bridge 仓库位置
+- app 端只消费 bridge capability、routing、gateway runtime 合同，不再在本地恢复旧 provider/module 真源
diff --git a/docs/architecture/xworkmate-layered-architecture.md b/docs/architecture/xworkmate-layered-architecture.md
index f528c942..0d79d6c8 100644
--- a/docs/architecture/xworkmate-layered-architecture.md
+++ b/docs/architecture/xworkmate-layered-architecture.md
@@ -1,113 +1,115 @@
-# XWorkmate 整体分层架构
+# XWorkmate Layered Architecture
 
-Last Updated: 2026-04-08
+Last Updated: 2026-04-13
 
-## 目的
+## Purpose
 
-本文件只保留整体分层总览与目录作用，不再把当前兼容旁路写成长期规范。
+本文件只保留当前 `xworkmate-app <-> xworkmate-bridge` 主链的分层总览。
 
-统一口径如下：
+当前仓库已经收敛到：
 
-- `TaskThread` 是线程控制面
-- `GoTaskService.executeTask` 是唯一公开执行入口
-- ACP 是统一控制面
-- `bridge` 是 app 客户端侧的发现 / 配置 / 连接 / 对话枢纽
-- 账户同步只同步 bridge 相关配置属性与安全引用，不负责自动连接
-- 历史旁路与旧的直连叙述不再作为目标架构
+- 顶层 surface 只有 `assistant`、`settings`
+- app 只保留消费 bridge 合同所需的 surface、gate、controller、runtime
+- provider catalog、routing、gateway runtime 能力都由 `xworkmate-bridge` 拥有真源
+- 已删除独立 `tasks / skills / modules / mcp / claw_hub / secrets / ai_gateway / account` 页面壳与 alias 心智
 
-## 总览图
+## Layered View
 
 ```mermaid
-flowchart TB
-    subgraph L1["访问与归属层"]
-        A1["Local user / device"]
-        A2["Web user / browser session"]
-        A3["Remote owner realm"]
+flowchart TD
+    subgraph L1["Surface Visibility"]
+        A1["config/feature_flags.yaml"]
+        A2["UiFeatureManifest / UiFeatureAccess / AppCapabilities"]
+        A3["AppShell / MobileShell / workspace_page_registry.dart"]
+        A4["AssistantPage / SettingsPage"]
     end
 
-    subgraph L2["多端 UI 层"]
-        B1["Desktop / Mobile / Web UI"]
-        B2["AssistantPage / Settings / Tasks"]
+    subgraph L2["App Orchestration"]
+        B1["AppControllerDesktop*"]
+        B2["SettingsController"]
+        B3["GatewaySessionsController"]
+        B4["GatewayChatController"]
+        B5["GatewayAgentsController"]
+        B6["DerivedTasksController"]
+        B7["SkillsController"]
     end
 
-    subgraph L3["线程控制面"]
-        C1["TaskThread"]
-        C2["ownerScope"]
-        C3["workspaceBinding"]
-        C4["executionBinding"]
-        C5["contextState"]
-        C6["lifecycleState"]
+    subgraph L3["Bridge Contract"]
+        C1["GoTaskService.executeTask"]
+        C2["GatewayAcpClient"]
+        C3["ExternalCodeAgentAcpDesktopTransport"]
+        C4["acp.capabilities / xworkmate.routing.resolve / session.* / xworkmate.gateway.*"]
+        C5["managed bridge/account sync contract"]
     end
 
-    subgraph L4["统一任务入口"]
-        D1["AppController*"]
-        D2["GoTaskService.executeTask"]
+    subgraph L4["Bridge And Upstreams"]
+        D1["xworkmate-bridge"]
+        D2["ACP adapters / gateway runtime adapters / upstream services"]
     end
 
-    subgraph L5["ACP Control Plane"]
-        E1["session.start / session.message"]
-        E2["Router.Resolve"]
-        E3["Skills.Resolve"]
-        E4["Memory.Inject / Record"]
-        E5["buildResolvedExecutionParams"]
-    end
-
-    subgraph L6["Bridge / Executors / Adapters"]
-        F1["agent ACP request"]
-        F2["gateway ACP request"]
-        F3["bridge hub<br/>dynamic discovery / config / connect / dialogue / auth injection"]
-        F4["gateway / provider adapters"]
-    end
-
-    A1 --> B1
-    A2 --> B1
-    A3 --> B1
+    A1 --> A2 --> A3 --> A4
+    A4 --> B1
     B1 --> B2
-    B2 --> C1
-    C1 --> C2
-    C1 --> C3
+    B1 --> B3
+    B1 --> B4
+    B1 --> B5
+    B1 --> B6
+    B1 --> B7
+    B1 --> C1
+    B1 --> C2
+    B1 --> C3
+    B2 --> C5
     C1 --> C4
-    C1 --> C5
-    C1 --> C6
-    C1 --> D1
-    D1 --> D2
-    D2 --> E1
-    E1 --> E2
-    E2 --> E3
-    E3 --> E4
-    E4 --> E5
-    E5 --> F1
-    E5 --> F2
-    F1 --> F3
-    F2 --> F3
-    F3 --> F4
+    C2 --> C4
+    C3 --> C4
+    C4 --> D1 --> D2
 ```
 
-## 核心规则
+## Layer Responsibilities
 
-1. UI 不直接决定执行 lane。
-2. `TaskThread` 承载线程级事实，不由页面局部状态拼装。
-3. `GoTaskService.executeTask` 是唯一公开任务入口。
-4. ACP 是统一控制面，负责 routing / skills / memory / resolved execution。
-5. `bridge` 是 app 侧统一枢纽；gateway/provider 适配能力挂在 bridge 后面，不再把历史直连路径写成长期主链。
+### 1. Surface Visibility
 
-## 文档目录
+- `feature_flags.yaml` 是 surface 可见性的唯一声明源
+- `UiFeatureManifest / AppCapabilities` 负责把声明变成当前平台允许能力
+- `AppShell / MobileShell / workspace_page_registry.dart` 只承载已声明且真实存在的 `assistant`、`settings`
+- 不再允许“manifest 已删但 shell/registry 还留旧入口”的双重真源
 
-### 目标规范
+### 2. App Orchestration
 
-- [任务执行链路统一收敛](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-control-plane-unification.md)
-- [ACP Forwarding Topology](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)
+- `AssistantPage` 承载当前线程、任务、技能、结果与 bridge 主链交互
+- `SettingsPage` 承载 bridge connection、account sync、integration affordance
+- app controller 只做最小本地编排，不再维护独立模块壳、假矩阵、旧 alias 分流
+- 任务与技能仍可作为 assistant 内部数据面存在，但不再拥有独立页面地位
 
-### 当前实现观察
+### 3. Bridge Contract
 
-- 当前实现观察不再保留独立主设计文档
-- 如需判断规范，以 [任务执行链路统一收敛](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-control-plane-unification.md) 为准
+- `GoTaskService.executeTask` 是 app 任务链的统一公开入口
+- `acp.capabilities` 提供 bridge-owned capability snapshot
+- `xworkmate.routing.resolve` 返回执行解析结果与 unavailable 信息
+- `session.*` 承载 ACP 会话流
+- `xworkmate.gateway.*` 承载 gateway runtime 连接与请求流
+- 账户同步只同步 bridge 相关配置属性与安全引用，不负责恢复旧模块心智或自动造 catalog
 
-### 边界与适配器说明
+### 4. Bridge And Upstreams
 
-- 适配器边界统一收敛到本文件与主文档，不再保留旧的并列设计稿
+- `xworkmate-bridge` 是 app 唯一公共集成面
+- upstream ACP service、gateway runtime、provider adapter 都是 bridge 内部关注点
+- app 不直接把 upstream URL、provider topology、gateway backend 细节当成自己的 surface taxonomy
+
+## Canonical Cross-Repo Reading Order
+
+建议按下面顺序理解当前主链：
+
+1. [XWorkmate Core Module Inventory](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/xworkmate-core-module-inventory-2026-04-13.md)
+2. [Task Control Plane Unification](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-control-plane-unification.md)
+3. [ACP Forwarding Topology](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)
+4. [ADR: Unified Bridge Entry Points](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/adr-unified-bridge-entrypoints.md)
 
 ## Removed From Target
 
-- 旧的 `openClawTask` 公开语义不再是目标架构的一部分
-- 不再把“客户端直接围绕旧 gateway 默认值运转”写成长期主设计
+以下内容都不再作为当前目标架构的一部分：
+
+- `Tasks / Skills / Modules / MCP / ClawHub / Secrets / AiGateway / Account` 独立 surface
+- 旧 alias destination 与 dormant registry
+- app-side provider preset/backfill/fallback 真源
+- 把 upstream URL、gateway backend 或 provider 拓扑直接暴露成 app 一级模块心智